HTML::FromText - Convert plain text to HTML.
use HTML::FromText; text2html( $text, %options ); # or use HTML::FromText (); my $t2h = HTML::FromText->new( \%options ); my $html = $t2h->parse( $html );
HTML::FromText converts plain text to HTML. There are a handfull of options that shape the conversion. There is a utility function, text2html, that's exported by default. This function is simply a short- cut to the Object Oriented interface described in detail below.
HTML::FromText
text2html
The following methods may be used as the public interface.
my $t2h = HTML::FromText->new({ paras => 1, blockcode => 1, tables => 1, bullets => 1, numbers => 1, urls => 1, email => 1, bold => 1, underline => 1, });
Constructs a new HTML::FromText object using the given configuration. The resulting object can parse lots of objects using the parse method.
parse
Options to new are passed by name, with the value being either true or false. If true, the option will be turned on. If false, it will be turned off. The following outlines all the options.
new
This option is on by default.
All characters that are unsafe for HTML display will be encoded using HTML::Entities::encode_entities().
HTML::Entities::encode_entities()
This option is off by default.
Replaces URLs with links.
Replaces email addresses with mailto: links.
mailto:
Replaces text surrounded by asterisks (*) with the same text surrounded by strong tags.
*
strong
Replaces text surrownded by underscores (_) with the same text surrounded by span tags with an underline style.
_
span
The following are three output modes and the options associated with them. They are listed in order of precidence. If none of these modes are supplied, the basic decorators are applied to the text in whole.
Wraps the entire text in pre tags.
pre
Preserves line breaks by inserting br tags at the end of each line.
br
This mode has further options.
All spaces are HTML encoded.
Preserves paragraphs by wrapping them in p tags.
p
Convert bulleted lists into unordered lists (ul). Bullets can be either an asterisk (*) or a hyphen (-). Lists can be nested.
ul
-
Convert numbered lists into ordered lists (ol). Numbered lists are identified by numerals. Lists may be nested.
ol
Convert paragraphs identified as headings into HTML headings at the appropriate level. The heading 1. Top would be heading level one (h1). The heading 2.5.1. Blah would be heading level three (h3).
1. Top
h1
2.5.1. Blah
h3
Convert the first paragraph to a heading level one (h1).
Convert paragraphs identified as tables to HTML tables. Tables are two or more rows and two or more columns. Columns should be separated by two or more spaces.
The following options apply specifically to indented paragraphs. They are listed in order of precidence.
Convert indented paragraphs to block quotes using the blockquote tag.
blockquote
Convert indented paragraphs as blockparas would, but also preserving line breaks.
blockparas
Convert indented paragraphs as blockquotes would, but also preserving spaces using pre tags.
blockquotes
my $html = $t2h->parse( $text );
Parses text supplied as a single scalar string and returns the HTML as a single scalar string. All the tabs in your text will be expanded using Text::Tabs::expand().
Text::Tabs::expand()
my $html = text2html( $text, urls => 1, email => 1, );
Functional interface that just wraps the OO interface. This function is exported by default. If you don't want it you can require the module or use it with an empty list.
require
use
require HTML::FromText; # or ... use HTML::FromText ();
Note: At the time of this release, the internals of HTML::FromText are in a state of development and cannot be expected to stay the same from release to release. I expect that release version 3.00 will be analogous to a 1.00 release of other software. This is because the current maintainer has rewritten this distribution from the ground up for the 2.x series. You have been warned.
1.00
2.x
The following methods may be used for subclassing HTML::FromText to create your own text to HTML conversions. Each of these methods is passed just one argument, the object ($self), unless otherwise stated.
$self
The structure of $self is as follows for this release.
{ options => { option_name => $value, ... }, text => $text, # as passed to parse(), with tabs expanded html => $html, # the HTML that will be returned from parse() }
Used when pre mode is specified.
Should set $self->{html}.
$self->{html}
Return value is ignored.
Used when lines mode is specified.
lines
Implements the spaces option internally when the option is set to a true value.
spaces
Used when the paras mode is specified.
paras
Splits $self->{text} into paragraphs internally and sets up $self->{paras} as follows.
$self->{text}
$self->{paras}
paras => { 0 => { text => $text, # paragraph text html => $html, # paragraph html }, ... # and so on for all paragraphs },
Implements the title option internally when the option is turned on.
title
Converts any normal paragraphs to HTML paragraphs (surrounded by p tags) internally.
Used to format headings when the headings option is turned on.
headings
Format bulleted lists when the bullets option is turned on.
bullets
Format numbered lists when the numbers option is turned on.
numbers
Format tables when the tables option is turned on.
tables
Used when the blockparas option is turned on.
Used when the blockquotes option is turned on.
Used when the blockcode option is turned on.
blockcode
Turn urls into links when urls option is turned on.
urls
Should operate on $self->{html}.
Turn email addresses into mailto: links when email option is turned on.
email
Underline things between _underscores_ when underline option is turned on.
underline
Bold things between *asterisks* when bold option is turned on.
bold
Encode meta characters when metachars option is turned on.
metachars
The output from HTML::FromText has been updated to pass XHTML 1.1 validation. Every HTML tag that should have a CSS class name does. They are prefixed with hft- and correspond to the names of the options to new() (or text2html()). For example hft-lines, hft-paras, and hft-urls.
hft-
new()
text2html()
hft-lines
hft-paras
hft-urls
One important note is the output for underline. Because the <u> tag is deprecated in this specification a span is used with a style attribute of text-decoration: underline. The class is hft- underline. If you want to override the text-decoration style in the CSS class you'll need to do so like this.
text-decoration: underline
hft- underline
text-decoration
text-decoration: none !important;
text2html(1).
Casey West <casey@geeknest.com>.
Gareth Rees <garethr@cre.canon.co.uk>.
Copyright (c) 2003 Casey West. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::FromText, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::FromText
CPAN shell
perl -MCPAN -e shell install HTML::FromText
For more information on module installation, please visit the detailed CPAN module installation guide.