NAME
Getopt::Guided - getopts implementation that follows POSIX utility guidelines
SYNOPSIS
use Getopt::Guided qw( getopts );
my @argv = qw( -d dv1 -c -va av1 -ddv2 -a av2 -d -- -vv v1 v2 );
# If omitted @argv defaults to @ARGV
getopts( 'a:bcd,v+', my %opts, @argv );
# Parse result
# %opts == ( a => 'av2', c => !!1, d => [ 'dv1', 'dv2', '--' ], v => 3 )
# @argv == ( 'v1', 'v2' )
# ---
use Getopt::Guided qw( print_version_info processopts );
my @argv = qw( -v -I lib -vv -I local/lib/perl5 );
processopts( @argv, 'V' => \&print_version_info, 'v+' => \my $verbosity, 'I,' => \my @inc );
# Processing result
# $verbosity == 3
# @inc == ( 'lib', 'local/lib/perl5' )
# @argv == ()DESCRIPTION
The getopts POSIX utility retrieves options and option-arguments from a list of command-line arguments. It supports the POSIX utility syntax guidelines 3 to 10, inclusive. getopts is an iterator. The variable OPTIND (option index) stores the position of the next element of the command-line argument list to be searched for an option name.
The getopts( $;$ ) function of the Getopt::Std Perl core module provides an implementation of the getopts utility. It isn't an iterator function but parses the command-line argument list in a single call. Getopt::Guided exposes a new implementation through the getopts( $\%;\@ ) function. The primary implementation differences are
Topic | Getopt::Std impl | Getopt::Guided impl
-------------------------+-------------------+----------------------------
exported | by default | on request
2nd parameter | hash reference | hash (passed by reference)
3rd parameter (optional) | none | array (passed by reference),
| | which defaults to @ARGV
unknown option | partial parse and | restore @ARGV and warn user
| warn user |
missing option-argument | partial parse and | restore @ARGV and warn user
| don't warn user |COMMAND-LINE ARGUMENTS
A list of command-line arguments consists of options, option-arguments, and operands. The arguments that consist of hyphen-minus (-) characters and single alphanumeric ([[:alnum:]]) characters, are known as options. Certain options are followed by an option-argument. The arguments following the last options and option-arguments are named operands.
In Perl the array @ARGV contains the command-line arguments.
OPTIONS SPECIFICATION
The options specification $spec is the first parameter of the getopts() function. It is a non-empty string containing the option names (the single alphanumeric characters) recognized by the getopts() function.
If an option name ("a") is followed by a colon (:) character or a comma (,) character, the option should have an option-argument which either shall be supplied as a separate argument ("-a foo") or shall be part of the same argument string as the option name ("-afoo"). We call an option whose option name is followed by a colon/comma "option-argument indicator" a "common option"/"list option". A list option is sometimes called "multi-value option". The POSIX standard knows only common options.
An option that does not require an option-argument is called a flag. The flag name can optionally be followed by an exclamation mark (!) character or a plus sign (+) character. We call a flag whose flag name is followed by an exclamation mark/plus sign "flag-type indicator" a "negatable flag"/an "incrementable flag". An incrementable flag is sometimes called "cumulative flag". The POSIX standard doesn't know flag-type indicators.
NAME-VALUE MAP
The name-value map %opts is the second parameter of the getopts() function. It is an empty hash (passed by reference) that stores the parse result of the getopts() function. Each hash key refers to an option name and the corresponding hash value refers to the option-argument value (or the flag value). The hash value of a list option is an array reference.
COMMAND-LINE ARGUMENTS LIST
The command-line arguments list @argv is the third (optional) parameter of the getopts() function. It must be passed by reference. If this parameter is omitted, the getopts() function defaults to using the global @ARGV array.
PARSING
The implementation follows the POSIX utility syntax guidelines 4 to 10, inclusive. The getopts() function warns and returns false if a parse error occurs; otherwise the function returns true. The parse error types are:
illegal option
option requires an argument
The 2nd parse error occurs if either no argument or the undef value is provided for an option that has to have an option-argument. If any of the parse errors occurs, the getopts() function restores @ARGV and clears %opts before it warns and returns false.
REPEATED OPTIONS
If a common option is repeated, its option-arguments overwrite each other and the last option-argument wins. If a list option is repeated, its option-arguments are pushed onto a list.
The appearance of a flag on the command line sets its value (initial value) to true (!!1). If a flag with no flag-type indicator is repeated, its initial value will not change. If a negatable flag is repeated, its initial value will be logically negated on each occurrence. If an incrementable flag 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.
SEMANTIC
The processopts( \@@ ) function adds semantic to the parse result provided by the getopts() function. The processopts() function is exported on request.
The command-line arguments list @argv is the first parameter of the processopts() function. The list must be passed by reference. A possible value of this parameter is the global 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, 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 option-argument value (or the flag value).
If a list option belongs to the parse result and its destination is an ARRAY reference, this reference points to the list of option-argument values.
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 (--), the processopts() function stops prematurely. EOOD is a constant that returns the end of options delimiter. The constant is exported on request.
The processopts() function returns true (!!1) on success; otherwise the function returns false (!!0). If the function stops prematurely, its return value for true changes to the option name prefixed by the options delimiter.
SEE ALSO
AUTHOR
Sven Willenbuecher <sven.willenbuecher@gmx.de>
COPYRIGHT AND LICENSE
This software is copyright (c) 2025 by Sven Willenbuecher.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.