man HTML::WikiConverter () - An HTML to wiki markup converter

NAME

HTML::WikiConverter - An HTML to wiki markup converter

SYNOPSIS

  use HTML::WikiConverter;
  my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' );
  print $wc->html2wiki( $html );

DESCRIPTION

CWHTML::WikiConverter is an HTML to wiki converter. It can convert HTML source into a variety of wiki markups, called wiki dialects. The following dialects are supported: 

  DokuWiki
  Kwiki
  MediaWiki
  MoinMoin
  Oddmuse
  PhpWiki
  PmWiki
  SlipSlap
  TikiWiki
  UseMod
  WakkaWiki

Note that while dialects usually produce satisfactory wiki markup, not all features of all dialects are supported. Consult individual dialects' documentation for details of supported features. Suggestions for improvements, especially in the form of patches, are very much appreciated.

METHODS

new
  my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );
Returns a converter for the specified dialect. Dies if CW$dialect is not provided or is not installed on your system. Attributes may be specified in CW%attrs; see ATTRIBUTES for a list of recognized attributes.
html2wiki
  $wiki = $wc->html2wiki( $html );
  $wiki = $wc->html2wiki( html => $html );
  $wiki = $wc->html2wiki( file => $file );
  $wiki = $wc->html2wiki( file => $file, slurp => $slurp );
Converts HTML source to wiki markup for the current dialect. Accepts either an HTML string CW$html or an HTML file CW$file to read from. You may optionally bypass CWHTML::Parser's incremental parsing of HTML files (thus slurping the file in all at once) by giving CW$slurp a true value.
dialect
  my $dialect = $wc->dialect;
Returns the name of the dialect used to construct this CWHTML::WikiConverter object.
parsed_html
  my $html = $wc->parsed_html;
Returns CWHTML::TreeBuilder's representation of the last-parsed syntax tree, showing how the input HTML was parsed internally. This is often useful for debugging.

ATTRIBUTES

You may configure CWHTML::WikiConverter using a number of attributes. These may be passed as arguments to the CWnew constructor, or can be called as object methods on a CWHTML::WikiConverter object.

base_uri
URI to use for converting relative URIs to absolute ones. This effectively ensures that the CWsrc and CWhref attributes of image and anchor tags, respectively, are absolute before converting the HTML to wiki markup, which is necessary for wiki dialects that handle internal and external links separately. Relative URLs are only converted to absolute ones if the CWbase_uri argument is present. Defaults to CWundef.
wiki_uri
URI used in determining which links are wiki links. This assumes that URLs to wiki pages are created by joining the CWwiki_uri with the (possibly escaped) wiki page name. For example, the English Wikipedia would use CW"http://en.wikipedia.org/wiki/", while Ward's wiki would use CW"http://c2.com/cgi/wiki?". Defaults to CWundef.
wrap_in_html
Helps CWHTML::TreeBuilder parse HTML fragments by wrapping HTML in CW<html> and CW</html> before passing it through CWhtml2wiki. Boolean, disabled by default.
strip_comments
Removes HTML comments from the input before conversion to wiki markup. Boolean, enabled by default.
strip_head
Removes the HTML CWhead element from the input before converting. Boolean, enabled by default.
strip_scripts
Removes all HTML CWscript elements from the input before converting. Boolean, enabled by default.

Some dialects allow other parameters in addition to these. Consult individual dialect documentation for details.

DIALECTS

CWHTML::WikiConverter can convert HTML into markup for a variety of wiki dialects. The rules for converting HTML into a given dialect are specified in a dialect module registered in the CWHTML::WikiConverter:: namespace. For example, the rules for the MediaWiki dialect are provided in CWHTML::WikiConverter::MediaWiki, while PhpWiki's rules are specified in CWHTML::WikiConverter::PhpWiki.

This section is intended for dialect module authors.

Conversion rules

To interface with CWHTML::WikiConverter, dialect modules must define a single CWrules class method. It returns a reference to a hash of rules that specify how individual HTML elements are converted to wiki markup.

Supported rules

The following rules are recognized: 

  start
  end


  preserve
  attributes
  empty


  replace
  alias


  block
  line_format
  line_prefix


  trim

Simple rules method

For example, the following CWrules method could be used for a wiki dialect that uses CW*asterisks* for bold and CW_underscores_ for italic text: 

  sub rules {
    return {
      b => { start => '*', end => '*' },
      i => { start => '_', end => '_' }
    };
  }

