Log::Report::Lexicon::POT(3)

NAME
Log::Report::Lexicon::POT - manage PO files

SYNOPSIS
 # this is usually not for end-users, See ::Extract::PerlPPI
 # using a PO table

 my $pot = Log::Report::Lexicon::POT
    ->read('po/nl.po', charset => 'utf-8')
        or die;

 my $po = $pot->msgid('');
 print $pot->nrPlurals;
 print $pot->msgstr('msgid', 3);
 $pot->write;

 # creating a PO table

 my $po  = Log::Report::Lexicon::PO->new(...);
 $pot->add($po);

 $pot->write('po/nl.po')
     or die;

DESCRIPTION
This module is reading, extending, and writing POT files. POT files are used to store translations in humanly readable format for most of existing translation frameworks, like GNU gettext and Perl's Maketext. If you only wish to access the translation, then you may use the much more efficient Log::Report::Lexicon::POTcompact.

The code is loosely based on Locale::PO, by Alan Schwartz. The coding style is a bit off the rest of "Log::Report", and there was a need to sincere simplification. Each PO object will be represented by a Log::Report::Lexicon::PO.

METHODS

  Constructors

Log::Report::Lexicon::POT->new(OPTIONS)
    Create a new POT file. The initial header is generated for you, but it can be changed using the header() method.

     -Option    --Default
      charset     <required>
      date        now
      filename    undef
      index       {}
      nr_plurals  2
      plural_alg  n!=1
      textdomain  <required>
      version     undef

    charset => STRING
        The character-set which is used for the output.

    date => STRING
        Overrule the date which is included in the generated header.

    filename => STRING
        Specify an output filename. The name can also be specified when write() is called.

    index => HASH
        A set of translations (Log::Report::Lexicon::PO objects), with msgid as key.

    nr_plurals => INTEGER
        The number of translations each of the translation with plural form need to have.

    plural_alg => EXPRESSION
        The algorithm to be used to calculate which translated msgstr to use.

    textdomain => STRING
        The package name, used in the directory structure to store the PO files.

    version => STRING
Log::Report::Lexicon::POT->read(FILENAME, OPTIONS)
    Read the POT information from FILENAME.

     -Option --Default
      charset  <required>

    charset => STRING
        The character-set which is used for the file. You must specify this explicitly, while it cannot be trustfully detected automatically.

$obj->write([FILENAME|FILEHANDLE], OPTIONS)
    When you pass an open FILEHANDLE, you are yourself responsible that the correct character-encoding (binmode) is set. When the write followed a read() or the filename was explicitly set with filename(), then you may omit the first parameter.

  Attributes

$obj->charset
    The character-set to be used for reading and writing. You do not need to be aware of Perl's internal encoding for the characters.

$obj->filename
    Returns the FILENAME, as derived from read() or specified during initiation with new(filename).

$obj->index
    Returns a HASH of all defined PO objects, organized by msgid. Please try to avoid using this: use msgid() for lookup and add() for adding translations.

  Managing PO's

$obj->add(PO)
    Add the information from a PO into this POT. If the msgid of the PO is already known, that is an error.

$obj->header([FIELD, [CONTENT]])
    The translation of a blank MSGID is used to store a MIME header, which contains some meta-data. When only a FIELD is specified, that content is looked-up (case-insensitive) and returned. When a CONTENT is specified, the knowledge will be stored. In latter case, the header structure may get created. When the CONTENT is set to "undef", the field will be removed.

$obj->msgid(STRING)
    Lookup the Log::Report::Lexicon::PO with the STRING. If you want to add a new translation, use add(). Returns "undef" when not defined.

$obj->msgstr(MSGID, [COUNT])
    Returns the translated string for MSGID. When not specified, COUNT is 1.

$obj->nrPlurals
    Returns the number of plurals, when not known then '2'.

$obj->pluralIndex(COUNT)
    Returns the msgstr index used to translate a value of COUNT.

$obj->removeReferencesTo(FILENAME)
    Remove all the references to the indicate FILENAME from all defined translations. Returns the number of refs left.

$obj->stats
    Returns a HASH with some statistics about this POT table.

$obj->translations([ACTIVE])
    Returns a list with all defined Log::Report::Lexicon::PO objects. When the string "ACTIVE" is given as parameter, only objects which have references are returned.

$obj->updated([DATE])
    Replace the "PO-Revision-Date" with the specified DATE, or the current moment.

DIAGNOSTICS

Error: charset parameter is required
Error: no filename or file-handle specified for PO
    When a PO file is written, then a filename or file-handle must be specified explicitly, or set beforehand using the filename() method, or known because the write follows a read() of the file.

Error: only acceptable parameter is 'ACTIVE'
Error: textdomain parameter is required

SEE ALSO
This module is part of Log-Report distribution version 0.94, built on August 23, 2011. Website: http://perl.overmeer.net/log-report/

LICENSE
Copyrights 2007-2011 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html