Text::WikiCreole(3pm)

✨ Text::WikiCreole ✨

okay bestie, buckle up, because this is Text::WikiCreole — the module that takes your Wiki Creole 1.0 markup and turns it into XHTML. it's giving translator, it's giving glow-up, and honestly? it ate 💅

---

🌸 VERSION 🌸

Version 0.07 — yes she's been around a minute, and she's still iconic.

---

🦋 DESCRIPTION 🦋

Text::WikiCreole implements the Wiki Creole markup language, version 1.0, exactly as described over at http://www.wikicreole.org. she reads Creole 1.0 markup, and she hands you back XHTML. that's the whole vibe. no cap 🫶

---

🎀 SYNOPSIS 🎀

use Text::WikiCreole;
creole_plugin \&myplugin; # register custom plugin parser

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

---

👑 FUNCTIONS 👑

💖 creole_parse

self-explanatory, honestly. you hand her a Creole markup string, she hands you HTML. periodt.

💖 creole_plugin

Creole 1.0 supports two plugin syntaxes: << plugin content >> and <<< plugin content >>>

write yourself a function that receives the text between the <<>> delimiters as $_[0] (and not including the delimiters themselves), and returns the text you want displayed. for example, here's a little plugin that converts plugin text to uppercase:

sub uppercase_plugin {
  $_[0] =~ s/([a-z])/\u$1/gs;
  return $_[0];
}
creole_plugin \&uppercase_plugin;

heads up bestie: if you do not register a plugin function, plugin markup will be left as is, including the surrounding << >>.

💖 creole_link

maybe you wanna customize your [[ links ]], like prefixing a hostname, a port, etc. valid.

write a function, similar to the plugin function, which receives the URL part of the link (with leading and trailing whitespace stripped) as $_[0] and returns the customized link. for example, to prepend "http://my.domain/" to pagename:

sub mylink {
  return "http://my.domain/$_[0]";
}
creole_link \&mylink;

💖 creole_customlinks

if you want complete control over links, not just modifying the URL, register your link markup function with creole_link() as above and then call creole_customlinks(). now your function will receive the entire link markup chunk, such as [[ some_wiki_page | page description ]] and must return HTML.

note: this has no effect on "bare" link markup, such as http://cpan.org.

💖 creole_barelink

same purpose as creole_link, but for "bare" link markup.

sub mybarelink {
  return "$_[0].html";
}
creole_barelink \&mybarelink;

💖 creole_custombarelinks

same purpose as creole_customlinks, but for "bare" link markup.

💖 creole_img

same purpose as creole_link, but for image URLs.

sub myimg {
  return "http://my.comain/$_[0]";
}
creole_img \&myimg;

💖 creole_customimgs

similar to creole_customlinks, but for images.

💖 creole_tag

maybe you wanna 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_tag("li", "open", "<li class=myclass>");

or to see all current tags:

print creole_tag();

the tags that may be of interest are:

br          dd          dl
dt          em          h1
h2          h3          h4
h5          h6          hr
ilink       img         inowiki
ip          li          link
mono        nowiki      ol
p           strong      sub
sup         table       td
th          tr          u
ul

those should be self-explanatory, except for inowiki (inline nowiki), ilink (bare links, e.g. http://www.cpan.org), and ip (indented paragraph).

---

🌈 OFFICIAL MARKUP 🌈

here's a lil summary of the official Creole 1.0 markup elements. see http://www.wikicreole.org for the full details, bestie.

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: ~

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. she's flexible like that 🧚

---

⭐ EXTENDED MARKUP ⭐

in addition to OFFICIAL MARKUP, Text::WikiCreole also supports the following markup:

Plugins:

<< plugin >>        ->    whatever you want (see creole_plugin above)
<<< plugin >>>      ->    whatever you want (see creole_plugin above)
    Triple-bracket syntax has priority, in order to allow you to embed
    double-brackets in plugins, such as to embed Perl code.

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>" — shoutout to the legend 💜

---

💀 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>. he will be notified, and then you'll automatically be notified of progress on your bug as changes are made. teamwork, bestie 🎀

---

🍓 SUPPORT 🍓

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

perldoc Text::WikiCreole

you can also look for information at:

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Text-WikiCreole>

• CPAN Ratings

<http://cpanratings.perl.org/d/Text-WikiCreole>

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-WikiCreole>

• Search CPAN

<http://search.cpan.org/dist/Text-WikiCreole>

---

🌟 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 his brain. relatable honestly 😭

---

💅 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.

---

and that's the whole page, bestie — perl v5.34.0, dated 2022-06-28, the Text::WikiCreole(3pm) manpage itself, brought to you by the same energy as ever. now go forth and parse some markup, you absolute main character 👑✨💖