/ 
HTML-WikiConverter-0.55
River stage two • 22 direct dependents • 24 total dependents
/ HTML::WikiConverter

NAME

HTML::WikiConverter - Convert HTML to wiki markup

SYNOPSIS

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

DESCRIPTION

HTML::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
PbWiki
PhpWiki
PmWiki
SlipSlap
TikiWiki
UseMod
WakkaWiki
WikkaWiki

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 wiki dialect. Dies if $dialect is not provided or its dialect module is not installed on your system. Additional attributes may be specified in %attrs; see "ATTRIBUTES" for a list of recognized attributes.

html2wiki

$wiki = $wc->html2wiki( $html, %attrs );
$wiki = $wc->html2wiki( html => $html, %attrs );
$wiki = $wc->html2wiki( file => $file, %attrs );

Converts HTML source to wiki markup for the current dialect. Accepts either an HTML string $html or an HTML file $file to read from.

Attributes assigned in %attrs (see "ATTRIBUTES") will override previously assigned attributes for the duration of the html2wiki() call.

parsed_html

my $html = $wc->parsed_html;

Returns HTML::TreeBuilder's string representation of the last-parsed syntax tree, showing how the input HTML was parsed internally. Useful for debugging.

available_dialects

my @dialects = HTML::WikiConverter->available_dialects;

Returns a list of all available dialects by searching the directories in @INC for HTML::WikiConverter:: modules.

ATTRIBUTES

You may configure HTML::WikiConverter using a number of attributes. These may be passed as arguments to the new constructor, or can be called as object methods on an H::WC object.

Some dialects allow other attributes in addition to those below, and may override the attributes' default values. Consult the dialect's documentation for details.

dialect

(Required) Dialect to use for converting HTML into wiki markup. See the "DESCRIPTION" section above for a list of dialects. new() will fail if the dialect given is not installed on your system. Use available_dialects() to list installed dialects.

base_uri

URI to use for converting relative URIs to absolute ones. This effectively ensures that the src and href 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 base_uri argument is present. Defaults to undef.

wiki_uri

Takes a URI, regular expression, or coderef (or a reference to an array of elements of these types) used to determine which links are to wiki pages: a link whose href parameter matches wiki_uri will be treated as a link to a wiki page. In addition, wiki_uri will be used to extract the title of the wiki page. The way this is done depends on whether the wiki_uri has been set to a string, regexp, or coderef. The default is undef, meaning that all links will be treated as external links by default.

If wiki_uri is a string, it is assumed that URIs to wiki pages are created by joining the wiki_uri with the wiki page title. For example, the English Wikipedia might use "http://en.wikipedia.org/wiki/" as the value of wiki_uri. Ward's wiki might use "http://c2.com/cgi/wiki?".

wiki_uri can also be a regexp that matches URIs to wiki pages and also extracts the page title from them. For example, the English Wikipedia might use qr~http://en\.wikipedia\.org/w/index\.php\?title\=([^&]+)~.

wiki_uri can also be a coderef that takes the current HTML::WikiConverter object and a URI object. It should return the title of the wiki page extracted from the URI, or undef if the URI doesn't represent a link to a wiki page.

As mentioned above, the wiki_uri attribute can either take a single URI/regexp/coderef element or it may be assigned a reference to an array of any number of these elements. This is useful for wikis that have different ways of creating links to wiki pages. For example, the English Wikipedia might use:

my $wc = new HTML::WikiConverter(
  dialect => 'MediaWiki',
  wiki_uri => [
    'http://en.wikipiedia.org/wiki/',
    sub { pop->query_param('title') } # requires URI::QueryParam
  ]
);

wrap_in_html

Helps HTML::TreeBuilder parse HTML fragments by wrapping HTML in <html> and </html> before passing it through html2wiki. Boolean, enabled by default.

encoding

Specifies the encoding used by the HTML to be converted. Also determines the encoding of the wiki markup returned by the html2wiki method. Defaults to 'utf8'.

strip_tags

A reference to an array of tags to be removed from the HTML input prior to conversion to wiki markup. Tag names are the same as those used in HTML::Element. Defaults to [ '~comment', 'head', 'script', 'style' ].

preprocess

Code reference that gets invoked after HTML is parsed but before it is converted into wiki markup. The callback is passed two arguments: the HTML::WikiConverter object and a HTML::Element pointing to the root node of the HTML tree created by HTML::TreeBuilder.

remove_empty

Removes elements containing no content (unless those elements legitimately contain no content, such as is the case for br and img elements, for example). Defaults to false.

slurp

When parsing HTML files, bypasses HTML::Parser's incremental parsing (thus slurping the file in all at once). If File::Slurp is installed, its read_file() function will be used to perform slurping; otherwise, a common Perl idiom will be used for slurping instead. This option has no effect if all you do is call html2wiki() with a single HTML string argument instead of a file.

escape_entities

Potentially unsafe characters found within text nodes can be automatically encoded into their corresponding HTML entities, a feature enabled by giving the escape_entities a true value. Defaults to true.

ADDING A DIALECT

Consult HTML::WikiConverter::Dialects for documentation on how to write your own dialect module for HTML::WikiConverter. Or if you're not up to the task, drop me an email and I'll have a go at it when I get a spare moment.

SEE ALSO

HTML::Tree, Convert::Wiki

AUTHOR

David J. Iberri, <diberri@cpan.org>

BUGS

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

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Tatsuhiko Miyagawa for suggesting Bundle::HTMLWikiConverter as well as providing code for the available_dialects() class method.

My thanks also goes to Martin Kudlvasr for catching (and fixing!) a bug in the logic of how HTML files were processed.

Big thanks to Dave Schaefer for the PbWiki dialect and for the idea behind the new attributes() implementation.

COPYRIGHT & LICENSE

Copyright 2006 David J. Iberri, all rights reserved.

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