view release on metacpan or  search on metacpan

lib/Getopt/Guided.pod  view on Meta::CPAN

is repeated, its initial value (its IV value) will be incremented by one on
each occurrence.  Use case: A verbosity level can be represented by a "v+"
incrementable flag.

=head1 SEMANTIC

The C<processopts( \@@ )> function adds semantic to the parse result provided
by the C<getopts()> function.

The command-line arguments list C<@argv> is the first parameter of the
C<processopts()> function.  The list must be passed by reference. A possible
value of this parameter is the global C<ARGV> array.  The remaining function
parameters form a non-empty list with an even number of elements. Each
even-numbered element represents a single "option specification".  The element
that follows such an option specification (an odd-numbered element) is called
its "option destination". The destination has to be a SCALAR, an ARRAY,
a HASH, or a CODE reference.

The option specification/option destination pairs are applied in order to
the parse result. This feature can be used to implement best practices such
as ensuring that a "-V" (version) option should have a higher precedence
(semantic priority) than a "-h" (help) option:

  processopts @argv, 'V' => sub { ... }, 'h' => sub { ... };

If an option belongs to the parse result and its destination is a SCALAR
reference, this reference points to the value of the corresponding C<%opts>
name-value map entry.

If a list option belongs to the parse result and its destination is an ARRAY
reference, this reference points to the list value of the corresponding
C<%opts> name-value map entry.

If a map option belongs to the parse result and its destination is a HASH
reference, this reference points to the hash value of the corresponding
C<%opts> name-value map entry.

If an option belongs to the parse result and its destination is a CODE
reference, the corresponding anonymous callback function is called with the
option-argument value (or the flag value) as its first, with the option
name as its second, and with the option-argument indicator (or flag-type
indicator) as its third argument. If the option (or flag) has no indicator,
the third argument is an empty string. The callback function is invoked in
scalar context. If the callback function returns the end of options delimiter
(C<-->), the C<processopts()> function stops prematurely. EOOD is a constant
that returns the end of options delimiter.

The C<processopts()> function returns true (C<!!1>) on success; otherwise the
function returns false (C<!!0>). If the function stops prematurely, its return
value for true changes to the option name prefixed by the options delimiter.

=head1 DEFAULT OPTIONS

The C<readopts( \@ )> function reads default command-line options from a
rcfile and prepends them to the command-line arguments list C<@argv>. This
function is usually called immediately before the C<processopts()> function.

The basename of the rcfile is the program name with the
extension C<rc>. The dirname of the rcfile is defined by the
environment variable XDG_CONFIG_HOME (L<XDG Base Directory
Specification|https://specifications.freedesktop.org/basedir/latest/>).

The rcfile must contain one option per line. This implies that options must
not be grouped. Each line is either a simple flag name or an option name
followed by a space character and an option-argument value. Neither the
flag name nor the option name should start with the option delimiter (C<->).
Option-argument values should not be quoted even if they include spaces.
Example rcfile content:

  # verbose
  v
  # jobs
  j 9

=head1 PROGRAM VERSION

The GNU coding standard provides some guideline how a "-V" (version) option
should behave. This module provides the C<print_version_info()> function. It
can be used as a "-V" option destination callback function. The function
implements some recommendations. It prints information about the program name
(the basename of L<$0|perlvar/$0>), and its version to standard output. As
a second information line it prints the version of the perl interpreter to
standard output too. Example output:

  foo v1.2.3
  perl v5.14.2

The function returns the end of options delimiter, so that the C<processopts()>
function stops prematurely.

=head1 SEE ALSO

=over 2

=item *

L<Tie::Hash::MultiValueOpts>

=item *

L<Tacit list of POSIX short options|https://stackoverflow.com/questions/56131811/is-there-a-tacit-list-of-reserved-names-for-posix-short-options>

=item *

L<The -W option of GNU getopt()|https://stackoverflow.com/questions/14338223/what-is-the-w-option-of-gnu-getopt-used-for>

=item *

L<Getopt::ArgvFile>

=item *

L<Configuration file for command-line options|https://pasdoc.github.io/ConfigFileOption>

=back

=head1 AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

=head1 COPYRIGHT AND LICENSE