The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-WikiCreole
River stage one • 3 direct dependents • 4 total dependents
++
/ Text::WikiCreole

NAME

Text::WikiCreole - Convert Wiki Creole 1.0 markup to XHTML

VERSION

Version 0.01

DESCRIPTION

Text::WikiCreole implements the Wiki Creole markup language, version 1.0, as described at http://www.wikicreole.org. It reads Creole 1.0 markup and returns XHTML.

SYNOPSIS

 use Text::WikiCreole;
 creole_extend;            # use optional extensions to Creole 1.0
 creole_plugin \&myplugin; # register custom plugin parser

 my $html = creole_parse($creole_text);
 ...

FUNCTIONS

creole_parse

    Self-explanatory.  Takes a Creole markup string argument and 
    returns HTML.

creole_extend

    By default, Text::WikiCreole implements strict Creole 1.0,
    summarized in STRICT MARKUP below.

    creole_extend() enables support for the additional markup 
    described in EXTENDED MARKUP below.

creole_plugin

    Creole 1.0 supports a plugin syntax: << plugin content >>

    Write a function that receives the text between the <<>> 
    delimiters as $_[0] (and not including the delimiters) and 
    returns the text to be displayed.  For example, here is a 
    simple plugin that converts plugin text to uppercase:

    sub uppercase_plugin {
      $_[0] =~ s/([a-z])/\u$1/gs;
      return $_[0];
    }
    creole_plugin \&uppercase_plugin;
    You may wish to customize [[ links ]], such as to prefix a hostname,
    port, etc.

    Write a function, similar to the plugin function, which receives the
    <a href="pagename"> part of the link as $_[0] and returns the 
    customized link.  For example, to prepend "http://my.domain/" to
    pagename:

    sub mylink {
      $_[0] =~ s%href=\"%href=\"http://my.comain/%;
      return $_[0];
    }
    creole_link \&mylink;

VARIABLES

%creole_tags

    You may wish to customize the opening and/or closing tags
    for the various bits of Creole markup.  For example, to
    assign a CSS class to list items:
 
    $creole_tags{li}{open} = "<li class=myclass>";

    Or to see the current open tag for indented paragraphs:

    print "$creole_tags{ip}{open}\n";

    The tags that may be of interest are:

    hr          br          li
    ol          ul          table
    tr          th          td
    strong      em          inowiki (inline nowiki syntax)
    nowiki      sup         sub
    u           p           ip (indented paragraphs)
    dl          dt          mono (monospace)
    dd          h1          h2
    h3          h4          h5
    h6          a           img

STRICT MARKUP

    Here is a summary of the official Creole 1.0 markup 
    elements.  See http://www.wikicreole.org for the full
    details.

    Headings:
    = heading 1       ->    <h1>heading 1</h1>
    == heading 2      ->    <h2>heading 2</h2>
    ...
    ====== heading 6  ->    <h6>heading 6</h6>
   
    Various inline markup:
    ** bold **        ->    <strong> bold </strong>
    // italics //     ->    <em> italics </em>
    **// both //**    ->    <strong><em> both </em></strong>
    [[ link ]]        ->    <a href="link">link</a>
    [[ link | text ]] ->    <a href="link">text</a>
    http://cpan.org   ->    <a href="http://cpan.org">http://cpan.org</a>
    line \\ break     ->    line <br /> break
    {{img.jpg|alt}}   ->    <img src="img.jpg" alt="alt">

    Lists:
    * unordered list        <ul><li>unordered list</li>
    * second item               <li>second item</li>
    ## nested ordered  ->       <ol><li>nested ordered</li>
    *** uber-nested                 <ul><li>uber-nested</li></ul>
    * back to level 1           </ol><li>back to level 1</li></ul>

    Tables:
    |= h1 |= h2       ->    <table><tr><th>h1</th><th>h2</th></tr>
    |  c1 |  c2             <tr><td>c1</td><td>c2</td></tr></table>

    Nowiki (Preformatted):
    {{{                     <pre>
      ** not bold **          ** not bold **
      escaped HTML:   ->      escaped HTML:
      <i> test </i>           &lt;i&gt; test &lt;/i&gt;
    }}}                     <pre>

    {{{ inline\\also }}} -> <tt>inline\\also</tt>

    Escape Character:
    ~** not bold **    ->    ** not bold **
    tilde: ~~          ->    tilde: ~

    Plugins:
    << plugin >>       ->    whatever you want

    Paragraphs are separated by other blocks and blank lines.  
    Inline markup can usually be combined, overlapped, etc.  List
    items and plugin text can span lines.

EXTENDED MARKUP

    In addition to STRICT MARKUP, Text::WikiCreole optionally supports
    the following markup:

    Inline:
    ## monospace ##     ->    <tt> monospace </tt>
    ^^ superscript ^^   ->    <sup> superscript </sup>
    ,, subscript ,,     ->    <sub> subscript </sub>
    __ underline __     ->    <u> underline </u>
    (TM)                ->    &trade;
    (R)                 ->    &reg;
    (C)                 ->    &copy;
    ...                 ->    &hellip;
    --                  ->    &ndash;

    Indented Paragraphs:
    :this               ->    <div style="margin-left:2em"><p>this
    is indented               is indented</p>
    :: more indented          <div style="margin-left:2em"><p> more
                              indented</div></div>

    Definition Lists:
    ; Title             ->    <dl><dt>Title</dt>
    : item 1 : item 2         <dd>item 1</dd><dd>item 2</dd>
    ; Title 2 : item2a        <dt>Title 2</dt><dd>item 2a</dd></dl>

AUTHOR

Jason Burnett, <jason at jnj.org>

BUGS

Please report any bugs or feature requests to bug-text-wikicreole at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-WikiCreole. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Text::WikiCreole

You can also look for information at:

ACKNOWLEDGEMENTS

The parsing algorithm is basically the same as (and inspired by) the one in Document::Parser. Document::Parser is OO and is, as such, incompatible with my brain.

COPYRIGHT & LICENSE

Copyright 2007 Jason Burnett, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.