/ 
Getopt-Long-Bash-0.5.0
/ getoptlong

NAME

getoptlong - Option parsing that does what you mean, for Bash

SYNOPSIS

Option definition:

declare -A OPTS=(
    [&USAGE]="command [options] file..."
    [verbose |v+                 # Verbosity     ]=0
    [output  |o:                 # Output file   ]=/dev/stdout
    [config  |c?                 # Config file   ]=
    [include |I@                 # Include paths ]=
    [define  |D%                 # Definitions   ]=
    [count   |n:=i               # Count integer ]=1
    [mode    |m:=(^(fast|slow)$) # Mode          ]=fast
)

One-liner:

. getoptlong.sh OPTS "$@"

Multi-step:

. getoptlong.sh -
getoptlong init OPTS
getoptlong parse "$@" && eval "$(getoptlong set)"

Or:

eval "$(getoptlong OPTS)"

VERSION

0.5.0

DESCRIPTION

getoptlong.sh is a Bash library providing Perl's Getopt::Long-style option parsing.

Options are defined in a Bash associative array: the key specifies the option name, aliases, type, and other attributes; the value sets the default. The library parses command-line arguments, sets variables, and leaves non-option arguments in $@.

Two usage modes are available: one-liner for simple scripts (source with array name and arguments), and multi-step for advanced control (separate init, parse, and set calls).

Supports short (-v) and long (--verbose) options with bundling (-vvv). Option types: flag, required argument, optional argument, array, hash, callback. Validation: integer, float, regex. Help message generation. Pass-through for wrapper scripts. Multiple invocations for subcommand support.

For a gentle introduction, see Getopt::Long::Bash::Tutorial.

INSTALLATION

cpanm -n Getopt::Long::Bash

USAGE

One-liner

Source with array name and arguments to parse in one step:

. getoptlong.sh OPTS "$@"

Configuration parameters must be included in the options array (e.g., [&PREFIX]=OPT_). Callback registration is not available in this mode; use ! modifier for automatic callback instead.

Multi-step

Source the library first, then call init, parse, and set separately:

. getoptlong.sh -
getoptlong init OPTS
getoptlong parse "$@" && eval "$(getoptlong set)"

This mode allows callback registration between init and parse.

Note: When sourcing without arguments (. getoptlong.sh), the current shell's positional parameters are passed to the library. If the first argument happens to match an existing associative array name, it may cause unexpected behavior. Use . getoptlong.sh - to safely source without side effects.

OPTION DEFINITION

Options are defined as elements of an associative array. Each key specifies the option's name, type, and modifiers, while the value provides the default. Whitespace is allowed anywhere in the definition for readability. Configuration parameters can also be included with & prefix (e.g., [&PREFIX]=OPT_); see "CONFIGURATION". The key format is:

[NAME[|ALIAS...][TYPE[MOD]][DEST][=VALIDATE] # DESC]=DEFAULT

COMPONENTS

NAME

Long option name (--name). Hyphens become underscores in variables (--dry-run → $dry_run).

ALIAS

Additional names separated by | (e.g., verbose|v|V).

TYPE

Argument type specifier:

(none) or +  Flag (counter)
:            Required argument
?            Optional argument
@            Array (multiple values)
%            Hash (key=value pairs)
MOD (MODIFIER)

Special behavior flags (can be combined):

!   Callback - calls function when option is parsed
>   Pass-through - collects option and value into array
DEST

Custom variable name (e.g., [opt|o:MYVAR] stores in $MYVAR).

VALIDATE

Value validation: =i (integer), =f (float), =<regex>. See "VALIDATION".

DESC (DESCRIPTION)

Help message text (everything after #).

OPTION TYPES

Each option type determines how arguments are handled and stored.

FLAG (+ or none)

A flag takes no argument. First use sets to 1, subsequent uses increment (useful for verbosity levels). Use --no-X to reset to empty string. Bundling supported: -vvv equals -v -v -v.

[verbose|v]=        # $verbose: 1 when specified
[debug|d+]=0        # $debug: increments (-d -d -d or -ddd)

Numeric initial value (like 0) enables counter display in help.

REQUIRED ARGUMENT (:)

The option requires an argument; error if missing. Use --no-X to reset to empty string (useful for disabling defaults).

[output|o:]=        # --output=file, --output file, -ofile, -o file

Short form -o=value is not supported (use -ovalue or -o value).

OPTIONAL ARGUMENT (?)

The argument is optional. The variable has three possible states: a value (--config=file), empty string (--config without value), or unset (option not specified). Use [[ -v config ]] to check if the option was specified.

[config|c?]=        # --config=file or --config (sets to "")

Syntax:

  • --config=value: variable set to value

  • --config: variable set to empty string ""

  • -c: sets to empty string; -cvalue form is not supported

ARRAY (@)

Collects multiple values into an array. Multiple specifications accumulate. A single option can contain delimited values (default: space, tab, comma; see DELIM). Access with "${include[@]}". To clear the array before adding values, use getoptlong callback --before.

[include|I@]=       # --include a --include b or --include a,b

HASH (%)

Collects key=value pairs into an associative array. Key without value is treated as key=1. Multiple pairs can be specified: --define A=1,B=2 (see DELIM). Access with ${define[KEY]}, keys with ${!define[@]}. To clear the hash before adding values, use getoptlong callback --before.

[define|D%]=        # --define KEY=VAL or --define KEY (KEY=1)

CALLBACK (!)

Calls a function when the option is parsed. Default function name is the option name with hyphens converted to underscores; use getoptlong callback to specify a custom function. Can combine with any type (+!, :!, ?!, @!, %!). See "CALLBACKS" for registration and timing details.

[action|a!]=        # Calls action() when specified
[file|f:!]=         # Calls file() with argument

VALIDATION

Option values can be validated using type specifiers or regex patterns: =i for integers, =f for floats, =( ... ) for regex.

[count:=i]=1            # Integer (positive/negative)
[ratio:=f]=0.5          # Float (e.g., 123.45)
[mode:=(^(a|b|c)$)]=a   # Regex: exactly a, b, or c

Note: For regex, the pattern extends to the last ) in the definition, including any ) in the description. Avoid using ) in comments when using regex validation.

Validation occurs before the value is stored or callbacks are invoked. For array options, each element is validated; for hash options, each key=value pair is matched as a whole. Error on validation failure (see EXIT_ON_ERROR).

DESTINATION VARIABLE

By default, values are stored in variables named after the option. A custom destination can be specified by adding the variable name after TYPE/MODIFIER and before VALIDATE: [NAME|ALIAS:!DEST=(REGEX)]. PREFIX setting applies to custom names too (see "getoptlong init").

[count|c:COUNT]=1       # Store in $COUNT instead of $count
[debug|d+DBG]=0         # Store in $DBG

HELP MESSAGE

By default, --help and -h options are automatically available. They display a help message generated from option definitions and exit. No configuration is required.

To customize or disable, use one of these methods (in order of precedence):

[&HELP]="usage|u#Show usage"            # 1. &HELP key in OPTS
getoptlong init OPTS HELP="manual|m"    # 2. HELP parameter in init
[help|h # Custom help text]=            # 3. Explicit option definition
getoptlong init OPTS HELP=""            # Disable help option

SYNOPSIS (USAGE)

Set the usage line displayed at the top of help output:

[&USAGE]="Usage: cmd [options] <file>"  # In OPTS array
getoptlong init OPTS USAGE="..."        # Or via init parameter

OPTION DESCRIPTIONS

Text after # in the option definition becomes the help description. If omitted, a description is auto-generated. Default values are shown as (default: value).

[output|o: # Output file path]=/dev/stdout

CALLBACKS

Callback functions are called when an option is parsed. The value is stored in the variable as usual, and the callback is invoked for additional processing such as validation or side effects. Callbacks work the same way with pass-through options.

REGISTRATION

Register callbacks with getoptlong callback. If function name is omitted or -, uses option name (hyphens to underscores).

getoptlong callback <option> [function] [args...]
getoptlong callback --before <option> [function] [args...]

CALLBACK TIMING

Normal callbacks are called after value is set, receiving the option name and value. Pre-processing callbacks (--before/-b) are called before value is set, without the value argument.

callback_func "option_name" "value" [args...]   # normal
callback_func "option_name" [args...]           # --before

ERROR HANDLING

Callbacks must handle their own errors. EXIT_ON_ERROR only applies to parsing errors, not callback failures. Use explicit exit if needed.

validate_file() {
    [[ -r "$2" ]] || { echo "Cannot read: $2" >&2; exit 1; }
}
getoptlong callback input-file validate_file

PASS-THROUGH (> Modifier)

Collects options and values into an array instead of storing in a variable. Useful for passing options to other commands. The actual option form used (--pass, -p, --no-pass) is collected, and for options with values, both option and value are added. Multiple options can collect to the same array. If no array name is specified after >, uses the option name. Can combine with callback: [opt|o:!>array].

[pass|p:>collected]=    # Option and value added to collected array

After --pass foo: collected=("--pass" "foo")

COMMANDS

The getoptlong function provides the following subcommands.

getoptlong init

Initialize with option definitions. Must be called before parse. See "CONFIGURATION" for available parameters.

getoptlong init <array_name> [CONFIG...]

getoptlong parse

Parse arguments. Returns 0 on success, non-zero on error. Always quote "$@". By default, script exits on error.

getoptlong parse "$@"

To handle errors manually, disable EXIT_ON_ERROR (see "CONFIGURATION") and check return value:

getoptlong configure EXIT_ON_ERROR=
if ! getoptlong parse "$@"; then
    echo "Parse error" >&2
    exit 1
fi

getoptlong set

eval "$(getoptlong set)"

Outputs shell commands to set variables and update positional parameters. Variables are actually set during parse; this updates $@.

getoptlong callback

Register callback function for option. Use -b/--before to call before value is set. If func is omitted, uses option name (hyphens to underscores). Additional args are passed to the callback.

getoptlong callback [-b|--before] <opt> [func] [args...]

getoptlong configure

Change configuration at runtime. Safe to change: EXIT_ON_ERROR, SILENT, DEBUG, DELIM. Changing PREFIX after init may cause issues.

getoptlong configure KEY=VALUE ...

getoptlong dump

Debug output to stderr showing option names, variables, and values. Use -a/--all to show all internal state.

getoptlong dump [-a|--all]

getoptlong help

Display help message. Optional SYNOPSIS overrides &USAGE/USAGE.

getoptlong help [SYNOPSIS]

CONFIGURATION

Configuration parameters can be specified either as arguments to getoptlong init or as keys in the options array with & prefix (e.g., [&PREFIX]=OPT_). Keys in the options array take precedence.

PERMUTE=array

Array name to store non-option arguments. Default: GOL_ARGV. After parsing, non-option arguments are collected here instead of remaining in $@. Set to empty string to disable permutation; non-option arguments must then come after all options.

PREFIX=string

Prefix added to all variable names. Default: none. For example, with PREFIX=OPT_, option --verbose sets $OPT_verbose.

HELP=spec

Help option specification. Default: help|h#show help. Set to empty string to disable automatic help option.

USAGE=string

Synopsis line shown in help message. Default: scriptname [ options ] args.

[&USAGE]="command [options] file..."
EXIT_ON_ERROR

Exit immediately on parse error. Default: enabled. Set to empty string to disable and handle errors manually by checking return value.

SILENT

Suppress error messages. Default: disabled. Set to non-empty value to enable.

DEBUG

Enable debug output. Default: disabled. Set to non-empty value to enable.

DELIM=string

Delimiter characters for array/hash values. Default: space, tab, comma. For example, DELIM=,: would split on comma and colon.

REQUIRE=version

Minimum required version. Script exits with error if current version is older than specified.

[&REQUIRE]="0.2"

MULTIPLE INVOCATIONS

getoptlong init and parse can be called multiple times for subcommand support:

# Parse global options
getoptlong init GlobalOPTS PERMUTE=REST
getoptlong parse "$@" && eval "$(getoptlong set)"

# Parse subcommand options
case "${REST[0]}" in
    commit)
        getoptlong init CommitOPTS
        getoptlong parse "${REST[@]:1}" && eval "$(getoptlong set)"
        ;;
esac

EXAMPLES

See ex/ directory for sample scripts:

  • repeat.sh - basic option types

  • prefix.sh - PREFIX setting

  • dest.sh - custom destination variables

  • subcmd.sh - subcommand handling

  • cmap - complex real-world example

SEE ALSO

AUTHOR

Kazumasa Utashiro

COPYRIGHT

Copyright 2025 Kazumasa Utashiro

LICENSE

MIT License