HTML::...nverter(3pm)

HTML::WikiConverter 💖 (that's the HTML::...nverter(3pm) page, bestie — User Contributed Perl Documentation)

okay so. you wanna turn HTML into wiki markup?? say less. this module is THE moment. let's get into it 🫶

---

✨ NAME ✨

HTML::WikiConverter — Convert HTML to wiki markup. that's it. that's the whole vibe. 💅

---

🎀 SYNOPSIS 🎀

like, here's the absolute basics:

  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 🌸

okay so HTML::WikiConverter is an HTML to wiki converter. it takes HTML source and turns it into a bunch of different wiki markups, and we call each markup flavor a wiki "dialect". it's giving polyglot honestly. 🦋

here are all the dialects it supports:

  DokuWiki
  Kwiki
  MediaWiki
  MoinMoin
  Oddmuse
  PbWiki
  PhpWiki
  PmWiki
  SlipSlap
  TikiWiki
  UseMod
  WakkaWiki
  WikkaWiki

ngl, while dialects usually produce satisfactory wiki markup, not all features of all dialects are supported. so like, consult the individual dialects' docs for the deets on what's supported. if you have suggestions for improvements — especially in the form of patches — they are very much appreciated. bestie contributions >>>

since version 0.50 all dialects were separated out from HTML:WikiConverter. so please install the independent dialect packages as needed. no cap. 🔥

---

👑 METHODS 👑

💜 new

  my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );

returns you a converter for whatever wiki dialect you asked for. it croaks if $dialect isn't provided, or if its dialect module isn't installed on your system. (rude of it, but fair.) you can also pass extra attributes in %attrs — the full list lives down in "ATTRIBUTES". go look, i'll wait 💖

💜 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. it accepts either an HTML string $html, a file $file, or a URI $uri to read from. pick your fighter ✨

any attributes you assign in %attrs (check "ATTRIBUTES") will augment or override the attributes you set before, but only for the duration of that one "html2wiki()" call. temporary slay. 💅

💜 elem_search_lineage

  my $ancestor = $wc->elem_search_lineage( $node, \%rules );

searches the lineage (the family tree, the ancestry.com moment 🌳) of $node and returns the first ancestor node that has rules matching those specified in %rules. if no matching node is found, you get "undef". rip.

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 that was passed to — or fetched (like, from a file or URI) by — the last "html2wiki()" method call. super handy for debugging. 🔍

💜 parsed_html

  my $parsed_html = $wc->parsed_html;

returns a string with the post-processed HTML from the last "html2wiki" call. and what does "post-processed" mean, you ask? it includes parsing by HTML::TreeBuilder, CSS normalization by HTML::WikiConverter::Normalizer, and calls to the "preprocess" and "preprocess_tree" dialect methods. the whole glow-up routine 🧖‍♀️

💜 available_dialects

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

returns a list of all the available dialects — it gets this by searching the directories in @INC for "HTML::WikiConverter::" modules. manifesting them into existence ✨

💜 rules_for_tag

  my $rules = $wc->rules_for_tag( $tag );

returns the rules that'll be used for converting elements of the given tag. it follows "alias" references too. heads up tho: the rules used for a particular tag may depend on the current set of attributes being used. so it's contextual, iykyk. 💅

---

🌈 ATTRIBUTES 🌈

you can configure "HTML::WikiConverter" with a bunch of attributes. pass them as arguments to the "new" constructor, or call them as object methods on an H::WC object. either way bestie. 🫶

some dialects allow other attributes in addition to the ones below, and may even override the default values of these. so consult the dialect's documentation for details, fr fr.

🦋 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) — the dialect to use for converting HTML into wiki markup. peep the "DESCRIPTION" section above for a list of dialects. "new()" will fail if the dialect you give isn't installed on your system. use "available_dialects()" to list the ones you actually have. no guessing games 💀

🦋 encoding

specifies the encoding used by the HTML to be converted. it 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. safety first babes 🛡️

🦋 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.

🦋 passthrough_naked_tags

boolean indicating whether tags with no attributes (aka "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. trust. 🔥

🦋 preprocess

code reference that gets invoked after the HTML is parsed but before it's 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. it's giving main character callback energy ✨

🦋 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 do the 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. okurrr 💅

🦋 strip_empty_tags

strips elements containing no content (unless those elements legitimately contain no content — like "br" and "img" 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' ]. bye bye to the clutter 👋

🦋 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. we love a default 🫶

🦋 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. on top of that, "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's 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 the HTML in "<html>" and "</html>" before passing it through "html2wiki". boolean, enabled by default. swaddling the lil fragments 🍼

---

🧚 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. we support each other here 💖

---

⭐ 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. we stay updated together ✨

---

🫶 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>

---

okay that's a lot of ground covered and we're not even done...

💖 ACKNOWLEDGEMENTS 💖

Ok bestie, shoutout time, because nobody builds a whole HTML-to-wiki converter alone and this author is not about to pretend otherwise 🫶

• Tatsuhiko Miyagawa — the absolute legend who suggested Bundle::HTMLWikiConverter, and also handed over the actual code for the available_dialects() class method. Iconic behaviour, no notes. 👑
• Martin Kudlvasr — caught and fixed a bug in the logic of how HTML files were processed. Not just spotting it, but fixing it too?? That's main character energy fr fr 😭💅
• Dave Schaefer — huge thanks for the PbWiki dialect, plus the idea behind the new attributes() implementation. Two-for-one genius, we love to see it 🌟

Genuinely though — every one of these people made this thing better. Respect the contributors, always. ✨

---

📜 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. 🐪✨

tl;dr — it's Perl-licensed, go forth and remix, just keep the terms the same. 💜

---

and that's the whole page, bestie!! 🎀 you made it to the very end, which honestly deserves a little round of applause 👏🌸 this one's from the perl v5.34.0 docs, dated 2022-06-14, and it's the HTML::...nverter(3pm) page from the User Contributed Perl Documentation. now go convert some HTML, you gorgeous nerd 💖🦋