view release on metacpan or  search on metacpan

lib/App/Textile2x.pm  view on Meta::CPAN

=head1 USAGE

This class makes two methods available:

=over 4

=item 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:

=over 8

=item plaintext

Arguments for the B<Text::Textile::Plaintext> class.

=item postscript

Arguments for the B<Text::Textile::PostScript> class.

=item rtf

Arguments for the B<Text::Textile::RTF> class.

=back

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.

=item convert($source, $sink, $format)

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

The C<$source> parameter may be in one of forms:

=over 8

=item Scalar

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

=item 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 B<Text::Textile>.

=item 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 B<Text::Textile>. Note that it is
not I<streamed> to the Textile converter (which does not support streaming
anyway). Caution should be taken when converting excessively large files this
way.

=back

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

=over 8

=item Scalar reference

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

=item 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 B<print>.

=back

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

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

=back

=head1 BUGS

Please report any bugs or feature requests to C<bug-text-textile-plaintext at
rt.cpan.org>, or through the web interface at
L<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.

=head1 SUPPORT

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-Textile-Plaintext>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Text-Textile-Plaintext>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Text-Textile-Plaintext>

=item * Search CPAN

L<http://search.cpan.org/dist/Text-Textile-Plaintext>