Aliases

To add CW<strong> and CW<em> as aliases of CW<b> and CW<i>, use the CWalias rule: 

  sub rules {
    return {
      b => { start => '*', end => '*' },
      strong => { alias => 'b' },


      i => { start => '_', end => '_' },
      em => { alias => 'i' }
    };
  }

Note that if you specify the CWalias rule, no other rules are allowed.

Blocks

Many dialects separate paragraphs and other block-level elements with a blank line. To indicate this, use the CWblock rule: 

  p => { block => 1 }

To better support nested block elements, if a block elements are nested inside each other, blank lines are only added to the outermost element.

Line formatting

Many dialects require that the text of a paragraph be contained on a single line of text. Or perhaps that a paragraph cannot contain any newlines. These options can be specified using the CWline_format rule, which can be assigned the value CW"single", CW"multi", or CW"blocks".

If the element must be contained on a single line, then the CWline_format rule should be CW"single". If the element can span multiple lines, but there can be no blank lines contained within, then it should be CW"multi". If blank lines (which delimit blocks) are allowed, then use CW"blocks". For example, paragraphs are specified like so in the MediaWiki dialect: 

  p => { block => 1, line_format => 'multi', trim => 'both' }

Trimming whitespace

The CWtrim rule specifies whether leading or trailing whitespace (or both) should be stripped from the element. To strip leading whitespace only, use CW"leading"; for trailing whitespace, use CW"trailing"; for both, use the aptly named CW"both"; for neither (the default), use CW"none".

Line prefixes

Some elements require that each line be prefixed with a particular string. For example, preformatted text in MediaWiki s prefixed with a space: 

  pre => { block => 1, line_prefix => ' ' }

Replacement

In some cases, conversion from HTML to wiki markup is as simple as string replacement. To replace a tag and its contents with a particular string, use the CWreplace rule. For example, in PhpWiki, three percent signs '%%%' represents a linebreak CW<br />, hence the rule: 

  br => { replace => '%%%' }

(The CWreplace rule cannot be used with any other rule.)

Preserving HTML tags

Some dialects allow a subset of HTML in their markup. HTML tags can be preserved using the CWpreserve rule. For example, to allow CW<font> tag in wiki markup: 

  font => { preserve => 1 }

Preserved tags may also specify a list of attributes that may also passthrough from HTML to wiki markup. This is done with the CWattributes option: 

  font => { preserve => 1, attributes => [ qw/ font size / ] }

(The CWattributes rule must be used alongside the CWpreserve rule.)

Some HTML elements have no content (e.g. line breaks, images), and should be preserved specially. To indicate that a preserved tag should have no content, use the CWempty rule. This will cause the element to be replaced with CW"<tag />", with no end tag. For example, MediaWiki handles line breaks like so: 

  br => {
    preserve => 1,
    attributes => qw/ id class title style clear /,
    empty => 1
  }

This will convert, e.g., CW"<br clear='both'>" into CW"<br clear='both' />". Without specifying the CWempty rule, this would be converted into the undesirable CW"<br clear='both'></br>".

The CWempty rule must be combined with the CWpreserve rule.

Dynamic rules

Instead of simple strings, you may use coderefs as values for the CWstart, CWend, CWreplace, and CWline_prefix rules. If you do, the code will be called as a method on the current CWHTML::WikiConverter dialect object, and will be passed the current HTML::Element node and a hashref of the dialect's rules for processing elements of that type.

For example, MoinMoin handles lists like so: 

  ul => { line_format => 'multi', block => 1, line_prefix => '  ' }
  li => { start => \&_li_start, trim => 'leading' }
  ol => { alias => 'ul' }

And then defines CW_li_start: 

  sub _li_start {
    my( $self, $rules ) = @_;
    my $bullet = '';
    $bullet = '*'  if $node->parent->tag eq 'ul';
    $bullet = '1.' if $node->parent->tag eq 'ol';
    return "\n$bullet ";
  }

This ensures that every unordered list item is prefixed with CW* and every ordered list item is prefixed with CW1., required by the MoinMoin formatting rules. It also ensures that each list item is on a separate line and that there is a space between the prefix and the content of the list item.

Rule validation

Certain rule combinations are not allowed. For example, the CWreplace and CWalias rules cannot be combined with any other rules, and CWattributes can only be specified alongside CWpreserve. Invalid rule combinations will trigger an error when the CWHTML::WikiConverter object is instantiated.

