The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Textile-Plaintext-0.101
River stage one • 1 direct dependent • 1 total dependent
++
/ Text::Textile::Plaintext

NAME

Text::Textile::Plaintext - Convert Textile mark-up to plain text

SYNOPSIS

    use Text::Textile::Plaintext qw(textile);

    my $textile = <<EOT;
    h1. Heading

    A _simple_ demonstration of Textile markup.

    * One
    * Two
    * Three

    "More information":http://www.textism.com/tools/textile is available.
    EOT

    # Procedural interface:
    my $text = textile($textile);
    print $text;

    # Object-oriented interface
    my $ttp = Text::Textile::Plaintext->new();
    $text = $ttp->process($textile);

DESCRIPTION

The Text::Textile::Plaintext class extends Text::Textile by running the HTML content that it produces through instances of a tree-builder and a formatter. By default, HTML::TreeBuilder and HTML::FormatText are used, but classes that match their interfaces can be substituted.

The functionality provided by this module is identical to that of Text::Textile. Note that even the synopsis, above, is lifted directly from there. The only difference is in the format of the output produced.

USAGE

As with Text::Textile, this module's functionality may be used either procedurally or via an object interface. You can import the textile() function and call it without having to first instantiate an object instance. See below for documentation on this function and its calling convention.

METHODS

The following methods are available within this class:

new([%ARGS])

Create a new object of this class. The arguments detailed below, if present, are stripped and processed by Text::Textile::Plaintext while any remaining arguments are passed to the super-class (Text::Textile) constructor.

The arguments handled locally are:

treebuilder

Provide a pre-instantiated instance of HTML::TreeBuilder (or suitable sub-class) to use in place of new() constructing one itself.

formatter

Provide a pre-instantiated instance of HTML::FormatText (or suitable sub-class) to use in place of new() constructing one itself.

leftmargin
rightmargin

These are passed directly to the constructor of HTML::FormatText, unless you passed in a specific formatter instance via the formatter parameter, above. The defaults for the margins are those set by HTML::FormatText (3 for the left margin, 72 for the right).

Both of the objects (tree-builder and formatter) are kept until after the parent constructor is called and the object re-blessed into the calling class. At that point, the values are assigned to the object using the accessor methods defined below. This allows a sub-class to overload the accessors and handle these parameters.

textile($textile_content)

Convert the Textile mark-up in $textile_content to plain text, and return the converted content. This method is identical in nature and calling form to the same-named method in the parent class. The difference is the production of plain text rather than HTML.

This method may be imported and called as a function. In such a case, a temporary Text::Textile::Plaintext object is created and used to invoke the needed parent class functionality.

treebuilder([$new])

Get or set the treebuilder attribute.

If a value is given, it is assigned as the new value of the attribute. This must be a reference to an object that is either an instance of HTML::TreeBuilder, or an instance of an object that matches its interface. You can use this to assign a tree-builder that has debugging capacity built into it, for example.

The return value is the current attribute value (after update).

formatter([$new])

Get or set the formatter attribute.

If a value is given, it is assigned as the new value of the attribute. This must be a reference to an object that is either an instance of HTML::FormatText, or an instance of an object that matches its interface. You can use this to assign a formatter that has debugging capacity built into it, for example.

The return value is the current attribute value (after update).

Note that the method process() is not defined here, as it is inherited from Text::Textile.

DIAGNOSTICS

This module makes no effort to trap error messages or exceptions. Any output to STDERR or STDOUT, or calls to warn or die by Text::Textile, HTML::TreeBuilder or HTML::FormatText will go through unchallenged unless the user sets up their own exception-handling.

CAVEATS

In truth, Textile could be converted to text without first being turned into HTML. But Text::Textile does a good job of handling all the various stylistic syntax that can affect things like paragraph justification, etc., and the other modules do their jobs quite well, too.

The HTML::FormatText package has some quirks in the way things are laid-out, such as bulleted lists.

BUGS

Please report any bugs or feature requests to bug-text-textile-plaintext at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Textile-Plaintext. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

COPYRIGHT & LICENSE

This file and the code within are copyright (c) 2009 by Randy J. Ray.

Copying and distribution are permitted under the terms of the Artistic License 2.0 (http://www.opensource.org/licenses/artistic-license-2.0.php) or the GNU LGPL 2.1 (http://www.opensource.org/licenses/lgpl-2.1.php).

SEE ALSO

Text::Textile

AUTHOR

Randy J. Ray <rjray@blackperl.com>