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

       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.

       Extends "DESCRIPTION" in Log::Report::Lexicon::Table.

       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

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

       Copyrights 2007-2025 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/

perl v5.40.1                                       2025-04-24                     Log::Report::Lexicon::POT(3pm)

       Extends "METHODS" in Log::Report::Lexicon::Table.

   Constructors
       Extends "Constructors" in Log::Report::Lexicon::Table.

       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       'UTF-8'
             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 charset to be used for the createed file.  It is unwise to use anything else than 'UTF-8',  but
             allowed.  Before [1.09] this option was required.

           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.

       $obj->write( [$filename|$fh], %options )
           When you pass an open $fh, 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.

            -Option     --Default
             only_active  false

           only_active => BOOLEAN
             [1.02] Do not write records which do have a translation, but where the msgid has  disappeared  from
             the sources.  By default, these records are commented out (marked with '#~') but left in the file.

   Attributes
       Extends "Attributes" in Log::Report::Lexicon::Table.

       $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.

       $obj->language()
           Returns the language code, which is derived from the filename.

   ManagingPO's
       Extends "Managing PO's" in Log::Report::Lexicon::Table.

       $obj->keepReferencesTo($table)
           Remove all references which are not found  as  key  in  the  hash  $table.   Returns  the  number  of
           references left.

       $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

       Extends "Translation" in Log::Report::Lexicon::Table.

       $obj->msgid( STRING, [$msgctxt] )
           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, [$msgctxt]] )
           Returns  the  translated string for $msgid.  When $count is not specified or "undef", the translation
           string related to "1" is returned.

       Administration

       Extends "Administration" in Log::Report::Lexicon::Table.

       $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()
           Inherited, see "Administration" in Log::Report::Lexicon::Table

       $obj->pluralIndex($count)
           Inherited, see "Administration" in Log::Report::Lexicon::Table

       $obj->setupPluralAlgorithm()
           Inherited, 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.

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

       This module is part of Log-Report-Lexicon distribution version 1.12, built on April  18,  2025.  Website:
       http://perl.overmeer.net/CPAN/

        # 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');
        my $po = $pot->msgid($msgid, $msgctxt);
        print $pot->nrPlurals;
        print $pot->msgstr('msgid', 3);
        print $pot->msgstr($msgid, 3, $msgctxt);
        $pot->write;  # update the file

        # fill the table, by calling the next a lot
        my $po  = Log::Report::Lexicon::PO->new(...);
        $pot->add($po);

        # creating a PO table
        $pot->write('po/nl.po')
            or die;