README

include 'WikiCreole.php';
$parser = new WikiCreole(array(
    'urlBase' => '/wiki/',
    'imgBase' => '/media/',
    ),
    $list_of_existing_page_slugs
);
$html = $parser->parse($wiki_markup);

Features

Parses everything in the Creole 1.0 spec.
Parses creole additions for , , and . See discussion below about these tags.
Automatic prepending of a base URL or path to link or image slug. See and option keys below.
Automatic conversion of slugs to links to other wiki pages. This removes spaces and other characters not allowed in a URL path.
Control over markup applied to all link tags, in case you would like to style links internal to and external to your site differently. See the linkFormat* option keys below.
Macros. Run a user defined function on text inside the macro markup tag .

Setting Options

The class requires an array of options to be passed as the first argument in it's constructor. The options array follows a 'keyname' => 'value' format. There are currently six valid key names.

: A URL string that will be prepended to any wiki links, link tags where the target is just a page name and is not a full URL with scheme & host name. An empty string will prepend nothing. You can pass a path for absolute path URLs or a scheme + host name + optionally a path for full absolute URLs.
: A URL string that will be prepended to any wiki images, image tags where the target is just a filename or path & filename, not a full URL with scheme & host name. The same rules for absolute paths & full URLs as apply.
: Specifies a format to use when creating <a> tags for link tags that have a full URL. This is most usefull if you want to apply a special class to external links so they are formatted differently. The format string will be passed to PHP's sprintf function. The format can use two numbered placeholders: %1$s - The URL, %2$s - The text part of the link. The default format is . As an alternative you can pass a valid PHP callback (Closures work here if you are on PHP 5.3) and your function will be called with the URL as the first argument and the text as the second.
: Same as except this format will be used for all links to other wiki/blog/CMS pages, where just the page title was supplied. The default format is . You can also pass a PHP callback or Closure here.
: Same as except if you supply a list of existing pages and the page in the link tag does not yet exist, this format will be applied. This is especially usefull for specifcally styling pages that are in need of being created. The default format is . You can also pass a PHP callback or Closure here.
: is applied to URLS which appear in a body of text but are not contained in a tag. Unlike the above three formats this one is a format string for preg_replace. There is also only one placeholder, $0, though it can be repeated. The default format is . Callback and Closures don't work here yet.
: Off by default. Allows extra information to be printed in case parsing goes wrong. If the parsing of a block level element goes wrong you will get back text with placeholders instead of that block level element. Setting to will print out all of the strings which could not be remerged at the end of the HTML string inside a PRE tag. This options is really only useful to developers and hopefully not needed much anymore.

Any of the above options can also be set with the method.

A second, optional, constructor argument accepts an array containing a list of existing pages. The values of the array (keys are ignored) must be just the URL slug for a page after any illegal characters have stripped and formatting been applied (i.e. spaces to dashes). See the method and property for more info on the URL formatting. I realize different software packages may have different rules for URL formatting/preparation. This is something that may become pluggable in the future.

Known issues

Multi-line list items do not work.
Putting }}} inside a no wiki tag will trip up the parser.

Creole Additions

I like to use strikethrough so I added and then also as markup formats. The rendered HTML uses a tag with style applied to be compatible with HTML4/XHTML1 Strict. Note however that and are valid HTML5 tags. I may add a flag to toggle between these two options in the future.
I've also implemented the addition which wraps the text in tags (this was supposed to be but that was dropped in HTML5).

Block Level Macros

You register your marco by calling the method. Again the $callback can be any valid PHP callable including a Closure. The parser will match a block level macro with the following sytax:

<<macroName arg1 arg2
This is some paragraph text.
>>

Arguments for your macro function should be separated by spaces and must appear on the first line. The body of the macro follows on the next lines until the closing marker is found. When your macro is called the arguments will be passed in the order they were presented. The body will always be last. Whatever your function returns will be placed in the markup in place of the macro tag. Inline macros are next on my development list.

Plans for the future

Fix the stuff in known issues.
Inline macros.
Possible automatic creation of anchors on headings (this is a common usage pattern).
Implement a strict/non-strict mode that would toggle between HTML4/XHTML1 Strict compliance and tags allowed in HTML 5.
Pluggable formatting for free link.
Pluggable transformation of plain text wiki links into page slugs.

paulyg / wikicreole

Maintainers

Details