File Coverage

blib/lib/Text/Textile/RTF.pm

Criterion	Covered	Total	%
statement	18	18	100.0
branch			n/a
condition			n/a
subroutine	6	6	100.0
pod			n/a
total	24	24	100.0

###############################################################################
#
# This file copyright (c) 2009 by Randy J. Ray, all rights reserved
#
# 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 (http://www.opensource.org/licenses/lgpl-2.1.php).
#
###############################################################################
#
#   Description:    A sub-class of Text::Textile::Plaintext that plugs in a
#                   RTF formatter in place of the plain-text one.
#
#   Functions:      new
#                   textile
#
#   Libraries:      HTML::FormatRTF
#
#   Global Consts:  $VERSION
#
###############################################################################

package Text::Textile::RTF;

use 5.008;
use strict;
use warnings;
use vars qw($VERSION @EXPORT @EXPORT_OK);
use subs qw(new textile);
use base qw(Exporter Text::Textile::Plaintext);

use Scalar::Util qw(blessed reftype);
require HTML::FormatRTF;

$VERSION   = '0.101';
$VERSION   = eval $VERSION;    ## no critic
@EXPORT    = ();
@EXPORT_OK = qw(textile);

###############################################################################
#
#   Sub Name:       new
#
#   Description:    Look for "formatter" arguments, and/or create a RTF-based
#                   formatter before relegating to the parent-class
#                   constructor.
#
#   Arguments:      NAME      IN/OUT  TYPE      DESCRIPTION
#                   $class    in      scalar    Class we are blessing into
#                   %args     in      hash      Additional arguments
#
#   Returns:        object reference, dies if given bad "formatter" data
#
###############################################################################
sub new
{
    my ($class, %args) = @_;

    if ($args{formatter})
    {
        if (!blessed $args{formatter})
        {
            die __PACKAGE__ . "::new: Argument to 'formatter' must be an " .
              'object or a hash reference, stopped'
              unless (reftype($args{formatter}) eq 'HASH');

			$args{formatter} = HTML::FormatRTF->new(%{$args{formatter}});
        }
    }
    else
    {
        $args{formatter} = HTML::FormatPS->new();
    }

    $class->SUPER::new(%args);
}

###############################################################################
#
#   Sub Name:       textile
#
#   Description:    A wrapper around the parent-class version, so that this
#                   can be properly exported.
#
#   Arguments:      NAME      IN/OUT  TYPE      DESCRIPTION
#                   $self     in      ref       If present, an object of this
#                                                 class. If not present, a
#                                                 throw-away one is created.
#                   $content  in      scalar    Content to be converted to
#                                                 plain text.
#
#   Returns:        return value from SUPER::textile
#
###############################################################################
sub textile
{
	my ($self, $content) = @_;

	unless (blessed $self && $self->isa('Text::Textile::RTF'))
	{
		$content = $self;
		$self = __PACKAGE__->new();
	}

	$self->SUPER::textile($content);
}

1;

=head1 NAME

Text::Textile::RTF - Generate RTF output from Textile mark-up

=head1 SYNOPSIS

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

    my $textile = <
    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 $ttrtf = Text::Textile::RTF->new();
    $rtf = $ttrtf->process($textile);

=head1 DESCRIPTION

B is a sub-class of B that
produces RTF output instead of plain text. See L
for more detail.

=head1 METHODS

This class only defines the following two methods. It inherits everything else
from B.

=over 4

=item new([%args])

Create a new instance of this class. This constructor calls the super-class
constructor after handling the C parameter and setting up an
instance of B to pass to the parent. This method only handles
the following parameter:

=over 8

=item formatter($obj|$hashref)

Specify either a pre-created instance of B (or a suitable
sub-class) or a hash-reference of parameters to pass to the constructor when
creating one. If this parameter is not present, an object is created with the
default parameters (as according to L).

=back

See documentation of the new() method in L for
additional recognized parameters.

=item textile($textile)

This method is defined in this class so that it can be imported and used
procedurally, as textile() is used in either B or
B itself. It renders the Textile mark-up in C<$textile> to HTML,
then renders the resulting HTML tree into RTF. It returns the RTF content as a
single string.

=back

=head1 BUGS

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

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=item * Source code on GitHub

L

=back

=head1 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 (L) or
the GNU LGPL 2.1 (L).

=head1 SEE ALSO

L, L, L,
L.

=head1 AUTHOR

Randy J. Ray C<<  >>

=cut