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
++
/ App::Textile2x

NAME

App::Textile2x - Application-wrapper class for converting Textile mark-up

SYNOPSIS

    use App::Textile2x;

    # ...presume that %opts comes from the command-line or other source
    $input  = $opts{input}  || \*STDIN;
    $output = $opts{output} || \*STDOUT;

    $app = App::Textile2x->new();
    $app->convert($input, $output, $opts{format} || 'plaintext');

DESCRIPTION

The App::Textile2x class is a wrapper around basic functionality based on the Text::Textile::Plaintext, etc., classes. It is meant to encapsulate the functionality provided by the textile2x family of scripts that come with this distribution.

USAGE

This class makes two methods available:

new([%args])

Create an instance of the class. Any arguments are assumed to be key-value pairs that specify constructor arguments for the formatter classes. These are used only when the class in question is actually instantiated.

The value associated with each key should be a hash-reference containing key-value pairs that are used for the constructor of the given class. The three keys currently recognized are:

plaintext

Arguments for the Text::Textile::Plaintext class.

postscript

Arguments for the Text::Textile::PostScript class.

rtf

Arguments for the Text::Textile::RTF class.

Note that the keys are expected to be all-lowercase. See the associated documentation pages for each formatter class for more information on their arguments.

convert($source, $sink, $format)

Convert Textile mark-up in the given $source and send the resulting output to the given $sink. Optionally, specify $format to use, with the default being "plaintext".

The $source parameter may be in one of forms:

Scalar

If the source is a plain scalar, it is taken as the Textile content itself and used directly.

Scalar reference

If the source is a scalar reference, it is assumed to reference the content. It is de-referenced and its content passed to Text::Textile.

Filehandle reference (GLOB)

Lastly, if the source is a filehandle or filehandle-like value, it is read from and the complete content from it is passed to Text::Textile. Note that it is not streamed to the Textile converter (which does not support streaming anyway). Caution should be taken when converting excessively large files this way.

The $sink parameter may be in one of two forms:

Scalar reference

If the sink is a scalar reference, the converted content is assigned to it directly.

Filehandle reference (GLOB)

If the sink is a reference to a filehandle or filehandle-like value, then the converted content is written to it using print.

The last parameter, $format, is optional and defaults to plaintext. It specifies whether the converted Textile content is then converted to text (plaintext), PostScript (postscript) or Rich Text Format (rtf). The value is converted to lower-case, so PostScript is a synonym for postscript.

The return value from convert() is always a true value, as it uses die to throw an exception on any errors it encounters.

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, Text::Textile::Plaintext, Text::Textile::PostScript, Text::Textile::RTF

AUTHOR

Randy J. Ray <rjray@blackperl.com>