-
-
21 Jul 2006 15:38:12 UTC
- Distribution: HTML-WikiConverter
- Module version: 0.61
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (25)
- Testers (112 / 13 / 2)
- Kwalitee
Bus factor: 0- License: unknown
- Activity
24 month- Tools
- Download (34.33KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- CSS
- Carp
- Class::Data::Inheritable
- Exporter
- HTML::Element
- HTML::Entities
- HTML::Tagset
- HTML::Tree
- Params::Validate
- Pod::Usage
- Test::More
- URI
- URI::Escape
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS
- ATTRIBUTES
- ADDING A DIALECT
- SEE ALSO
- AUTHOR
- BUGS
- SUPPORT
- ACKNOWLEDGEMENTS
- COPYRIGHT & LICENSE
NAME
HTML::WikiConverter - Convert HTML to wiki markup
SYNOPSIS
use HTML::WikiConverter; my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' ); # Provide HTML directly print $wc->html2wiki( $html ); # ...which is the same as print $wc->html2wiki( html => $html ); # Or fetch it from a file print $wc->html2wiki( file => $path ); # ...slurp it all at once rather than parsing incrementally print $wc->html2wiki( file => $path, slurp => 1 ); # Or from a URI print $wc->html2wiki( uri => $uri ); # Get a list of installed dialects my @dialects = HTML::WikiConverter->available_dialects;
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. 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 list of recognized attributes.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 thehtml2wiki()
call.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 HTML::TreeBuilder's string representation of the last-parsed syntax tree, showing how the input HTML was parsed internally. Also useful for debugging.
available_dialects
my @dialects = HTML::WikiConverter->available_dialects;
Returns a list of all available dialects by searching the directories in
@INC
forHTML::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. 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 thenew
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
andhref
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 thebase_uri
argument is present. Defaults toundef
.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. Useavailable_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
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.head2 passthrough_naked_tags
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, itsread_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 callhtml2wiki()
with thefile
argument.strip_empty_tags
Strips elements containing no content (unless those elements legitimately contain no content, such as is the case for
br
andimg
tags, for example). Defaults to false.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' ]
.user_agent
Specifies the LWP::UserAgent object to be used when fetching the URI passed to
html2wiki()
. If unspecified andhtml2wiki()
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 matcheswiki_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 thewiki_uri
has been set to a string, regexp, or coderef. The default isundef
, 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 thewiki_uri
with the wiki page title. For example, the English Wikipedia might use"http://en.wikipedia.org/wiki/"
as the value ofwiki_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 useqr~http://en\.wikipedia\.org/w/index\.php\?title\=([^&]+)~
.wiki_uri
can also be a coderef that takes the currentHTML::WikiConverter
object and a URI object. It should return the title of the wiki page extracted from the URI, orundef
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 throughhtml2wiki
. 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
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
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
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.
Module Install Instructions
To install HTML::WikiConverter, copy and paste the appropriate command in to your terminal.
cpanm HTML::WikiConverter
perl -MCPAN -e shell install HTML::WikiConverter
For more information on module installation, please visit the detailed CPAN module installation guide.