man HTML::FromText () - Convert plain text to HTML.

NAME

HTML::FromText - Convert plain text to HTML.

SYNOPSIS

    use HTML::FromText;
    text2html( $text, %options );

    # or

    use HTML::FromText ();
    my $t2h  = HTML::FromText->new( \%options );
    my $html = $t2h->parse( $html );

DESCRIPTION

CWHTML::FromText converts plain text to HTML. There are a handfull of options that shape the conversion. There is a utility function, CWtext2html, that's exported by default. This function is simply a short- cut to the Object Oriented interface described in detail below.

Methods

The following methods may be used as the public interface.

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 CWHTML::FromText object using the given configuration. The resulting object can parse lots of objects using the CWparse method.

Options to CWnew 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 CWHTML::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 CWmailto: links.
bold: This option is off by default. Replaces text surrounded by asterisks (CW*) with the same text surrounded by CWstrong tags.
underline: This option is off by default. Replaces text surrownded by underscores (CW_) with the same text surrounded by CWspan 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 CWpre tags.
lines: This option is off by default. Preserves line breaks by inserting CWbr tags at the end of each line. This mode has further options.
spaces: This option is off by default. All spaces are HTML encoded.
paras: This option is off by default. Preserves paragraphs by wrapping them in CWp tags. This mode has further options.
bullets: This option is off by default. Convert bulleted lists into unordered lists (CWul). Bullets can be either an asterisk (CW*) or a hyphen (CW-). Lists can be nested.
numbers: This option is off by default. Convert numbered lists into ordered lists (CWol). Numbered lists are identified by numerals. Lists may be nested.
headings: This option is off by default. Convert paragraphs identified as headings into HTML headings at the appropriate level. The heading CW1. Top would be heading level one (CWh1). The heading CW2.5.1. Blah would be heading level three (CWh3).
title: This option is off by default. Convert the first paragraph to a heading level one (CWh1).
tables: This option is off by default. 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.
blockparas: This option is off by default. Convert indented paragraphs to block quotes using the CWblockquote tag.
blockquotes: Convert indented paragraphs as CWblockparas would, but also preserving line breaks.
blockcode: Convert indented paragraphs as CWblockquotes would, but also preserving spaces using CWpre tags.

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 CWText::Tabs::expand().

Functions

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 CWrequire the module or CWuse it with an empty list.

    require HTML::FromText;
    # or ...
    use HTML::FromText ();

Subclassing

Note: At the time of this release, the internals of CWHTML::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 CW1.00 release of other software. This is because the current maintainer has rewritten this distribution from the ground up for the CW2.x series. You have been warned.

The following methods may be used for subclassing CWHTML::FromText to create your own text to HTML conversions. Each of these methods is passed just one argument, the object (CW$self), unless otherwise stated.

The structure of CW$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 CWpre mode is specified.

Should set CW$self->{html}.

Return value is ignored.

lines

Used when CWlines mode is specified.

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

Should set CW$self->{html}.

Return value is ignored.

paras

Used when the CWparas mode is specified.

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

    paras => {
              0 => {
                    text => $text, # paragraph text
                    html => $html, # paragraph html
                   },
              ... # and so on for all paragraphs
             },

Implements the CWtitle option internally when the option is turned on.

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

Should set CW$self->{html}.

Return value is ignored.

headings

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

Return value is ignored.

bullets

Format bulleted lists when the CWbullets option is turned on.

Return value is ignored.

numbers

Format numbered lists when the CWnumbers option is turned on.

Return value is ignored.

tables

Format tables when the CWtables option is turned on.

Return value is ignored.

blockparas

Used when the CWblockparas option is turned on.

Return value is ignored.

blockquotes

Used when the CWblockquotes option is turned on.

Return value is ignored.

blockcode

Used when the CWblockcode option is turned on.

Return value is ignored.

urls

Turn urls into links when CWurls option is turned on.