# References

- [Global functions](#global-functions)
  - [`getoptions` - Generate a function for option parsing](#getoptions---generate-a-function-for-option-parsing)
  - [`getoptions_abbr` - Handle abbreviated long options](#getoptions_abbr---handle-abbreviated-long-options)
  - [`getoptions_help` - Generate a function to display help](#getoptions_help---generate-a-function-to-display-help)
  - [`getoptions_parse` - Default option parser name](#getoptions_parse---default-option-parser-name)
- [Option parser](#option-parser)
  - [Option parser definition function](#option-parser-definition-function)
  - [Custom error handler](#custom-error-handler)
  - [Prehook](#prehook)
- [Helper functions](#helper-functions)
  - [Data types & Initial values](#data-types--initial-values)
  - [`setup` - Setup global settings (mandatory)](#setup---setup-global-settings-mandatory)
    - [Scanning modes](#scanning-modes)
  - [`flag` - Define an option that take no argument](#flag---define-an-option-that-take-no-argument)
  - [`param` - Define an option that take an argument](#param---define-an-option-that-take-an-argument)
  - [`option` - Define an option that take an optional argument](#option---define-an-option-that-take-an-optional-argument)
  - [`disp` - Define an option that display only](#disp---define-an-option-that-display-only)
  - [`msg` - Display message in help](#msg---display-message-in-help)
  - [`cmd` - Define a subcommand](#cmd---define-a-subcommand)
  - [Attributes related to the help display](#attributes-related-to-the-help-display)

## Global functions

### `getoptions` - Generate a function for option parsing

This function is, to be exact, an option parser generator.
An option parser is defined by `eval` the generated code.

`getoptions <definition> [<parser|-> [arguments]...]`


- parser_definition - Option parser definition
- parser_name - Function name for option parser
- arguments - Passed to the parser definition function

```sh
parser_definition() {
  setup REST ...
  ...
}

# Define the parse function for option parsing
eval "$(getoptions parser_definition parse "$0")"
parse "$@"          # Option parsing
eval "set -- $REST" # Exclude options from arguments
```

If you omit the option parser name or use `-`, it will define the default option
parser and parse arguments immediately.

```sh
parser_definition() {
  setup REST ...
  ...
}

eval "$(getoptions parser_definition - "$0") exit 1"

# The above means the same as the following code.
# eval "$(getoptions parser_definition getoptions_parse "$0") exit 1"
# getoptions_parse "$@"
# eval "set -- $REST"
```

### `getoptions_abbr` - Handle abbreviated long options

This function is called automatically by `getoptions` with the `abbr` attribute,
Do not call it manually.

### `getoptions_help` - Generate a function to display help

This function generates a function for displaying help. Normally, this function is called
automatically by the `help` attribute of `getoptions`, but you can also call it manually.

The function to display help does not necessarily need to be generated by `getoptions_help`.
Since it is just a function, you may define your own shell function.

`getoptions_help <definition> <help> [arguments...]`

- parser_definition - Option parser definition
- help_name - Function name for help display
- arguments - Passed to the parser definition function

```sh
parser_definition() {
  ...
}

eval "$(getoptions_help parser_definition usage)"
usage
```

### `getoptions_parse` - Default option parser name

This is the default option parser name defined when `-` is specified as the option parser name.

## Option parser

This is a function for parsing options, which is generated by `getoptions`
based on the parser definition function.

The option parser reuses the shell special variables `OPTIND` and `OPTARG`
for a different purpose than `getopts`. When the option parsing is successfully
completed, the `OPTIND` is reset to 1 and the `OPTARG` is unset.
When option parsing fails, the `OPTARG` is set to the value of the failed option.

### Option parser definition function

This is the function for defining the option parser.

The option parser definition functions are called by `getoptions` 2 times
(or 3 times when using automatic help generation).

Since this function is called within a subshell, defining variables and
functions within this function does not pollute the global. Of course,
helper functions are also defined in the subshell.

### Custom error handler

You can modify the standard error messages and define additional error messages
by defining a custom error handler. It is also possible to change the exit status.

Example

```sh
parser_definition() {
  setup   REST error:error
  param   NUMBER --number validate:number
  param   RANGE  --range validate:'range 10 100' -- '10 - 100'
}

number() {
  case $OPTARG in (*[!0-9]*)
    return 1
  esac
}

range() {
  number || return 1
  [ "$1" -le "$OPTARG" ] && [ "$OPTARG" -le "$2" ] && return 0
  return 2
}

# Custom error handler
#   $1: Default error message
#   $2: Error name
#     - `unknown` (Unrecognized option)
#     - `noarg` (Does not allow an argument)
#     - `required` (Requires an argument)
#     - `pattern:<PATTERN>` (Does not match the pattern)
#     - `validator_name:<STATUS>` (Validation error)
#     - `ambiguous` (Ambiguous option)
#   $3: Option
#   $4-: Validator name and arguments (if $2 is validator_name)
#   $4-: Candidate options (if $2 is ambiguous)
#   return: exit status
error() {
  case $2 in
    unknown) echo "Unrecognized option: $3" ;;
    number:*) echo "Not a number: $3" ;;
    range:1) echo "Not a number: $3" ;;
    range:2) echo "Out of range ($5 - $6): $3"; return 2 ;;
    *) return 0 ;; # Display default error
  esac
  return 1
}
```

The value of the option that caused the error is stored in the `OPTARG` variable.
If the cause of the error is `ambiguous`, the `OPTARG` is stored candidate
options splited by `, `.

### Prehook

If you define a `prehook` function in the parser definition,
the `prehook` function will be called before helper functions is called.
Use `invoke` to call the original function from within a `prehook` function.

NOTE: The `prehook` function is not called in the help.

```sh
extension() {
  # The prehook is called before helper functions is called.
  prehook() {
    helper=$1 varname_or_action=$2
    shift 2

    # Do something

    invoke "$helper" "$varname_or_action" "$@"
  }
}

parser_definition() {
  extension
  setup   REST
  flag    FLAG -f  --flag
}
```

## Helper functions

Helper functions are not defined globally.
They are available only in the `getoptions` and `getoptions_help` functions.

### Data types & Initial values

| name       | description                                                                                                                                                                   |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SWITCH     | `-?`, `+?`, `--*`, `--no-*`, `--with-*`, `--without-*`,<br>`--{no-}*` (expand to `--flag` and `--no-flag`),<br>`--with{out}-*` (expand to `--with-flag` and `--without-flag`) |
| BOOLEAN    | Boolean (true: not zero-length string, false: **zero-length string**)                                                                                                         |
| STRING     | String                                                                                                                                                                        |
| NUMBER     | Number                                                                                                                                                                        |
| STATEMENT  | Function name (arguments can be added) - e.g. `foo`, `foo 1 2 3`                                                                                                              |
| CODE       | Statement or multiple statements - e.g `foo; bar`                                                                                                                             |
| KEY-VALUE  | `key:value` style arguments - If `:value` is omitted, it is the same as `key:key`                                                                                             |
| INIT-VALUE | Initial value (`@on`, `@no`, `@unset`, `@none`, `@export`)                                                                                                                    |

| name      | description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| `@on`     | Set the variable to a positive value. [default: `1`]                         |
| `@no`     | Set the variable to a negative value. [default: empty]                       |
| `@unset`  | Unset the variable                                                           |
| `@none`   | Do not initialization (Use the current value as it is)                       |
| `@export` | Add only export flag without initialization (Use the current value as it is) |

### `setup` - Setup global settings (mandatory)

`setup <restargs> [settings...] [default attributes...] [-- [messages...]]`

- resrargs (VARIABLE)
  - The variable name for getting rest arguments
  - Specify `-` if you want to omit the restargs
- settings (KEY-VALUE)
  - `abbr`:BOOLEAN - Handle abbreviated long options (requires `getoptions_abbr`)
  - `alt`:BOOLEAN - allow long options starting with single `-` (alternative)
    - Unlike `getopt`, the syntax `-abc` and `-sVALUE` cannot be used when enabled
  - `error`:STATEMENT - Custom error handler
  - `help`:STATEMENT - Define help function (requires `getoptions_help`)
  - `leading`:STRING - Leading characters in the option part of the help [default: `"  "` (two spaces)]
  - `mode`:STRING - Scanning modes (See below or `man getopt`) [default: empty]
  - `plus`:BOOLEAN - Those start with `+` are treated as options [default: auto]
  - `width`:NUMBER - The width of the option or subcommand part of the help [default: `"30,12"`]
- default attributes (KEY-VALUE)
  - `export`:BOOLEAN - Export variables [default: empty]
  - `hidden`:BOOLEAN - Do not display in help [default: empty]
  - `init`:[@INIT-VALUE | =STRING | CODE] - Initial value
  - `on`:STRING - The positive value [default: `1`]
  - `no`:STRING - The negative value [default: empty]
- message (STRING)
  - Help messages

#### Scanning modes

| mode | `getopt`      | `getoptions`                                                |
| ---- | ------------- | ----------------------------------------------------------- |
| `+`  | Supported     | Stop parsing when an argument (not an option) is found      |
| `-`  | Supported     | Not supported (No point in supporting it)                   |
| `@`  | Not supported | Similar to mode `+` but leaves `--` (AKA, subcommands mode) |

### `flag` - Define an option that take no argument

`flag <varname | :action> [switches...] [attributes...] [-- [messages...]]`

- varname (VARIABLE) or action (STATEMENT)
  - Variable name or Action function
- switches (SWITCH)
  - Options
- attributes (KEY-VALUE)
  - `abbr`:BOOLEAN - Set empty to disable individually [default: `1` if abbreviation option is enabled]
  - `counter`:BOOLEAN - Counts the number of flags
  - `export`:BOOLEAN - Export variables
  - `hidden`:BOOLEAN - Do not display in help
  - `init`:[@INIT-VALUE | =STRING | CODE] - Initial value
  - `label`:STRING - The option part of the help
  - `on`:STRING - The positive value
  - `no`:STRING - The negative value
  - `pattern`:PATTERN - Pattern to accept
  - `validate`:STATEMENT - Code for value validation
- message (STRING)
  - Help messages

### `param` - Define an option that take an argument

`param <varname | :action> [switches...] [attributes...] [-- [messages...]]`

- varname (VARIABLE) or action (STATEMENT)
  - Variable name or Action function
- switches (SWITCH)
  - Options
- attributes (KEY-VALUE)
  - `abbr`:BOOLEAN - Set empty to disable individually [default: `1` if abbreviation option is enabled]
  - `export`:BOOLEAN - Export variables
  - `hidden`:BOOLEAN - Do not display in help
  - `init`:[@INIT-VALUE | =STRING | CODE] - Initial value
  - `label`:STRING - Option part of help message
  - `pattern`:PATTERN - Pattern to accept
  - `validate`:STATEMENT - Code for value validation
  - `var`:STRING - Variable name displayed in help
- message (STRING)
  - Help messages

### `option` - Define an option that take an optional argument

`option <varname | :action> [switches...] [attributes...] [-- [messages...]]`

- varname (VARIABLE) or action (STATEMENT)
  - Variable name or Action function
- switches (SWITCH)
  - Options
- attributes (KEY-VALUE)
  - `abbr`:BOOLEAN - Set empty to disable individually [default: `1` if abbreviation option is enabled]
  - `export`:BOOLEAN - Export variables
  - `hidden`:BOOLEAN - Do not display in help
  - `init`:[@INIT-VALUE | =STRING | CODE] - Initial value
  - `label`:STRING - Option part of help message
  - `on`:STRING - The positive value
  - `no`:STRING - The negative value
  - `pattern`:PATTERN - Pattern to accept
  - `validate`:STATEMENT - Code for value validation
  - `var`:STRING - Variable name displayed in help
- message (STRING)
  - Help messages

### `disp` - Define an option that display only

`disp <varname | :action> [switches...] [attributes...] [-- [messages...]]`

- varname (VARIABLE) or action (STATEMENT)
  - Variable name or Action function
- switches (SWITCH)
  - Options
- attributes (KEY-VALUE)
  - `abbr`:BOOLEAN - Set empty to disable individually [default: `1` if abbreviation option is enabled]
  - `hidden`:BOOLEAN - Do not display in help
  - `label`:STRING - Option part of help message
- message (STRING)
  - Help messages

### `msg` - Display message in help

`msg [attributes...] [-- [messages...]]`

- attributes (KEY-VALUE)
  - `hidden`:BOOLEAN - Do not display in help
  - `label`:STRING - Option part of help message
- message (STRING)
  - Help messages

### `cmd` - Define a subcommand

`cmd [subcommand] [-- [messages...]]`

- attributes (KEY-VALUE)
  - `hidden`:BOOLEAN - Do not display in help
  - `label`:STRING - Command part of help message
- message (STRING)
  - Help messages

NOTE: Defining a subcommand will change the scanning mode to `@` (subcommands mode).

### Attributes related to the help display

```console
$ example.sh ---help

Options:
+----------------------------- message -----------------------------+
:                                                                   :
+----------- label -----------+                                     :
:   width [default: 30]       :                                     :
:                             :                                     :
  -f, +f, --flag              message for --flag
  -l, +l, --long-long-option-name
                              message for --long-long-option-name
  -o, +o, --option VAR        message for --option
|     |            |
|     |            +-- var
|     +-- plus (visible if specified)
+-- leading [default: "  " (two spaces)]

Commands:
+---------------- message ----------------+
:                                         :
+-- label --+                             :
: width [12]:                             :
:           :                             :
  cmd1      subcommand1
  cmd2      subcommand2
  cmd3      subcommand3
|
+-- leading [default: "  " (two spaces)]
```