1HTML::WikiConverter(3)User Contributed Perl DocumentationHTML::WikiConverter(3)
2
6 HTML::WikiConverter - Convert HTML to wiki markup
7
9 use HTML::WikiConverter;
10 my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' );
11 print $wc->html2wiki( html => '<b>text</b>' ), "\n\n";
12 # A more complete example
14 my $html = qq(
16 <p><i>Italic</i>, <b>bold</b>, <span style="font-weight:bold">also bold</span>, etc.</p>
17 );
18 my @dialects = HTML::WikiConverter->available_dialects;
20 foreach my $dialect ( @dialects ) {
21 my $wc = new HTML::WikiConverter( dialect => $dialect );
22 my $wiki = $wc->html2wiki( html => $html );
23 printf "The %s dialect gives:\n\n%s\n\n", $dialect, $wiki;
24 }
25
27 "HTML::WikiConverter" is an HTML to wiki converter. It can convert HTML
28 source into a variety of wiki markups, called wiki "dialects". The
29 following dialects are supported:
30 DokuWiki
32 Kwiki
33 MediaWiki
34 MoinMoin
35 Oddmuse
36 PbWiki
37 PhpWiki
38 PmWiki
39 SlipSlap
40 TikiWiki
41 UseMod
42 WakkaWiki
43 WikkaWiki
44 Note that while dialects usually produce satisfactory wiki markup, not
46 all features of all dialects are supported. Consult individual
47 dialects' documentation for details of supported features. Suggestions
48 for improvements, especially in the form of patches, are very much
49 appreciated.
50
52 new
53 my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );
54 Returns a converter for the specified wiki dialect. Croaks if $dialect
56 is not provided or its dialect module is not installed on your system.
57 Additional attributes may be specified in %attrs; see "ATTRIBUTES" for
58 a complete list.
59 html2wiki
61 $wiki = $wc->html2wiki( $html, %attrs );
62 $wiki = $wc->html2wiki( html => $html, %attrs );
63 $wiki = $wc->html2wiki( file => $file, %attrs );
64 $wiki = $wc->html2wiki( uri => $uri, %attrs );
65 Converts HTML source to wiki markup for the current dialect. Accepts
67 either an HTML string $html, an file $file, or a URI <$uri> to read
68 from.
69 Attributes assigned in %attrs (see "ATTRIBUTES") will augment or
71 override previously assigned attributes for the duration of the
72 "html2wiki()" call.
73 elem_search_lineage
75 my $ancestor = $wc->elem_search_lineage( $node, \%rules );
76 Searches the lineage of $node and returns the first ancestor node that
78 has rules matching those specified in %rules, or "undef" if no matching
79 node is found.
80 For example, to find out whether $node has an ancestor with rules
82 matching "{ block =>1 }", one could use:
83 if( $wc->elem_search_lineage( $node, { block => 1 } ) ) {
85 # do something
86 }
87 given_html
89 my $html = $wc->given_html;
90 Returns the HTML passed to or fetched (ie, from a file or URI) by the
92 last "html2wiki()" method call. Useful for debugging.
93 parsed_html
95 my $parsed_html = $wc->parsed_html;
96 Returns a string containing the post-processed HTML from the last
98 "html2wiki" call. Post-processing includes parsing by
99 HTML::TreeBuilder, CSS normalization by
100 HTML::WikiConverter::Normalizer, and calls to the "preprocess" and
101 "preprocess_tree" dialect methods.
102 available_dialects
104 my @dialects = HTML::WikiConverter->available_dialects;
105 Returns a list of all available dialects by searching the directories
107 in @INC for "HTML::WikiConverter::" modules.
108 rules_for_tag
110 my $rules = $wc->rules_for_tag( $tag );
111 Returns the rules that will be used for converting elements of the
113 given tag. Follows "alias" references. Note that the rules used for a
114 particular tag may depend on the current set of attributes being used.
115
117 You may configure "HTML::WikiConverter" using a number of attributes.
118 These may be passed as arguments to the "new" constructor, or can be
119 called as object methods on an H::WC object.
120 Some dialects allow other attributes in addition to those below, and
122 may override the attributes' default values. Consult the dialect's
123 documentation for details.
124 base_uri
126 URI to use for converting relative URIs to absolute ones. This
127 effectively ensures that the "src" and "href" attributes of image and
128 anchor tags, respectively, are absolute before converting the HTML to
129 wiki markup, which is necessary for wiki dialects that handle internal
130 and external links separately. Relative URIs are only converted to
131 absolute ones if the "base_uri" argument is present. Defaults to
132 "undef".
133 dialect
135 (Required) Dialect to use for converting HTML into wiki markup. See the
136 "DESCRIPTION" section above for a list of dialects. "new()" will fail
137 if the dialect given is not installed on your system. Use
138 "available_dialects()" to list installed dialects.
139 encoding
141 Specifies the encoding used by the HTML to be converted. Also
142 determines the encoding of the wiki markup returned by the "html2wiki"
143 method. Defaults to "utf8".
144 escape_entities
146 Passing "escape_entities" a true value uses HTML::Entities to encode
147 potentially unsafe '<', '>', and '&' characters. Defaults to true.
148 p_strict
150 Boolean indicating whether HTML::TreeBuilder will use strict handling
151 of paragraph tags when parsing HTML input. (This corresponds to the
152 "p_strict" method in the HTML::TreeBuilder module.) Enabled by default.
153 passthrough_naked_tags
155 Boolean indicating whether tags with no attributes ("naked" tags)
156 should be removed and replaced with their content. By default, this
157 only applies to non-semantic tags such as <span>, <div>, etc., but does
158 not apply to semantic tags such as <strong>, <address>, etc. To
159 override this behavior and specify the tags that should be considered
160 for passthrough, provide this attribute with a reference to an array of
161 tag names. Defaults to false, but you'll probably want to enable it.
162 preprocess
164 Code reference that gets invoked after HTML is parsed but before it is
165 converted into wiki markup. The callback is passed two arguments: the
166 "HTML::WikiConverter" object and a HTML::Element pointing to the root
167 node of the HTML tree created by HTML::TreeBuilder.
168 slurp
170 Boolean that, if enabled, bypasses "HTML::Parser"'s incremental parsing
171 (thus slurping the file in all at once) of files when reading HTML
172 files. If File::Slurp is installed, its "read_file()" function will be
173 used to perform slurping; otherwise, a common Perl idiom will be used
174 for slurping instead. This option is only used if you call
175 "html2wiki()" with the "file" argument.
176 strip_empty_tags
178 Strips elements containing no content (unless those elements
179 legitimately contain no content, such as is the case for "br" and "img"
180 tags, for example). Defaults to false.
181 strip_tags
183 A reference to an array of tags to be removed from the HTML input prior
184 to conversion to wiki markup. Tag names are the same as those used in
185 HTML::Element. Defaults to "[ '~comment', 'head', 'script', 'style' ]".
186 user_agent
188 Specifies the LWP::UserAgent object to be used when fetching the URI
189 passed to "html2wiki()". If unspecified and "html2wiki()" is passed a
190 URI, a default user agent will be created.
191 wiki_uri
193 Takes a URI, regular expression, or coderef (or a reference to an array
194 of elements of these types) used to determine which links are to wiki
195 pages: a link whose "href" parameter matches "wiki_uri" will be treated
196 as a link to a wiki page. In addition, "wiki_uri" will be used to
197 extract the title of the wiki page. The way this is done depends on
198 whether the "wiki_uri" has been set to a string, regexp, or coderef.
199 The default is "undef", meaning that all links will be treated as
200 external links by default.
201 If "wiki_uri" is a string, it is interpreted as a URI template, and it
203 will be assumed that URIs to wiki pages are created by joining
204 "wiki_uri" with the wiki page title. For example, the English Wikipedia
205 might use "http://en.wikipedia.org/wiki/" as the value of "wiki_uri".
206 Ward's wiki might use "http://c2.com/cgi/wiki?". These examples use an
207 absolute "wiki_uri", but a relative URI can be used as well; an
208 absolute URI will be created based on the value of "base_uri". For
209 example, the Wikipedia example above can be rewritten using "base_uri"
210 of "http://en.wikipedia.org" and a "wiki_uri" of "/wiki/".
211 "wiki_uri" can also be a regexp that matches URIs to wiki pages and
213 also extracts the page title from them. For example, the English
214 Wikipedia might use
215 "qr~http://en\.wikipedia\.org/w/index\.php\?title\=([^&]+)~".
216 "wiki_uri" can also be a coderef that takes the current
218 "HTML::WikiConverter" object and a URI object. It should return the
219 title of the wiki page extracted from the URI, or "undef" if the URI
220 doesn't represent a link to a wiki page.
221 As mentioned above, the "wiki_uri" attribute can either take a single
223 URI/regexp/coderef element or it may be assigned a reference to an
224 array of any number of these elements. This is useful for wikis that
225 have different ways of creating links to wiki pages. For example, the
226 English Wikipedia might use:
227 my $wc = new HTML::WikiConverter(
229 dialect => 'MediaWiki',
230 wiki_uri => [
231 'http://en.wikipiedia.org/wiki/',
232 sub { pop->query_param('title') } # requires URI::QueryParam
233 ]
234 );
235 wrap_in_html
237 Helps HTML::TreeBuilder parse HTML fragments by wrapping HTML in
238 "<html>" and "</html>" before passing it through "html2wiki". Boolean,
239 enabled by default.
240
242 Consult HTML::WikiConverter::Dialects for documentation on how to write
243 your own dialect module for "HTML::WikiConverter". Or if you're not up
244 to the task, drop me an email and I'll have a go at it when I get a
245 spare moment.
246
248 HTML::Tree, Convert::Wiki
249
251 David J. Iberri, "<diberri@cpan.org>"
252
254 Please report any bugs or feature requests to "bug-html-wikiconverter
255 at rt.cpan.org", or through the web interface at
256 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-WikiConverter>. I
257 will be notified, and then you'll automatically be notified of progress
258 on your bug as I make changes.
259
261 You can find documentation for this module with the perldoc command.
262 perldoc HTML::WikiConverter
264 You can also look for information at:
266 · AnnoCPAN: Annotated CPAN documentation
268 <http://annocpan.org/dist/HTML-WikiConverter>
270 · CPAN Ratings
272 <http://cpanratings.perl.org/d/HTML-WikiConverter>
274 · RT: CPAN's request tracker
276 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-WikiConverter>
278 · Search CPAN
280 <http://search.cpan.org/dist/HTML-WikiConverter>
282
284 Thanks to Tatsuhiko Miyagawa for suggesting Bundle::HTMLWikiConverter
285 as well as providing code for the "available_dialects()" class method.
286 My thanks also goes to Martin Kudlvasr for catching (and fixing!) a bug
288 in the logic of how HTML files were processed.
289 Big thanks to Dave Schaefer for the PbWiki dialect and for the idea
291 behind the new "attributes()" implementation.
292
294 Copyright (c) David J. Iberri, all rights reserved.
295 This program is free software; you can redistribute it and/or modify it
297 under the same terms as Perl itself.
298perl v5.28.0 2009-03-21 HTML::WikiConverter(3)