NAME

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

INHERITANCE

        Log::Report::Lexicon::POT
          is a Log::Report::Lexicon::Table

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('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 record
       will be represented by a Log::Report::Lexicon::PO.

       See documentation in the base class.

METHODS

       See documentation in the base class.

   Constructors
       See documentation in the base class.

       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
             plural_forms  <constructed from nr_plurals and plural_alg>
             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.

           plural_forms => RULE
             [0.992] When this option is used, it overrules "nr_plurals" and "plural_alg".  The
             RULE should be a full "Plural-Forms" field.

           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
       See documentation in the base class.

       $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
       See documentation in the base class.

       $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->updated([DATE])
           Replace the "PO-Revision-Date" with the specified DATE, or the current moment.

       Translation

       See documentation in the base class.

       $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 COUNT is not specified, the translation
           string related to "1" is returned.

       Administration

       See documentation in the base class.

       $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->nrPlurals()
           See "Administration" in Log::Report::Lexicon::Table

       $obj->pluralIndex(COUNT)
           See "Administration" in Log::Report::Lexicon::Table

       $obj->setupPluralAlgorithm()
           See "Administration" in Log::Report::Lexicon::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.

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.998, built on October 22, 2013.
       Website: http://perl.overmeer.net/log-report/

LICENSE

       Copyrights 2007-2013 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