.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Locale::XGettext 3pm"
.TH Locale::XGettext 3pm "2023-02-05" "perl v5.36.0" "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"
Locale::XGettext \- Extract Strings To PO Files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use base \*(AqLocale::XGettext\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBLocale::XGettext\fR is the base class for various string extractors.  These
string extractors can be used as standalone programs on the command-line or
as a module as a part of other software.
.PP
See <https://github.com/gflohr/Locale\-XGettext> for an overall picture of
the software.
.SH "USAGE"
.IX Header "USAGE"
This section describes the usage of extractors based on this library.
See \*(L"\s-1SUBCLASSING\*(R"\s0 and the sections following it for the \s-1API\s0 
documentation!
.PP
.Vb 1
\&    xgettext\-LANG [OPTIONS] [INPUTFILE]...
.Ve
.PP
\&\fB\s-1LANG\s0\fR will be replaced by an identifier for the language that a specific
extractor was written for, for example \*(L"xgettext-txt\*(R" for plain text files
or \*(L"xgettext\-tt2\*(R" for templates for the Template Toolkit version 2 (see
Template).
.PP
By default, string extractors based on this module extract strings from
one or more \fB\s-1INPUTFILES\s0\fR and write the output to a file \*(L"messages.po\*(R" if
any strings had been found.
.SH "OPTIONS"
.IX Header "OPTIONS"
The command line options are mostly compatible to
\&\fIxgettext\fR from \s-1GNU\s0
Gettext <https://www.gnu.org/software/gettext/manual/html_node/xgettext-Invocation.html>.
.SS "\s-1INPUT FILE LOCATION\s0"
.IX Subsection "INPUT FILE LOCATION"
.IP "\fB\s-1INPUTFILE...\s0\fR" 4
.IX Item "INPUTFILE..."
All non-option arguments are interpreted as input files containing strings to
be extracted.  If the input file is \*(L"\-\*(R", standard input is read.
.IP "\fB\-f \s-1FILE\s0\fR" 4
.IX Item "-f FILE"
.PD 0
.IP "\fB\-\-files\-from=FILE\fR" 4
.IX Item "--files-from=FILE"
.PD
Read the names of the input files from \fB\s-1FILE\s0\fR instead of getting them from the
command line.
.Sp
\&\fBNote!\fR Unlike xgettext from \s-1GNU\s0 Gettext, extractors based on 
\&\fBLocale::XGettext\fR accept this option multiple times, so that you can read 
the list of input files from multiple files.
.IP "\fB\-D \s-1DIRECTORY\s0\fR" 4
.IX Item "-D DIRECTORY"
.PD 0
.IP "\fB\-\-directory=DIRECTORY\fR" 4
.IX Item "--directory=DIRECTORY"
.PD
Add \fB\s-1DIRECTORY\s0\fR to the list of directories. Source files are searched 
relative to this list of directories. The resulting .po file will be written 
relative to the current directory, though.
.SS "\s-1OUTPUT FILE LOCATION\s0"
.IX Subsection "OUTPUT FILE LOCATION"
.IP "\fB\-d \s-1NAME\s0\fR" 4
.IX Item "-d NAME"
.PD 0
.IP "\fB\-\-default\-domain=NAME\fR" 4
.IX Item "--default-domain=NAME"
.PD
Use \fB\s-1NAME\s0\fR.po for output (instead of \fImessages.po\fR).
.IP "\fB\-o \s-1FILE\s0\fR" 4
.IX Item "-o FILE"
.PD 0
.IP "\fB\-\-output=FILE\fR" 4
.IX Item "--output=FILE"
.PD
Write output to specified \fI\f(BI\s-1FILE\s0\fI\fR (instead of \fI\f(BI\s-1NAME\s0\fI.po\fR or 
\&\fImessages.po\fR).
.IP "\fB\-p \s-1DIR\s0\fR" 4
.IX Item "-p DIR"
.PD 0
.IP "\fB\-\-output\-dir=DIR\fR" 4
.IX Item "--output-dir=DIR"
.PD
Output files will be placed in directory \fB\s-1DIR\s0\fR.
.Sp
If the output file is \fB\-\fR or \fI/dev/stdout\fR, the output is written to standard 
output.
.SS "\s-1INPUT FILE INTERPRETATION\s0"
.IX Subsection "INPUT FILE INTERPRETATION"
.IP "\fB\-\-from\-code=NAME\fR" 4
.IX Item "--from-code=NAME"
Specifies the encoding of the input files. This option is needed only if some 
untranslated message strings or their corresponding comments contain non-ASCII 
characters.
.Sp
By default the input files are assumed to be in \s-1ASCII.\s0
.Sp
\&\fBNote!\fR Some extractors have a fixed input set, \s-1UTF\-8\s0 most of the times.
.SS "\s-1OPERATION MODE\s0"
.IX Subsection "OPERATION MODE"
.IP "\fB\-j\fR" 4
.IX Item "-j"
.PD 0
.IP "\fB\-\-join\-existing\fR" 4
.IX Item "--join-existing"
.PD
Join messages with existing files.  This is a shortcut for adding the
output file to the list of input files.  The output file is read, and
then all messages from other input files are added.
.Sp
For obvious reasons, you cannot use this option if output is written
to standard output.
.IP "\fB\-x \s-1FILE\s0.po\fR" 4
.IX Item "-x FILE.po"
.PD 0
.IP "\fB\-\-exclude\-file=FILE.po\fR" 4
.IX Item "--exclude-file=FILE.po"
.PD
\&\s-1PO\s0 entries that are present in \fI\s-1FILE\s0.po\fR are not extracted.
.IP "\fB\-c \s-1TAG\s0\fR" 4
.IX Item "-c TAG"
.PD 0
.IP "\fB\-\-add\-comments=TAG\fR" 4
.IX Item "--add-comments=TAG"
.PD
Place comment blocks starting with \fB\s-1TAG\s0\fR in the output
if they precede a keyword line.
.IP "\fB\-c\fR" 4
.IX Item "-c"
.PD 0
.IP "\fB\-\-add\-comments\fR" 4
.IX Item "--add-comments"
.PD
Place all comment blocks that precede a keyword line in the output.
.SS "LANGUAGE-SPECIFIC-OPTIONS"
.IX Subsection "LANGUAGE-SPECIFIC-OPTIONS"
.IP "\fB\-a\fR" 4
.IX Item "-a"
.PD 0
.IP "\fB\-\-extract\-all\fR" 4
.IX Item "--extract-all"
.PD
Extract \fBall\fR strings, not just the ones marked with keywords.
.Sp
\&\fBNot all extractors support this option!\fR
.IP "\fB\-k \s-1WORD\s0\fR" 4
.IX Item "-k WORD"
.PD 0
.IP "\fB\-\-keyword=WORD\fR" 4
.IX Item "--keyword=WORD"
.PD
Use \fB\s-1WORD\s0\fR as an additional keyword.
.Sp
\&\fBNot all extractors support this option!\fR
.IP "\fB\-k\fR" 4
.IX Item "-k"
.PD 0
.IP "\fB\-\-keyword\fR" 4
.IX Item "--keyword"
.PD
Do not use default keywords!  If you define your own keywords, you
use usually give the option '\-\-keyword' first without an argument to
reset the keyword list to empty, and then you give a '\-\-keyword'
option for everyt keyword wanted.
.Sp
\&\fBNot all extractors support this option!\fR
.IP "\fB\-\-flag=WORD:ARG:FLAG\fR" 4
.IX Item "--flag=WORD:ARG:FLAG"
Original explanation from \s-1GNU\s0 gettext:
.RS 4
.Sp
.RS 4
Specifies additional flags for strings occurring as part of the \fIarg\fRth
argument of the function \fIword\fR. The possible flags are the possible
format string indicators, such as Xc-formatX, and their negations,
such as Xno-c-formatX, possibly prefixed with Xpass-X.
.Sp
The meaning of \-\-flag=\fIfunction:arg:lang\-format\fR is that in language
\&\fIlang\fR, the specified \fIfunction\fR expects as \fIarg\fRth argument a format string.
(For those of you familiar with \s-1GCC\s0 function attributes, 
\&\-\-flag=\fIfunction:arg\fR:c\-format is roughly equivalent to the declaration
X_\|_attribute_\|_ ((_\|_format_\|_ (_\|_printf_\|_, \fIarg\fR, ...)))X attached to \fIfunction\fR
in a C source file.) For example, if you use the XerrorX function from
\&\s-1GNU\s0 libc, you can specify its behaviour through \-\-flag=error:3:c\-format.
The effect of this specification is that xgettext will mark as format
strings all gettext invocations that occur as \fIarg\fRth argument of \fIfunction\fR.
This is useful when such strings contain no format string directives:
together with the checks done by Xmsgfmt \-cX it will ensure that translators
cannot accidentally use format string directives that would lead to a
crash at runtime.
.Sp
The meaning of \-\-flag=\fIfunction:arg\fR:pass\-\fIlang\fR\-format is that in language
\&\fIlang\fR, if the \fIfunction\fR call occurs in a position that must yield a format
string, then its \fIarg\fRth argument must yield a format string of the same
type as well. (If you know \s-1GCC\s0 function attributes, the 
\&\-\-flag=\fIfunction:arg\fR:pass\-c\-format option is roughly equivalent to the
declaration X_\|_attribute_\|_ ((_\|_format_arg_\|_ (\fIarg\fR)))X attached to function
in a C source file.) For example, if you use the X_X shortcut for the
gettext function, you should use \-\-flag=_:1:pass\-c\-format. The effect of
this specification is that xgettext will propagate a format string
requirement for a _(\*(L"string\*(R") call to its first argument, the literal
\&\*(L"string\*(R", and thus mark it as a format string. This is useful when such
strings contain no format string directives: together with the checks
done by Xmsgfmt \-cX it will ensure that translators cannot accidentally
use format string directives that would lead to a crash at runtime.
.RE
.RE
.RS 4
.Sp
Note that \fBLocale::XGettext\fR ignores the prefix \fIpass\-\fR and therefore
most extractors based on \fBLocale::XGettext\fR will also ignore it.
.RE
.PP
Individual extractors may define more language-specific options.
.SS "Output Details"
.IX Subsection "Output Details"
.IP "\fB\-\-force\-po\fR" 4
.IX Item "--force-po"
Write \s-1PO\s0 file even if empty.  Normally, empty \s-1PO\s0 files are not written,
and existing output files are not overwritten if they would be empty.
.IP "\fB\-\-no\-location\fR" 4
.IX Item "--no-location"
Do not write '#: filename:line' lines into the output \s-1PO\s0 files.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-add\-location\fR" 4
.IX Item "--add-location"
.PD
Generate '#: filename:line' lines in the output \s-1PO\s0 files.  This is the
default.
.IP "\fB\-s\fR" 4
.IX Item "-s"
.PD 0
.IP "\fB\-\-sort\-output\fR" 4
.IX Item "--sort-output"
.PD
Sort output entries alphanumerically.
.IP "\fB\-F\fR" 4
.IX Item "-F"
.PD 0
.IP "\fB\-\-sort\-by\-file\fR" 4
.IX Item "--sort-by-file"
.PD
Sort output entries by source file location.
.IP "\fB\-\-omit\-header\fR" 4
.IX Item "--omit-header"
Do not write header with meta information.  The meta information is
normally included as the \*(L"translation\*(R" for the empty string.
.Sp
If you want to hava a translation for an empty string you should also
consider using message contexts.
.IP "\fB\-\-copyright\-holder=STRING\fR" 4
.IX Item "--copyright-holder=STRING"
Set the copyright holder to \fB\s-1STRING\s0\fR in the output \s-1PO\s0 file.
.IP "\fB\-\-foreign\-user\fR" 4
.IX Item "--foreign-user"
Omit \s-1FSF\s0 copyright in output for foreign user.
.IP "\fB\-\-package\-name=PACKAGE\fR" 4
.IX Item "--package-name=PACKAGE"
Set package name in output
.IP "\fB\-\-package\-version=VERSION\fR" 4
.IX Item "--package-version=VERSION"
Set package version in output.
.IP "\fB\-\-msgid\-bugs\-address=EMAIL@ADDRESS\fR" 4
.IX Item "--msgid-bugs-address=EMAIL@ADDRESS"
Set report address for msgid bugs.
.IP "\fB\-m[\s-1STRING\s0]\fR" 4
.IX Item "-m[STRING]"
.PD 0
.IP "\fB\-\-msgstr\-prefix[=STRING]\fR" 4
.IX Item "--msgstr-prefix[=STRING]"
.PD
Use \s-1STRING\s0 or "" as prefix for msgstr values.
.IP "\fB\-M[\s-1STRING\s0]\fR" 4
.IX Item "-M[STRING]"
.PD 0
.IP "\fB\-\-msgstr\-suffix[=STRING]\fR" 4
.IX Item "--msgstr-suffix[=STRING]"
.PD
Use \s-1STRING\s0 or "" as suffix for msgstr values.
.SS "\s-1INFORMATIVE OUTPUT\s0"
.IX Subsection "INFORMATIVE OUTPUT"
.IP "\fB\-h\fR" 4
.IX Item "-h"
.PD 0
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
.PD
Display short help and exit.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Output version information and exit.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Writing a complete extractor script in Perl with \fBLocale::XGettext\fR
is as simple as:
.PP
.Vb 1
\&    #! /usr/bin/env perl
\&
\&    use Locale::Messages qw(setlocale LC_MESSAGES);
\&    use Locale::TextDomain qw(YOURTEXTDOMAIN);
\&
\&    use Locale::XGettext::YOURSUBCLASS;
\&
\&    Locale::Messages::setlocale(LC_MESSAGES, "");
\&    Locale::XGettext::YOURSUBCLASS\->newFromArgv(\e@ARGV)\->run\->output;
.Ve
.PP
Writing the extractor class is also trivial:
.PP
.Vb 1
\&    package Locale::XGettext::YOURSUBCLASS;
\&
\&    use base \*(AqLocale::XGettext\*(Aq;
\&
\&    sub readFile {
\&        my ($self, $filename) = @_;
\&
\&        foreach my $found (search_for_strings_in $filename) {
\&            $self\->addEntry({
\&                msgid => $found\->{string},
\&                # More possible fields following, see 
\&                # addEntry() below!
\&            }, $found\->{possible_comment});
\&        }
\&
\&        # The return value is actually ignored.
\&        return $self;
\&    }
.Ve
.PP
All the heavy lifting happens in the method \fB\fBreadFile()\fB\fR that you have
to implement yourself.  All other methods are optional.
.PP
See the section \*(L"\s-1METHODS\*(R"\s0 below for information on how to
additionally modify the behavior your extractor.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.IP "\fBnew \f(CB$OPTIONS\fB, \f(CB@FILES\fB\fR" 4
.IX Item "new $OPTIONS, @FILES"
\&\fB\s-1OPTIONS\s0\fR is a hash reference containing the above command-line
options but with every hyphen replaced by an underscore.  You
should normally not use this constructor!
.IP "\fBnewFromArgv \f(CB$ARGV\fB\fR" 4
.IX Item "newFromArgv $ARGV"
\&\fB\s-1ARGV\s0\fR is a reference to a an array of command-line arguments
that is passed verbatim to \fBGetopt::Long::GetOptionsFromArray\fR.
After processing all options and arguments, the constructor
\&\fB\fBnew()\fB\fR above is then invoked with the cooked command-line
arguments.
.Sp
This is the constructor that you should normally use in 
custom extractors that you write.
.SH "METHODS"
.IX Header "METHODS"
\&\fBLocale::XGettext\fR is an abstract base class.  All public methods
may be overridden by subclassed extractors.
.IP "\fBreadFile \s-1FILENAME\s0\fR" 4
.IX Item "readFile FILENAME"
You have to implement this method yourself.  In it, read \fB\s-1FILENAME\s0\fR,
extract all relevant entries, and call \fB\fBaddEntry()\fB\fR for each entry
found.
.Sp
The method is not invoked for filenames ending in \*(L".po\*(R" or \*(L".pot\*(R"!
For those files, \fB\fBreadPO()\fB\fR is invoked instead.
.Sp
This method is the only one that you have to implement!
.IP "\fBaddEntry ENTRY[, \s-1COMMENT\s0]\fR" 4
.IX Item "addEntry ENTRY[, COMMENT]"
You should invoke this  method for every entry found.
.Sp
\&\fB\s-1COMMENT\s0\fR is an optional comment that you may have extracted along 
with the message.  Note that \fB\fBaddEntry()\fB\fR checks whether this
comment should make it into the output.  Therefore, just pass any
comment that you have found preceding the keyword.
.Sp
\&\fB\s-1ENTRY\s0\fR should be a reference to a hash with these possible
keys:
.RS 4
.IP "\fBmsgid\fR" 8
.IX Item "msgid"
The entry's message id.
.IP "\fBmsgid_plural\fR" 8
.IX Item "msgid_plural"
A possible plural form.
.IP "\fBmsgctxt\fR" 8
.IX Item "msgctxt"
A possible message context.
.IP "\fBreference\fR" 8
.IX Item "reference"
A source reference in the form \*(L"\s-1FILENAME: LINENO\*(R".\s0
.IP "\fBflags\fR" 8
.IX Item "flags"
Set a flag for this entry, for example \*(L"perl-brace-format\*(R" or
\&\*(L"no-perl-brace-format\*(R".  You can comma-separate multiple
flags.
.IP "\fBkeyword\fR" 8
.IX Item "keyword"
The keyword that triggered the entry.  If you set this
property and the keyword definition contained an automatic
comment, the comment will be added.  You can try this out
like this:
.Sp
.Vb 1
\&    xgettext\-my.pl \-\-keyword=greet:1,\*(Aq"Hello, world!"\*(Aq
.Ve
.Sp
If you set \fBkeyword\fR to \*(L"greet\*(R", the comment \*(L"Hello, world\*(R"
will be added.  Note that the \*(L"double quotes\*(R" are part of the
command-line argument!
.Sp
Likewise, if \*(L"\-\-flag\*(R" was specified on the command-line or
the extractor ships with default flags, entries matching
the flag definition will automatically have this flag.
.Sp
You can try this out with:
.Sp
.Vb 1
\&    xgettext\-my.pl \-\-keyword="greet:1" \-\-flag=greet:1:hello\-format
.Ve
.Sp
Now all \s-1PO\s0 entries for the keyword \*(L"greet\*(R" will have the
flag \*(L"hello-format\*(R"
.IP "\fBfuzzy\fR" 8
.IX Item "fuzzy"
True if the entry is fuzzy.  There is no reason to use this
in string extractors because they typically product .pot
files without translations.
.IP "\fBautomatic\fR" 8
.IX Item "automatic"
Sets an automatic comment, not recommended.  Rather set
the keyword (see above) and let \fBLocale::XGettext\fR set the
comment as appropriate.
.RE
.RS 4
.Sp
Instead of a hash you can currently also pass a 
\&\fBLocale::PO\fR object.  This may no longer be supported in
the future.  Do not use!
.RE
.IP "\fBkeywords\fR" 4
.IX Item "keywords"
Return a hash reference with all keyword definitions as
Locale::XGettext::Util::Keyword objects.
.IP "\fBkeywordOptionStrings\fR" 4
.IX Item "keywordOptionStrings"
Return a reference to an array with all keyword definitions
as option strings suitable for the command-line option
\&\*(L"\-\-keyword\*(R".
.IP "\fBflags\fR" 4
.IX Item "flags"
Return an array reference with all flag definitions as
Locale::XGettext::Util::Flag objects.
.IP "\fBflagOptionStrings\fR" 4
.IX Item "flagOptionStrings"
Return a reference to an array with all flag definitions
as option strings suitable for the command-line option
\&\*(L"\-\-flag\*(R".
.IP "\fBoptions\fR" 4
.IX Item "options"
Get all command-line options as a hash reference.
.IP "\fBoption \s-1OPTION\s0\fR" 4
.IX Item "option OPTION"
Get the value for command line option \fB\s-1OPTION\s0\fR.
.IP "\fBsetOption \s-1OPTION, VALUE\s0\fR" 4
.IX Item "setOption OPTION, VALUE"
Set the value for command line option \fB\s-1OPTION\s0\fR to \fB\s-1VALUE\s0\fR.
.IP "\fBlanguageSpecificOptions\fR" 4
.IX Item "languageSpecificOptions"
The default representation returns nothing.
.Sp
Your own implementation can return an reference to an array of
arrays, each of them containing one option specification
consisting of four items:
.RS 4
.IP "\(bu" 8
The option specification for \fBGetopt::Long\fR\|(3pm), for example
\&\*(L"f|filename=s\*(R" for an option expecting a mandatory
string argument.
.IP "\(bu" 8
The name of the option.  This is what gets passed to \fBoption()\fR
above.  It should generally be the long option name with hyphens
converted to underscores.
.IP "\(bu" 8
The option description for the usage information, for example
\&\*(L"\-f, \-\-files=STRING\*(R" for options taking arguments or 
something like \*(L"    \-\-verbose\*(R" for long-only options.  This
is printed in the left column, when you invoke your extractor
with \*(L"\-\-help\*(R".
.IP "\(bu" 8
The description of this option.  This is printed in the right
column, when you invoke your extractor with \*(L"\-\-help\*(R".
.RE
.RS 4
.RE
.IP "\fBprintLanguageSpecificOptions\fR" 4
.IX Item "printLanguageSpecificOptions"
Prints all language-specific options to standard output, calls
\&\fBlanguageSpecificOptions()\fR internally.  This is used for the
output for the option \*(L"\-\-help\*(R".
.IP "\fBfileInformation\fR" 4
.IX Item "fileInformation"
Returns nothing by default.  You can return a string describing
the expected input format, when invoked with \*(L"\-\-help\*(R".
.IP "\fBversionInformation\fR" 4
.IX Item "versionInformation"
Returns nothing by default.  You can return a string that is
printed, when invoked with \*(L"\-\-version\*(R".
.IP "\fBbugTrackingAddress\fR" 4
.IX Item "bugTrackingAddress"
Returns nothing by default.  You can return a string describing
the bug tracking address, when invoked with \*(L"\-\-help\*(R".
.IP "\fBcanExtractAll\fR" 4
.IX Item "canExtractAll"
Returns false by default.  Return a truthy value if your extractor
supports the option \*(L"\-\-extract\-all\*(R".
.IP "\fBcanKeywords\fR" 4
.IX Item "canKeywords"
Returns true by default.  Return a false value if your extractor
does not support the option \*(L"\-\-keyword\*(R".
.IP "\fBcanFlags\fR" 4
.IX Item "canFlags"
Returns true by default.  Return a false value if your extractor
does not support the option \*(L"\-\-flag\*(R".
.IP "\fBneedInputFiles\fR" 4
.IX Item "needInputFiles"
Returns true by default.  Return a false value if your extractor
does not support input from files.  In this case you should
implement \fBreadFromNonFiles()\fR.
.IP "\fBprogramName\fR" 4
.IX Item "programName"
Return the name of the program for usage and help information.  Defaults
to just \f(CW$0\fR but you can return another value here.
.IP "\fBrun\fR" 4
.IX Item "run"
Runs the extractor once.  The default implementation scans all
input sources for translatable strings and collects them.
.IP "\fBoutput\fR" 4
.IX Item "output"
Print the output as a \s-1PO\s0 file to the specified output location.
.IP "\fBextractFromNonFiles\fR" 4
.IX Item "extractFromNonFiles"
This method is invoked after all input files have been processed.
The default implementation does nothing.  You may use the method
for extracting strings from additional sources like a database.
.IP "\fBresolveFilename \s-1FILENAME\s0\fR" 4
.IX Item "resolveFilename FILENAME"
Given an input filename \fB\s-1FILENAME\s0\fR the method returns the absolute
location of the file.  The default implementation honors the
option \*(L"\-D, \-\-directory\*(R".
.IP "\fBdefaultKeywords\fR" 4
.IX Item "defaultKeywords"
Returns a reference to an empty array.
.Sp
Subclasses may return a reference to an array with default keyword
definitions for the specific language.  The default keywords 
(actually just a subset for it) for the language C would look like 
this (expressed in \s-1JSON\s0):
.Sp
.Vb 6
\&    [
\&        "gettext:1",
\&        "ngettext:1,2",
\&        "pgettext:1c,2",
\&        "npgettext:1c,2,3"
\&    ]
.Ve
.Sp
See above the description of the command-line option \*(L"\-\-keyword\*(R"
for more information about the meaning of these strings.
.IP "\fBdefaultFlags\fR" 4
.IX Item "defaultFlags"
Returns a reference to an empty array.
.Sp
Subclasses may return a reference to an array with default flag
specifications for the specific language.  An example may look
like this (expressed in \s-1JSON\s0):
.Sp
.Vb 5
\&    [
\&        "gettextx:1:perl\-brace\-format",
\&        "ngettextx:1:perl\-brace\-format",
\&        "ngettextx:2:perl\-brace\-format",
\&    ]
.Ve
.Sp
We assume that \*(L"\fBgettextx()\fR\*(R" and \*(L"\fBgettextx()\fR are keywords for
the language in question.  The above default flag definition
would mean that in all invocations of the function \*(R"\fBgettextx()\fR\*(L",
the 1st argument would get the flag \*(R"perl-brace-format\*(L".  In
all invocations of \*(R"\fBngettextx()\fR\*(L", the 1st and 2nd argument would
get the flag \*(R"perl-brace-format".
.Sp
You can prefix the format with \*(L"no\-\*(R" which tells the \s-1GNU\s0 gettext
tools that the particular never uses that format.
.Sp
You can additionally prefix the format with \*(L"pass\-\*(R" but this
is ignored by Locale::XGettext.  If you want to implemnt the
\&\s-1GNU\s0 xgettext behavior for the \*(L"pass\-\*(R" prefix, you have to implement
it yourself in your extractor.
.IP "\fBrecodeEntry \s-1ENTRY\s0\fR" 4
.IX Item "recodeEntry ENTRY"
Gets invoked for every \s-1PO\s0 entry but \fIafter\fR it has been
promoted to a \fB\fBLocale::PO\fB\|(3pm)\fR object.  The implementation
of this method is likely to be changed in the future.
.Sp
Do not use!
.IP "\fBreadPO \s-1FILENAME\s0\fR" 4
.IX Item "readPO FILENAME"
Reads \fB\s-1FILENAME\s0\fR as .po or .pot file.  There is no reason why
you should override or invoke this method.
.IP "\fBpo\fR" 4
.IX Item "po"
Returns a list of \s-1PO\s0 entries represented by hash references.
Do not use or override this method!
.IP "\fBprintLanguageSpecificUsage\fR" 4
.IX Item "printLanguageSpecificUsage"
Prints the help for language-specific options.  Override it, 
if you are not happy with the formatting.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2016\-2017 Guido Flohr <guido.flohr@cantanea.com>,
all rights reserved.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Getopt::Long, \fBxgettext\fR\|(1), perl