NAME

       Log::Report::Lexicon::PO - one translation definition

SYNOPSIS

DESCRIPTION

       This module is administering one translation object.  Sets of PO records are kept in a POT
       file, implemented in Log::Report::Lexicon::POT.

METHODS

   Constructors
       Log::Report::Lexicon::PO->new(%options)
            -Option      --Default
             automatic     ""
             comment       []
             format        []
             fuzzy         false
             msgctxt       undef
             msgid         <required>
             msgid_plural  undef
             msgstr        "" or []
             references    []

           automatic => PARAGRAPH
             Automatically added comments.  See addAutomatic().

           comment => PARAGRAPH
             Translator added comments.  See addComment().

           format => ARRAY|HASH
             See format().  Either an ARRAY with PAIRS or a HASH with that same information.

           fuzzy => BOOLEAN
             The string is not yet translated, some smart guesses may have been made.  See
             fuzzy().

           msgctxt => STRING
             Context string: text around the msgid itself.

           msgid => STRING
           msgid_plural => STRING
           msgstr => STRING|ARRAY-OF-STRING
             The translations for the msgid.  When msgid_plural is defined, then an ARRAY must be
             provided.

           references => STRING|ARRAY-OF-LOCATIONS
             The STRING is a blank separated list of LOCATIONS.  LOCATIONs are of the  form
             "filename:linenumber", for instance "lib/Foo.pm:42" See addReferences()

   Attributes
       $obj->addAutomatic(LIST|ARRAY|STRING)
           Add multiple lines to the translator's comment block.  Returns an empty string if
           there are no comments.

       $obj->addComment(LIST|ARRAY|STRING)
           Add multiple lines to the translator's comment block.  Returns an empty string if
           there are no comments.

       $obj->addFlags(STRING)
           Parse a "flags" line.

       $obj->addReferences(STRING|LIST|ARRAY)
           The STRING is a blank separated list of LOCATIONS.  The LIST and ARRAY contain
           separate LOCATIONs.  A LOCATION is of the form "filename:linenumber".  Returns the
           internal HASH with references.

       $obj->automatic( [LIST|ARRAY|STRING] )
           Returns a STRING which contains the cleaned paragraph of automatically added comments.
           If an argument is specified, it will replace the current comment.

       $obj->comment( [LIST|ARRAY|STRING] )
           Returns a STRING which contains the cleaned paragraph of translator's comment.  If an
           argument is specified, it will replace the current comment.

       $obj->format( $language | <PAIRS|ARRAY|HASH> )
           When one $language is specified, it looks whether a "$language-format" or
           "no-$language-format" is present in the line of FLAGS.  This will return 1 (true) in
           the first case, 0 (false) in the second case.  It will return "undef" (also false) in
           case that both are not present.

           You can also specify PAIRS: the key is a language name, and the value is either 0, 1,
           or "undef".

           example: use of format()

            # getters
            if($po->format('c')) ...
            unless($po->format('perl-brace')) ...
            if(defined $po->format('java')) ...

            # setters
            $po->format(java => 1);       # results in 'java-format'
            $po->format(java => 0);       # results in 'no-java-format'
            $po->format(java => undef);   # results in ''

       $obj->fuzzy( [BOOLEAN] )
           Returns whether the translation needs human inspection.

       $obj->isActive()
           Returns whether the translation has any references, or is the header.

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

       $obj->msgctxt()
           Returns the message context, if provided.

       $obj->msgid()
           Returns the actual msgid, which cannot be "undef".

       $obj->msgstr( [$index, [STRING]] )
           With a STRING, a new translation will be set.  Without STRING, a lookup will take
           place.  When no plural is defined, the $index is ignored.

       $obj->plural( [STRING] )
           Returns the actual msgid_plural, which can be "undef".

       $obj->references( [STRING|LIST|ARRAY] )
           Returns an unsorted list of LOCATIONS.  When options are specified, then those will be
           used to replace all currently defined references.  Returns the unsorted LIST of
           references.

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

   Parsing
       Log::Report::Lexicon::PO->fromText( STRING, [$where] )
           Parse the STRING into a new PO object.  The $where string should explain the location
           of the STRING, to be used in error messages.

       $obj->toString(%options)
           Format the object into a multi-lined string.

            -Option    --Default
             nr_plurals  undef

           nr_plurals => INTEGER
             If the number of plurals is specified, then the plural translation list can be
             checked for the correct length.  Otherwise, no smart behavior is attempted.

       $obj->useless()
           [1.02] The message-id has no references anymore and no translations.

SEE ALSO

       This module is part of Log-Report-Lexicon distribution version 1.03, built on June 04,
       2014. Website: http://perl.overmeer.net/log-report/

LICENSE

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