new

    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.

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.

Decorators

metachars

This option is on by default.

All characters that are unsafe for HTML display will be encoded using "HTML::Entities::encode_entities()".

urls

This option is off by default.

Replaces URLs with links.

email

This option is off by default.

Replaces email addresses with "mailto:" links.

bold

This option is off by default.

Replaces text surrounded by asterisks ("*") with the same text surrounded by "strong" tags.

underline

This option is off by default.

Replaces text surrownded by underscores ("_") with the same text surrounded by "span" tags with an underline style.

Output Modes

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.

pre

This option is off by default.

Wraps the entire text in "pre" tags.

lines

This option is off by default.

Preserves line breaks by inserting "br" tags at the end of each line.

This mode has further options.

paras

This option is off by default.

Preserves paragraphs by wrapping them in "p" tags.

This mode has further options.

parse

  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()".

text2html

    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 HTML::FromText;
    # or ...
    use HTML::FromText ();

Subclassing

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.

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()
    }

pre

Used when "pre" mode is specified.

Should set "$self->{html}".

Return value is ignored.

lines

Used when "lines" mode is specified.

Implements the "spaces" option internally when the option is set to a true value.

Should set "$self->{html}".

Return value is ignored.

paras

Used when the "paras" mode is specified.

Splits "$self->{text}" into paragraphs internally and sets up "$self->{paras}" as follows.

    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.

Converts any normal paragraphs to HTML paragraphs (surrounded by "p" tags) internally.

Should set "$self->{html}".

Return value is ignored.

headings

Used to format headings when the "headings" option is turned on.

Return value is ignored.

bullets

Format bulleted lists when the "bullets" option is turned on.

Return value is ignored.

numbers

Format numbered lists when the "numbers" option is turned on.

Return value is ignored.

tables

Format tables when the "tables" option is turned on.

Return value is ignored.

blockparas

Used when the "blockparas" option is turned on.

Return value is ignored.

blockquotes

Used when the "blockquotes" option is turned on.

Return value is ignored.

blockcode

Used when the "blockcode" option is turned on.

Return value is ignored.

urls

Turn urls into links when "urls" option is turned on.

Should operate on "$self->{html}".

Return value is ignored.

email

Turn email addresses into "mailto:" links when "email" option is turned on.

Should operate on "$self->{html}".

Return value is ignored.

underline

Underline things between _underscores_ when "underline" option is turned on.

Should operate on "$self->{html}".

Return value is ignored.

bold

Bold things between *asterisks* when "bold" option is turned on.

Should operate on "$self->{html}".

Return value is ignored.

metachars

Encode meta characters when "metachars" option is turned on.

Should operate on "$self->{html}".

Return value is ignored.

Output

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: none !important;