.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Log::Report::Lexicon::POT 3pm"
.TH Log::Report::Lexicon::POT 3pm "2018-04-16" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Report::Lexicon::POT \- manage PO files
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Log::Report::Lexicon::POT
\&   is a Log::Report::Lexicon::Table
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # this is usually not for end\-users, See ::Extract::PerlPPI
\& # using a PO table
\&
\& my $pot = Log::Report::Lexicon::POT
\&    \->read(\*(Aqpo/nl.po\*(Aq, charset => \*(Aqutf\-8\*(Aq)
\&        or die;
\&
\& my $po = $pot\->msgid(\*(Aqmsgid\*(Aq);
\& my $po = $pot\->msgid($msgid, $msgctxt);
\& print $pot\->nrPlurals;
\& print $pot\->msgstr(\*(Aqmsgid\*(Aq, 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(\*(Aqpo/nl.po\*(Aq)
\&     or die;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is reading, extending, and writing \s-1POT\s0 files.  \s-1POT\s0 files
are used to store translations in humanly readable format for most of
existing translation frameworks, like \s-1GNU\s0 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.
.PP
The code is loosely based on Locale::PO, by Alan Schwartz.  The coding
style is a bit off the rest of \f(CW\*(C`Log::Report\*(C'\fR, and there was a need to
sincere simplification.  Each \s-1PO\s0 record will be represented by a
Log::Report::Lexicon::PO.
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Log::Report::Lexicon::Table.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Log::Report::Lexicon::Table.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Log::Report::Lexicon::Table.
.IP "Log::Report::Lexicon::POT\->\fBnew\fR(%options)" 4
.IX Item "Log::Report::Lexicon::POT->new(%options)"
Create a new \s-1POT\s0 file.  The initial header is generated for you, but
it can be changed using the \fIheader()\fR method.
.Sp
.Vb 10
\& \-Option      \-\-Default
\&  charset       \*(AqUTF\-8\*(Aq
\&  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
.Ve
.RS 4
.IP "charset => \s-1STRING\s0" 2
.IX Item "charset => STRING"
The charset to be used for the createed file.  It is unwise to use anything
else than '\s-1UTF\-8\s0', but allowed.  Before [1.09] this option was required.
.IP "date => \s-1STRING\s0" 2
.IX Item "date => STRING"
Overrule the date which is included in the generated header.
.IP "filename => \s-1STRING\s0" 2
.IX Item "filename => STRING"
Specify an output filename.  The name can also be specified when
\&\fIwrite()\fR is called.
.IP "index => \s-1HASH\s0" 2
.IX Item "index => HASH"
A set of translations (Log::Report::Lexicon::PO objects),
with msgid as key.
.IP "nr_plurals => \s-1INTEGER\s0" 2
.IX Item "nr_plurals => INTEGER"
The number of translations each of the translation with plural form
need to have.
.IP "plural_alg => \s-1EXPRESSION\s0" 2
.IX Item "plural_alg => EXPRESSION"
The algorithm to be used to calculate which translated msgstr to use.
.IP "plural_forms => \s-1RULE\s0" 2
.IX Item "plural_forms => RULE"
[0.992] When this option is used, it overrules \f(CW\*(C`nr_plurals\*(C'\fR and
\&\f(CW\*(C`plural_alg\*(C'\fR.  The \s-1RULE\s0 should be a full \*(L"Plural-Forms\*(R" field.
.IP "textdomain => \s-1STRING\s0" 2
.IX Item "textdomain => STRING"
The package name, used in the directory structure to store the
\&\s-1PO\s0 files.
.IP "version => \s-1STRING\s0" 2
.IX Item "version => STRING"
.RE
.RS 4
.RE
.PD 0
.ie n .IP "Log::Report::Lexicon::POT\->\fBread\fR($filename, %options)" 4
.el .IP "Log::Report::Lexicon::POT\->\fBread\fR($filename, \f(CW%options\fR)" 4
.IX Item "Log::Report::Lexicon::POT->read($filename, %options)"
.PD
Read the \s-1POT\s0 information from \f(CW$filename\fR.
.Sp
.Vb 2
\& \-Option \-\-Default
\&  charset  <required>
.Ve
.RS 4
.IP "charset => \s-1STRING\s0" 2
.IX Item "charset => STRING"
The character-set which is used for the file.  You must specify
this explicitly.
.RE
.RS 4
.RE
.ie n .IP "$obj\->\fBwrite\fR( [$filename|$fh], %options )" 4
.el .IP "\f(CW$obj\fR\->\fBwrite\fR( [$filename|$fh], \f(CW%options\fR )" 4
.IX Item "$obj->write( [$filename|$fh], %options )"
When you pass an open \f(CW$fh\fR, you are yourself responsible that
the correct character-encoding (binmode) is set.  When the write
followed a \fIread()\fR or the filename was explicitly set with \fIfilename()\fR,
then you may omit the first parameter.
.Sp
.Vb 2
\& \-Option     \-\-Default
\&  only_active  false
.Ve
.RS 4
.IP "only_active => \s-1BOOLEAN\s0" 2
.IX Item "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.
.RE
.RS 4
.RE
.SS "Attributes"
.IX Subsection "Attributes"
Extends \*(L"Attributes\*(R" in Log::Report::Lexicon::Table.
.ie n .IP "$obj\->\fBcharset\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBcharset\fR()" 4
.IX Item "$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.
.ie n .IP "$obj\->\fBfilename\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBfilename\fR()" 4
.IX Item "$obj->filename()"
Returns the \f(CW$filename\fR, as derived from \fIread()\fR or specified during
initiation with new(filename).
.ie n .IP "$obj\->\fBindex\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBindex\fR()" 4
.IX Item "$obj->index()"
Returns a \s-1HASH\s0 of all defined \s-1PO\s0 objects, organized by msgid.  Please try
to avoid using this: use \fImsgid()\fR for lookup and \fIadd()\fR for adding
translations.
.ie n .IP "$obj\->\fBlanguage\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlanguage\fR()" 4
.IX Item "$obj->language()"
Returns the language code, which is derived from the filename.
.SS "Managing \s-1PO\s0's"
.IX Subsection "Managing PO's"
Extends \*(L"Managing \s-1PO\s0's\*(R" in Log::Report::Lexicon::Table.
.ie n .IP "$obj\->\fBkeepReferencesTo\fR($table)" 4
.el .IP "\f(CW$obj\fR\->\fBkeepReferencesTo\fR($table)" 4
.IX Item "$obj->keepReferencesTo($table)"
Remove all references which are not found as key in the hash \f(CW$table\fR.
Returns the number of references left.
.ie n .IP "$obj\->\fBremoveReferencesTo\fR($filename)" 4
.el .IP "\f(CW$obj\fR\->\fBremoveReferencesTo\fR($filename)" 4
.IX Item "$obj->removeReferencesTo($filename)"
Remove all the references to the indicate \f(CW$filename\fR from all defined
translations.  Returns the number of refs left.
.ie n .IP "$obj\->\fBstats\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBstats\fR()" 4
.IX Item "$obj->stats()"
Returns a \s-1HASH\s0 with some statistics about this \s-1POT\s0 table.
.ie n .IP "$obj\->\fBupdated\fR( [$date] )" 4
.el .IP "\f(CW$obj\fR\->\fBupdated\fR( [$date] )" 4
.IX Item "$obj->updated( [$date] )"
Replace the \*(L"PO-Revision-Date\*(R" with the specified \f(CW$date\fR, or the current
moment.
.PP
\fITranslation\fR
.IX Subsection "Translation"
.PP
Extends \*(L"Translation\*(R" in Log::Report::Lexicon::Table.
.ie n .IP "$obj\->\fBmsgid\fR( \s-1STRING,\s0 [$msgctxt] )" 4
.el .IP "\f(CW$obj\fR\->\fBmsgid\fR( \s-1STRING,\s0 [$msgctxt] )" 4
.IX Item "$obj->msgid( STRING, [$msgctxt] )"
Lookup the Log::Report::Lexicon::PO with the \s-1STRING.\s0  If you
want to add a new translation, use \fIadd()\fR.  Returns \f(CW\*(C`undef\*(C'\fR
when not defined.
.ie n .IP "$obj\->\fBmsgstr\fR( $msgid, [$count, [$msgctxt]] )" 4
.el .IP "\f(CW$obj\fR\->\fBmsgstr\fR( \f(CW$msgid\fR, [$count, [$msgctxt]] )" 4
.IX Item "$obj->msgstr( $msgid, [$count, [$msgctxt]] )"
Returns the translated string for \f(CW$msgid\fR.  When \f(CW$count\fR is not specified or
\&\f(CW\*(C`undef\*(C'\fR, the translation string related to \*(L"1\*(R" is returned.
.PP
\fIAdministration\fR
.IX Subsection "Administration"
.PP
Extends \*(L"Administration\*(R" in Log::Report::Lexicon::Table.
.ie n .IP "$obj\->\fBadd\fR($po)" 4
.el .IP "\f(CW$obj\fR\->\fBadd\fR($po)" 4
.IX Item "$obj->add($po)"
Add the information from a \f(CW$po\fR into this \s-1POT.\s0  If the msgid of the \f(CW$po\fR
is already known, that is an error.
.ie n .IP "$obj\->\fBheader\fR( [$field, [$content]] )" 4
.el .IP "\f(CW$obj\fR\->\fBheader\fR( [$field, [$content]] )" 4
.IX Item "$obj->header( [$field, [$content]] )"
The translation of a blank \s-1MSGID\s0 is used to store a \s-1MIME\s0 header, which
contains some meta-data.  When only a \f(CW$field\fR is specified, that content is
looked-up (case-insensitive) and returned.  When a \f(CW$content\fR is specified,
the knowledge will be stored.  In latter case, the header structure
may get created.  When the \f(CW$content\fR is set to \f(CW\*(C`undef\*(C'\fR, the field will
be removed.
.ie n .IP "$obj\->\fBnrPlurals\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnrPlurals\fR()" 4
.IX Item "$obj->nrPlurals()"
Inherited, see \*(L"Administration\*(R" in Log::Report::Lexicon::Table
.ie n .IP "$obj\->\fBpluralIndex\fR($count)" 4
.el .IP "\f(CW$obj\fR\->\fBpluralIndex\fR($count)" 4
.IX Item "$obj->pluralIndex($count)"
Inherited, see \*(L"Administration\*(R" in Log::Report::Lexicon::Table
.ie n .IP "$obj\->\fBsetupPluralAlgorithm\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBsetupPluralAlgorithm\fR()" 4
.IX Item "$obj->setupPluralAlgorithm()"
Inherited, see \*(L"Administration\*(R" in Log::Report::Lexicon::Table
.ie n .IP "$obj\->\fBtranslations\fR( [$active] )" 4
.el .IP "\f(CW$obj\fR\->\fBtranslations\fR( [$active] )" 4
.IX Item "$obj->translations( [$active] )"
Returns a list with all defined Log::Report::Lexicon::PO objects. When
the string \f(CW$active\fR is given as parameter, only objects which have
references are returned.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Error: no filename or file-handle specified for \s-1PO\s0" 4
.IX Item "Error: no filename or file-handle specified for PO"
When a \s-1PO\s0 file is written, then a filename or file-handle must be
specified explicitly, or set beforehand using the \fIfilename()\fR
method, or known because the write follows a \fIread()\fR of the file.
.IP "Error: only acceptable parameter is '\s-1ACTIVE\s0'" 4
.IX Item "Error: only acceptable parameter is 'ACTIVE'"
.PD 0
.IP "Error: textdomain parameter is required" 4
.IX Item "Error: textdomain parameter is required"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Log-Report-Lexicon distribution version 1.11,
built on March 22, 2018. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2007\-2018 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR