/ 
Text-Translate-Format-0.1.0_01
/ Text::Translate::Format

NAME

Text::Translate::Format - basic format conversions for Text::Translate

VERSION

version 0.1.0_01

SYNOPSIS

my $obj = Text::Translate::Format->new(
   Pod => filename => '/opt/perl-5.12.2/lib/5.12.2/pod/perlfunc.pod'
);

my @paragraphs = $obj->paragraphs();

my @translated = translate(@paragraphs);
my $trans_obj = Text::Translate::Format->new(
   Pod => paragraphs => \@translated
);
print "Translated POD:\n", $trans_obj->text();

DESCRIPTION

This module allows transforming a text into paragraphs (suitable for handling through <L/Text::Translate>) and vice-versa. This module is actually a base class for format-specific subclasses, and acts as a factory to generate objects of these subclasses as well.

The typical life cycle will be the following:

  • load the source text from a file (or from a filehandle, or directly from a scalar variable):

    my $src = Text::Translate::Format->new(
   Pod => filename => '/path/to/file.pod'
);

  • get the paragraphs:

    my @src_paragraphs = $src->paragraphs();

  • translate the paragraphs:

    my @dst_paragraphs = translate(@src_paragraphs);

  • create an object for the translated document:

    my $dst = Text::Translate::Format->new(
   Pod => paragraphs => \@dst_paragraphs
);

  • get the textual rendition, e.g. for saving it or displaying:

    my $translated = $dst->text();
print "Translated text:\n", $translated;

METHODS

init

$obj->init(%args);

Object method.

(re)-initialise the object. You can pass one (and only one) of the following parameters in the %args:

text

the text to be converted into paragraphs;

filename

the name of a file containing the text to convert into paragraphs;

paragraphs

an array reference to the ordered list of paragraphs.

You can pass a reference to a hash instead of a hash.

Returns the input $obj.

new

Text::Translate::Format::Whatever->new(%args);

Class method, to be called on derived classes (croaks when called on Text::Translate::Format).

Accepts the same arguments as "init".

Returns a reference to the new object.

create

Text::Translate::Format->create($format => %args)

Class method, to be called on the Text::Translate::Format class (by default, croaks when called in derived classes).

This is a factory method to generate an object of the right $format.

Apart from the first parameter - that represents the format - all the following parameters are the same as "init".

Returns a reference to the newly created object.

paragraphs

# setter
$obj->paragraphs(@paragraphs);
$obj->paragraphs(\@pars);

# getter
my @paragraphs  = $obj->paragraphs();
my $ref_to_pars = $obj->paragraphs();

Object method, can be used as both a setter and a getter.

This method allows setting or getting the list of paragraphs.

If there are input parameters, they are set as the paragraphs list. It can be either a straight list, or a reference to an array containing the list.

Always returns the current list of paragraphs (in the setter case, returns the newly set list) in list context, a reference to an anonymous array containing the list in scalar context.

text

# setter
$obj->text($text);

# getter
my $text = $obj->text();

Object method, can be used as both a setter and a getter.

This method allows setting or getting a text rendition of the paragraphs.

If there is an input parameter, it is considered as the text to be set.

Always returns the current text (i.e. the newly set text in case of the setter).

text_from_file

# Can pass either a filename or an open filehandle to read from
my $text = $obj->text_from_file($filename);
my $text = $obj->text_from_file($FILEHANDLE);

Object method.

This method allows setting the text rendition of the paragraphs, reading it from either a file (provided through its filename) or from a filehandle.

Accepts either a filehandle or a filename.

Returns the text read from the file and set as "text".

paragraphs_to_text

$obj->paragraphs_to_text();

Object method.

This method MUST be overridden in the derived classes; it takes the list of paragraphs (via "paragraphs") and generate the textual rendition (setting it through "text").

text_to_paragraphs

$obj->text_to_paragraphs();

Object method.

This method MUST be overridden in the derived classes; it takes the textual representation (via "text") and generates the list of paragraphs (setting it through "paragraphs").

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Flavio Poletti.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.