/ 
Getopt-Guided-v3.0.1
/ Getopt::Guided

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' )

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:

  1. illegal option

  2. 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.

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.