Dialect attributes

The attributes that are recognized by the CWHTML::WikiConverter are given in the CWattributes method, which returns a hash of attribute names and their defaults. Dialects that wish to alter the set of recognized attributes must override this method. For example, to add a boolean attribute called CWcamel_case with is disabled by default, a dialect would define an CWattributes method like so: 

  sub attributes { (
    shift->SUPER::attributes,
    camel_case => 0
  ) }

Attributes defined liks this are given accessor and mutator methods via Perl's AUTOLOAD mechanism, so you can later say: 

  my $ok = $wc->camel_case; # accessor
  $wc->camel_case(0); # mutator

Preprocessing

The first step in converting HTML source to wiki markup is to parse the HTML into a syntax tree using HTML::TreeBuilder. It is often useful for dialects to preprocess the tree prior to converting it into wiki markup. Dialects that need to preprocess the tree define a CWpreprocess_node method that will be called on each node of the tree (traversal is done in pre-order). As its only argument the method receives the current HTML::Element node being traversed. It may modify the node or decide to ignore it. The return value of the CWpreprocess_node method is discarded.

Built-in preprocessors

Because they are commonly needed, two preprocessing steps are automatically carried out by CWHTML::WikiConverter, regardless of the dialect: 1) relative URIs in images and links are converted to absolute URIs (based upon the CWbase_uri parameter), and 2) ignorable text (e.g. between CW</td> and CW<td>) is discarded.

CWHTML::WikiConverter also provides additional preprocessing steps that may be explicitly enabled by dialect modules.

strip_aname
Removes from the HTML input any anchor elements that do not contain an CWhref attribute.
caption2para
Removes table captions and reinserts them as paragraphs before the table.

Dialects may apply these optional preprocessing steps by calling them as methods on the dialect object inside CWpreprocess_node. For example: 

  sub preprocess_node {
    my( $self, $node ) = @_;
    $self->strip_aname($node);
    $self->caption2para($node);
  }

Postprocessing

Once the work of converting HTML, it is sometimes useful to postprocess the resulting wiki markup. Postprocessing can be used to clean up whitespace, fix subtle bugs in the markup that can't otherwise be done in the original conversion, etc.

Dialects that want to postprocess the wiki markup should define a CWpostprocess_output object method that will be called just before theCWhtml2wiki method returns to the client. The method will be passed a single argument, a reference to the wiki markup. It may modify the wiki markup that the reference points to. Its return value is discarded.

For example, to convert a series of line breaks to be replaced with a pair of newlines, a dialect might implement this: 

  sub postprocess_output {
    my( $self, $outref ) = @_;
    $$outref =~ s/<br>\s*<br>/\n\n/g;
  }

(This example assumes that HTML line breaks were replaced with CW<br> in the wiki markup.)

Dialect utility methods

CWHTML::WikiConverter defines a set of utility methods for use by dialect modules.

get_elem_contents
  my $wiki = $wc->get_elem_contents( $node );
Converts the contents of CW$node into wiki markup and returns the resulting wiki markup.
get_wiki_page
  my $title = $wc->get_wiki_page( $url );
Attempts to extract the title of a wiki page from the given URL, returning the title on success, CWundef on failure. If CWwiki_uri is empty, this method always return CWundef. Assumes that URLs to wiki pages are constructed using "<wiki-uri><page-name>".
is_camel_case
  my $ok = $wc->is_camel_case( $str );
Returns true if CW$str is in CamelCase, false otherwise. CamelCase-ness is determined using the same rules as CGI::Kwiki's formatting module uses.
get_attr_str
  my $attr_str = $wc->get_attr_str( $node, @attrs );
Returns a string containing the specified attributes in the given node. The returned string is suitable for insertion into an HTML tag. For example, if CW$node refers to the HTML 
  <style id="ht" class="head" onclick="editPage()">Header</span>
and CW@attrs contains CW"id" and CW"class", then CWget_attr_str will return CW'id="ht" class="head"'.

BUGS

Please report bugs using http://rt.cpan.org.

SEE ALSO

HTML::Tree, HTML::Element

AUTHOR

David J. Iberri <diberri@cpan.org>

COPYRIGHT

Copyright (c) 2004-2005 David J. Iberri

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

See http://www.perl.com/perl/misc/Artistic.html