The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-YAWikiFormater-0.50
River stage zero No dependents
1 ++
/ Text::YAWikiFormater

NAME

Text::YAWikiFormater - The great new Text::YAWikiFormater!

VERSION

Version 0.02

SYNOPSIS

    use Text::YAWikiFormater;

    my $wiki = Text::YAWikiFormater->new( body => $wikitext );

    my $html = $wiki->format();

METHODS

new(body => $wikitext)

Creates the YAWikiFormater object. It accepts the parameters:

body

body is the wiki text you want to transform into HTML. This parameter is mandatory.

$wiki->urls( )

urls extracts all the recognized links from the wikitext and returns an data structure that you can use to change the parameters that will be used to generate the final <a> tags on the generated HTML

  my %links = $wiki->urls();
  for my $lnk (value %links) {
    if ($lnk->{_class} eq 'external'
        and $lnk->{href}=~m{wikipedia\.org}) {
      $lnk->{class} = 'external_wikipedia';
      $lnk->{title}.=' (Wikipedia)';
    }
  }
  $wiki->set_links( \%links );

The returned hash contains the link definition text (from your body) as keys and hashes with the data that will be used to create the <a> tags as values. On those hashes the following keys are supported:

href

the url the link will link to (really, the href of the <a> tag).

class

the css class that will be used for this link - this is never ser by Text::YAWikiFormater - it set _class instead, and uses that if class is not set. _class is set to external for any links starting with http:// or https://

title

title is the content of the link.

set_links is the companion of urls( ). It allows you to update the changes you made on the structure returned by urls back in the object, before calling format.

$url = urify($text)

urify is the method used internally to transform wiki titles into wiki urls - it is export to allow to allow the same algorithm to be used by any application that uses the TYAWF to generate URLs from text (title of documents, for instance).

$html = $wiki->format( )

format does all the work - well, centralizes it at least. format gets body from the $wiki object, transforms it and returns the resulting HTML code.

CLASS->register_namespace( $namespace, $info, $override );

register_namespace allow to register namespaces for links.

  Text::YAWikiFormater->register_namespace(
      'gs', # for google search
      { prefix => 'http://www.google.com/search?q=' },
      0
    );

This code would allow to create links like gs:Some Search, and that would link to the google search results page for "Some Search".

$info can be a CODE ref or a HASH ref.

CODEref

When $info is a coderef, it will be called with the link to expand and is expected to return $base, $category, $link. where:

$base

$base is the base for the URL we want to link to.

$category

$category is the category separator, in case that is supported by the website represented by the namespace.

$link can can a relative or an asbolute URL to the resource you want to link to. if $link is an absolute URL, starting with http(s):// the other two values will be ignored and the returned $link will be used.

  Text::YAWikiFormater->register_namespace(
    'tiny',
    sub {
      my ($namespace,$url) = @_;

      #generate or get from cache tinyURL

      return (undef, undef, $tinyurl);
    },
    0
  );
HASHref

When $info is a HASHref, the following keys are supported on that hashref:

prefix

prefix is the base url that will be used to generate the links.

category

category is the category separator. For instance, on Wikipedia, it would be ':'.

This allow you to always use '>' as the category separator in your wiki text and later have that replaced for you to the correct separator needed for you linked website.

CLASS->register_plugin( $name, $handler, $override );

register_plugin allow to extend YAWikiFormater syntax, and to add any type of functionality into the wiki syntax itself.

Text::YAWikiFormater (TYAWF) allows for plugins using the following syntax in the wiki text:

  {{plugintag: params }}

So, when you register a plugin, you are just creating an entry in the resolution table between your plugintag and the CODEref that implements that plugin.

If your plugin doesn't need paramters, it will be called on the wikitext just with:

  {{yourplugin}}

params, when existing, must be a list of valid JSON elements. If it is a JSON object ({}), it will be used, otherwise it will be transformed into a JSON array (by adding '[' in the begining and ']' on the end).

  Text::YAWikiFormater->register_plugin(
      'youtube',
      sub {
        my ($wiki, $plugin, $params) = @_;

        return "<embed ...></embed>";
      },
      0
    );

WIKI SYNTAX

headers

TYAWF supports six levels of headers (h1..h6).

Headers are defined using ! in the begining of the line.

  ! header 1
  !! header 2
  !!! header 3
  !!!! header 4
  !!!!! header 5
  !!!!!! header 6

bold, italic, ...

