view release on metacpan or  search on metacpan

GETOPTLONG.md  view on Meta::CPAN

    *   Long option: `--output=value`, `--output value`
    *   Short option: `-ovalue`, `-o value`
    *   Note: The `-o=value` form is not supported for short options.

*   **Variable Storage:** The specified value is stored as a string in the variable (e.g., `$output`).

*   **Initial Value:** Results in an error if not specified, but an initial value can be set during definition (e.g., `]=/dev/stdout`).

*   **Negation with `no-` Prefix:** Specifying with `--no-output` sets the variable to an empty string without requiring an argument. This is useful for options like `--pager` where `--no-pager` can disable the pager.

*   **Use Cases:** Specifying file paths, required parameters.

#### 4.2.3. Optional Argument Options (`?`)

Options that can take a value or be specified without one.

*   **Definition Example:** `[mode|m? # Operation mode]`

*   **How to Specify Value:**
    *   Long option:
        *   `--mode=value`: Variable `$mode` is set to `value`.
        *   `--mode`: Variable `$mode` is set to an empty string `""`.
    *   Short option:
        *   `-m`: Variable `$mode` is set to an empty string `""`.
        *   Note: Directly appending a value like `-mvalue` is not supported for short options. Use the long option if you need to specify a value.

*   **Variable Storage:**
    *   If a value is specified: That value is stored in the variable.
    *   If the option is specified without a value: An empty string `""` is stored in the variable.
    *   If the option is not specified: The variable remains unset (if no initial value was defined). Existence can be checked with `${variable+_}` or `[[ -v variable ]]`.

*   **Initial Value:** Can be set during definition (e.g., `]=default_mode`).

*   **Use Cases:** Optional configuration values, parameters valid only in certain cases.

#### 4.2.4. Array Options (`@`)

Accept multiple values as an array.

*   **Definition Example:** `[include|I@ # Include path]`

*   **How to Specify Values:**
    *   Specify the option multiple times: `--include /path/a --include /path/b`, `-I /path/a -I /path/b`
    *   Specify multiple values with a single option (delimiter controlled by `DELIM` setting; defaults to comma, space, tab):
        *   `--include /path/a,/path/b`
        *   `--include "/path/a /path/b"`
        *   `-I /path/a,/path/b`

*   **Variable Storage:** Specified values are stored in a Bash array (e.g., `"${include[@]}"`).

*   **Initial Value:** Usually an empty array. An initial value can be set during definition (e.g., `]=(/default/path1 /default/path2)`).

*   **Resetting with `no-` Prefix:** Specifying with `--no-include` resets the array to empty. This is useful for overriding default values. For example, `--no-include --include /new/path` clears any initial values and sets only `/new/path`.

*   **Use Cases:** Multiple input files, multiple configuration items.

#### 4.2.5. Hash Options (`%`)

Accept `key=value` pairs as an associative array (hash).

*   **Definition Example:** `[define|D% # Macro definition (e.g., KEY=VALUE)]`

*   **How to Specify Values:**
    *   Specify the option multiple times: `--define OS=Linux --define VER=1.0`, `-D OS=Linux -D VER=1.0`
    *   Specify multiple pairs with a single option (delimiter controlled by `DELIM` setting; defaults to comma):
        *   `--define OS=Linux,VER=1.0`
        *   `-D OS=Linux,VER=1.0`
    *   If the value (`=VALUE`) is omitted, it's treated as if `=1` was specified (e.g., `--define DEBUG` is interpreted as `DEBUG=1`).

*   **Variable Storage:** Specified keys and values are stored in a Bash associative array (e.g., `declare -A define_map="${define[@]}"; echo "${define_map[OS]}"`).

*   **Initial Value:** Usually an empty associative array. An initial value can be set during definition (e.g., `]=([USER]=$(whoami))`).

*   **Resetting with `no-` Prefix:** Specifying with `--no-define` resets the associative array to empty. This is useful for overriding default values. For example, `--no-define --define KEY=val` clears any initial values and sets only `KEY=val`.

*   **Use Cases:** Environment variable-like settings, information managed as key-value pairs.

#### 4.2.6. Callback Options (`!`)

When the option is parsed, the specified callback function is called. This `!` specifier can be appended to any of the above option types (`+`, `:`, `?`, `@`, `%`).

*   **Definition Examples:**
    *   `[execute|x! # Execute a command]` (flag type callback)
    *   `[config|c:! # Load a configuration file]` (required argument type callback)

*   **Behavior:**
    *   When the option is specified on the command line, the associated callback function is executed.
    *   By default, the callback function name is the same as the option's long name (hyphens converted to underscores). An arbitrary function name can be specified using the `getoptlong callback` command.
    *   For callback function invocation timing and arguments, see Section "7.4. `getoptlong callback ...`" and "5.1. Callback Function Details".

*   **Use Cases:** Executing custom actions during option parsing, complex value processing, immediate configuration changes.

### 4.3. Specifying Destination Variable Name

By default, `getoptlong.sh` stores the value of a parsed option (e.g., `--my-option value`) into a shell variable derived from the option's long name (e.g., `$my_option`, with hyphens replaced by underscores).  However, you can specify a custom varia...

This is achieved by writing the desired variable name directly after the option type specifier (e.g., `+`, `:`, `?`, `@`, `%`) and any modifiers (e.g., `!`, `-`).

*   **Syntax in Option Definition:** Refer back to Section "4.1. Basic Syntax" for the full structure: `long_name[|short_name...][<type_char>[<modifiers>]][DEST_VAR_NAME][=<validation_type>] # Description` The `DEST_VAR_NAME` is the custom variable n...

*   **Example from `ex/dest.sh`:**
    The script `ex/dest.sh` demonstrates this feature:
    ```bash
    declare -A OPTS=(
        [ count     | c :COUNT=i # repeat count              ]=1
        [ sleep     | i @SLEEP=f # interval time             ]=
        [ paragraph | p ?PARA    # print newline after cycle ]=
        [ trace     | x !TRACE   # trace execution           ]= # TRACE becomes var name for callback context
        [ debug     | d +DEBUG   # debug level               ]=0
        [ message   | m %MSG=(^(BEGIN|END|EACH)=) # print message at BEGIN|END|EACH ]=
    )
    ```
    In this example:
    *   `[count|c:COUNT=i]`: Stores the value of `--count` into `COUNT` (validated as integer).
    *   `[sleep|i@SLEEP=f]`: Stores values for `--sleep` into array `SLEEP` (validated as floats).
    *   `[paragraph|p?PARA]`: Stores optional arg of `--paragraph` into `PARA`.
    *   `[debug|d+DEBUG]`: Stores incrementing value of `--debug` into `DEBUG`.
    *   `[message|m%MSG=(...)]`: Stores key-value pairs from `--message` into associative array `MSG`.

*   **Behavior:**
    *   After `getoptlong parse "$@"` and `eval "$(getoptlong set)"`, the specified variables (`COUNT`, `SLEEP`, `PARA`, `DEBUG`, `MSG` in the example) will contain the parsed values.