The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-FormatExternal-15
River stage one • 3 direct dependents • 8 total dependents
++
/ HTML::FormatExternal

NAME

HTML::FormatExternal - HTML to text formatting using external programs

DESCRIPTION

This is a collection of the following formatter modules turning HTML into plain text by dumping it through the respective external programs.

    HTML::FormatText::Elinks
    HTML::FormatText::Html2text
    HTML::FormatText::Links
    HTML::FormatText::Lynx
    HTML::FormatText::Netrik
    HTML::FormatText::W3m
    HTML::FormatText::Zen

The module interfaces are compatible with HTML::Formatter modules like HTML::FormatText, but the programs do all the work.

Common formatting options are used where possible, like leftmargin and rightmargin, so just by switching the class you can use a different program (or the plain HTML::FormatText) according to personal preference, or strengths and weaknesses, or what you've got.

There's nothing particularly difficult about piping through these programs, but a unified interface hides details like how to set margins and how to force input or output charsets.

FUNCTIONS

Each of the classes above provide the following functions. The XXX in the class names here is a placeholder for any of Elinks, Lynx, etc as above.

Formatter Compatible Functions

$text = HTML::FormatText::XXX->format_file ($filename, key=>value,...)
$text = HTML::FormatText::XXX->format_string ($html_string, key=>value,...)

Run the formatter program over a file or string with the given options and return the formatted result as a string. See "OPTIONS" below for available options. For example,

    $text = HTML::FormatText::Lynx->format_file ('/my/file.html');

    $text = HTML::FormatText::W3m->format_string
      ('<html><body> <p> Hello world! </p </body></html>');
$formatter = HTML::FormatText::XXX->new (key=>value, ...)

Create a formatter object with the given options. In the current implementation an object doesn't do much more than remember the options for future use.

    $formatter = HTML::FormatText::Elinks->new(rightmargin => 60);
$text = $formatter->format ($tree_or_string)

Run the $formatter program on a HTML::TreeBuilder tree or a string, using the options in $formatter, and return the result as a string.

A TreeBuilder argument (ie. a HTML::Element) is for compatibility with HTML::Formatter. The tree is simply turned into a string with $tree->as_HTML to pass to the program, so if you've got a string already then give that instead of a tree.

Extra Functions

HTML::FormatText::XXX->program_version ()
HTML::FormatText::XXX->program_full_version ()
$formatter->program_version ()
$formatter->program_full_version ()

Return the version number of the formatter program as reported by its --version or similar option. If the formatter program is not available the return is undef.

program_version is the number alone. program_full_version is the entire output, which may include build options, copyright notice, etc.

    $str = HTML::FormatText::Lynx->program_version();
    # eg. "2.8.7dev.10"

    $str = HTML::FormatText::W3m->program_full_version();
    # eg. "w3m version w3m/0.5.2, options lang=en,m17n,image,..."

The version number of the Perl module itself is available with the usual HTML::FormatText::Netrik->VERSION or $formatter->VERSION, see UNIVERSAL.

CHARSETS

A file passed to the formatters is interpreted in the charset of a <meta> within the HTML, or latin-1 per the HTML specs, or as forced by the input_charset option below.

A string input should be bytes the same as a file, not Perl wide chars. (There's some secret experimental encode/decode for wide chars, but better let HTML::Formatter take the lead on how that might work.)

The result string is bytes similarly, encoded in whatever the respective programs produce. This may be the locale charset; you can force it with the output_charset option to be sure.

OPTIONS

The following options can be given. The defaults are whatever the respective programs do. The programs generally read their config files when dumping, so the defaults and formatting details may follow your personal settings (usually a good thing).

leftmargin => INTEGER
rightmargin => INTEGER

The column numbers for the left and right hand ends of the text. leftmargin 0 means no padding on the left. rightmargin is the text width, so for instance 60 would mean the longest line is 60 characters (inclusive of any leftmargin). These options are compatible with HTML::FormatText.

rightmargin is not necessarily a hard limit. Some of the programs will exceed it in a HTML literal <pre>, or a run of &nbsp;, or similar.

input_charset => STRING

Force the HTML input to be interpreted as bytes of the given charset, including ignoring any <meta> within the HTML.

output_charset => STRING

Force the text output to be encoded as of the given charset. The program defaults vary, but usually follow the locale.

FUTURE

There's nothing done with errors or warning messages from the formatters. Generally they make a best effort on doubtful HTML, but fatal errors like bad options or missing libraries will probably be trapped in the future.

elinks (from Aug 2008) and netrik can produce ANSI escapes for colours, underline, etc, and html2text can produce TTY style backspacing. This might be good for text destined for a tty or further crunching. Perhaps an ansi or tty option could enable this, where possible, but for now it's deliberately turned off in those programs to keep the default straightforward.

SEE ALSO

HTML::FormatText::Elinks, HTML::FormatText::Html2text, HTML::FormatText::Links, HTML::FormatText::Netrik, HTML::FormatText::Lynx, HTML::FormatText::W3m, HTML::FormatText::Zen,

HTML::FormatText, HTML::FormatText::WithLinks, HTML::FormatText::WithLinks::AndTables

HOME PAGE

http://user42.tuxfamily.org/html-formatexternal/index.html

LICENSE

Copyright 2008, 2009 Kevin Ryde

HTML-FormatExternal is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

HTML-FormatExternal is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with HTML-FormatExternal. If not, see <http://www.gnu.org/licenses/>.