NAME¶
HTML::WikiConverter - Convert HTML to wiki markup
SYNOPSIS¶
use HTML::WikiConverter;
my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' );
print $wc->html2wiki( html => '<b>text</b>' ), "\n\n";
# A more complete example
my $html = qq(
<p><i>Italic</i>, <b>bold</b>, <span style="font-weight:bold">also bold</span>, etc.</p>
);
my @dialects = HTML::WikiConverter->available_dialects;
foreach my $dialect ( @dialects ) {
my $wc = new HTML::WikiConverter( dialect => $dialect );
my $wiki = $wc->html2wiki( html => $html );
printf "The %s dialect gives:\n\n%s\n\n", $dialect, $wiki;
}
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.
Since version 0.50 all dialects were separated out from HTML:WikiConverter.
Please install the independent dialect packages as needed.
METHODS¶
new¶
my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );
Returns a converter for the specified wiki dialect. Croaks 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
complete list.
html2wiki¶
$wiki = $wc->html2wiki( $html, %attrs );
$wiki = $wc->html2wiki( html => $html, %attrs );
$wiki = $wc->html2wiki( file => $file, %attrs );
$wiki = $wc->html2wiki( uri => $uri, %attrs );
Converts HTML source to wiki markup for the current dialect. Accepts either an
HTML string $html, an file $file, or a URI <$uri> to read from.
Attributes assigned in %attrs (see "ATTRIBUTES") will augment or
override previously assigned attributes for the duration of the
"html2wiki()" call.
elem_search_lineage¶
my $ancestor = $wc->elem_search_lineage( $node, \%rules );
Searches the lineage of $node and returns the first ancestor node that has rules
matching those specified in %rules, or "undef" if no matching node
is found.
For example, to find out whether $node has an ancestor with rules matching
"{ block =>1 }", one could use:
if( $wc->elem_search_lineage( $node, { block => 1 } ) ) {
# do something
}
given_html¶
my $html = $wc->given_html;
Returns the HTML passed to or fetched (ie, from a file or URI) by the last
"html2wiki()" method call. Useful for debugging.
parsed_html¶
my $parsed_html = $wc->parsed_html;
Returns a string containing the post-processed HTML from the last
"html2wiki" call. Post-processing includes parsing by
HTML::TreeBuilder, CSS normalization by HTML::WikiConverter::Normalizer, and
calls to the "preprocess" and "preprocess_tree" dialect
methods.
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.
rules_for_tag¶
my $rules = $wc->rules_for_tag( $tag );
Returns the rules that will be used for converting elements of the given tag.
Follows "alias" references. Note that the rules used for a
particular tag may depend on the current set of attributes being used.
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.
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 URIs are only converted to absolute ones if the
"base_uri" argument is present. Defaults to "undef".
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.
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".
escape_entities¶
Passing "escape_entities" a true value uses HTML::Entities to encode
potentially unsafe '<', '>', and '&' characters. Defaults to true.
p_strict¶
Boolean indicating whether HTML::TreeBuilder will use strict handling of
paragraph tags when parsing HTML input. (This corresponds to the
"p_strict" method in the HTML::TreeBuilder module.) Enabled by
default.
Boolean indicating whether tags with no attributes ("naked" tags)
should be removed and replaced with their content. By default, this only
applies to non-semantic tags such as <span>, <div>, etc., but does
not apply to semantic tags such as <strong>, <address>, etc. To
override this behavior and specify the tags that should be considered for
passthrough, provide this attribute with a reference to an array of tag names.
Defaults to false, but you'll probably want to enable it.
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.
slurp¶
Boolean that, if enabled, bypasses "HTML::Parser"'s incremental
parsing (thus
slurping the file in all at once) of files when reading
HTML files. 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 is only used if you call
"html2wiki()" with the "file" argument.
Strips elements containing no content (unless those elements legitimately
contain no content, such as is the case for "br" and "img"
tags, for example). Defaults to false.
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'
]".
user_agent¶
Specifies the LWP::UserAgent object to be used when fetching the URI passed to
"html2wiki()". If unspecified and "html2wiki()" is passed
a URI, a default user agent will be created.
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 interpreted as a URI template, and it
will be assumed that URIs to wiki pages are created by joining
"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?". These examples use an absolute
"wiki_uri", but a relative URI can be used as well; an absolute URI
will be created based on the value of "base_uri". For example, the
Wikipedia example above can be rewritten using "base_uri" of
"
http://en.wikipedia.org" and a "wiki_uri" of
"/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.
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:
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/HTML-WikiConverter>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/HTML-WikiConverter>
- •
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-WikiConverter>
- •
- Search CPAN
<http://search.cpan.org/dist/HTML-WikiConverter>
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 (c) 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.