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

=head1 DESCRIPTION

B<Text::Textile::RTF> is a sub-class of B<Text::Textile::Plaintext> that
produces RTF output instead of plain text. See L<Text::Textile::Plaintext>
for more detail.

=head1 METHODS

This class only defines the following two methods. It inherits everything else
from B<Text::Textile::Plaintext>.

=over 4

=item new([%args])

Create a new instance of this class. This constructor calls the super-class
constructor after handling the C<formatter> parameter and setting up an
instance of B<HTML::FormatRTF> 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<HTML::FormatRTF> (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<HTML::FormatRTF>).

=back

See documentation of the new() method in L<Text::Textile::Plaintext> 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<Text::Textile::Plaintext> or
B<Text::Textile> 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<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>

=item * Source code on GitHub

L<http://github.com/rjray/text-textile-plaintext/tree/master>

=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<http://www.opensource.org/licenses/artistic-license-2.0.php>) or
the GNU LGPL 2.1 (L<http://www.opensource.org/licenses/lgpl-2.1.php>).

=head1 SEE ALSO

L<Text::Textile>, L<Text::Textile::Plaintext>, L<Text::Textile::PostScript>,
L<HTML::FormatRTF>.

=head1 AUTHOR

Randy J. Ray C<< <rjray@blackperl.com> >>

=cut
