References.md

References

• Global functions
  • getoptions - Generate a function for option parsing
  • getoptions_abbr - Handle abbreviated long options
  • getoptions_help - Generate a function to display help
  • getoptions_parse - Default option parser name
• Option parser
  • Option parser definition function
  • Custom error handler
  • Prehook
• Helper functions
  • Data types & Initial values
  • setup - Setup global settings (mandatory)
    • Scanning modes
  • flag - Define an option that take no argument
  • param - Define an option that take an argument
  • option - Define an option that take an optional argument
  • disp - Define an option that display only
  • msg - Display message in help
  • cmd - Define a subcommand
  • 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

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.

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

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

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.

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-*, --{no-}* (expand to --flag and --no-flag), --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

$ 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)]