TYAWF supports bold, italic, underline, strike, and monospaced.

  **bold**
  //italic//
  __underline__
  --deleted--
  ''monospaced''

code

TYAWF supports also code blocks - to define a code block use {{{ and }}}

  {{{
    my $wiki = Text::YAWikiFormater->new( body => $wikitext );
  }}}

  None of the wiki formating works inside of code blocks.

  {{{
    **bold** should be bold, but not inside a code block.
  }}}

blockquote

TYAWF also have support for blockquote. You can create blockquotes starting each line of the quote with '> '.

  > this will be a blockquote

Multiple levels are supported:

  > This is a quote quoting another quote
  > > and this is the quote quoted in the quote.
  >
  > And this is something else
  >

lists

TYAWF supports unordered lists:

  * some item
  * some other item

as well as ordered lists

  # item 1
  # item 2

you can use multiple levels and mix the types:

  * some item
  ** some sub item
  * some ordered items
  *# item 1
  *# item 2
  *## item 2.1

TYAWF supports links from full urls:

  http://www.google.com

As well as creating links using [[ | ]] syntax. TYAWF linking system is tought to be a Wiki linking system, simple, expandable and flexible.

So, lets start with the simple:

  [[Some Page Title]]

This will create a link to some-page-title, the place where is expectable that the page with that title is stored.

Note: This page is in the same directory as the current page. That's because TYAWF also support categories and allows to link to pages in different categories using a similar syntax:

  [[Subcategory > Some Other Page]]

This will link to subcategory/some-other-page - still, a page of a subcategory of the current category.

  [[> Main Category > SubCategory > Some Page]]

This would create a link to /main-category/subcategory/some-page - this time URL relative to the root of the site.

Whenever possible, while generating URLs TYAWF will strip the accents and use the base letters on the URLs.

But, some times, you want to have a different title on your link than the title of the page you want to link to - for those cases TYAWF gives you the option to specify both the title and the link:

  [[Syntax|/wiki/syntax]]

This would create a link to /wiki/syntax with the title Syntax. You can use the same syntax to link to external websites:

  [[Google Search|http://www.google.com]]

And this is before introducting the namespaces - the still missing piece. TYAWF also support namespaces, that work like alias for other websites.

By default TYAWF defines namespaces for wikipedia (wp) and google search (gs), so these are valid links:

  [[wp:Portal>Arts]]

  [[gs:Text YAWikiFormater]]

See above register_namespace on how to register more namespaces.

images

TYAWF also supports images, and those are implemented using the syntax for the plugins - it's simple to do that way as we already would support parameters on the plugins, and those are interesting for images.

  {{image: "/path/to/image.png" }}

  {{image: "/path/to/image.png", size="400x250", alt="Some alternative text" }}

Images plugin supports the following parameters:

  • size, width and heigth

    size is expected to be {width}x{height}. It doesn't override the values of either width or height if they also exist.

  • alt

  • title

toc

toc will generate a list with link to all the headers on the wikitext.

  {{toc}}

It doesn't take any parameters.

plugins

As you can guess from both image and toc, both implemented as if they where plugins, the syntax to call plugins is:

  {{pluginname: params }}

The params are options. you should refer to the plugins documentation to find out which parameters they support - when someone implements any plugins.

WHY, BUT WHY?

ok, now that the documentation is over, I'm sure there are some of you who may ask I do we need, in the good perl tradition, Yet Another Wiki Formater.

The main reason is that I didn't like the syntax of any of those I tested.

AUTHOR

Marco Neves, <perl-cpan at fwd.avidmind.net>

BUGS

Please report any bugs or feature requests to bug-text-yawikiformater at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-YAWikiFormater. 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::YAWikiFormater

You can also look for information at:

ACKNOWLEDGEMENTS

I would like to acknowledge that I got a lot of ideas from a lot of projects, probably the one I got more from was dokuwiki, even if in some cases I did exactly the oposite of what they do.

MAYBE TODO

a few plugins

Plugin to add webvideos (youtube, dailymotion, etc), maybe a few more - give me ideas.

a few more tests

Even if the basics of the syntax is covered by the current few tests, a few things are surelly not being tested yet - also I'm sure that with time we will be able to find a few test cases that break the formater - we'll need to create tests for thoses and fix them.

Send me the tests and I'll fix them.

webapp using TYAWF

That's actually the pet project I was working on when I started this one. It'll be online soon, I hope - yes, it will be opensource as well.

LICENSE AND COPYRIGHT

Copyright 2013 Marco Neves.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.