getoptions <!-- omit in toc -->

<br>

An elegant option parser for shell scripts (full support for all POSIX shells)

getoptions is a new option parser and generator written in POSIX-compliant shell script and released in august 2020. It is for those who want to support the POSIX / GNU style option syntax in your shell scripts. Most easy, simple, fast, small, extensible and portable. No more any loops and templates needed!

TL; DR <!-- omit in toc -->

#!/bin/sh

VERSION="0.1"

parser_definition() {
  setup   REST help:usage -- "Usage: example.sh [options]... [arguments]..." ''
  msg -- 'Options:'
  flag    FLAG    -f --flag                 -- "takes no arguments"
  param   PARAM   -p --param                -- "takes one argument"
  option  OPTION  -o --option on:"default"  -- "takes one optional argument"
  disp    :usage     --help
  disp    VERSION    --version
}

eval "$(getoptions parser_definition) exit 1"

echo "FLAG: $FLAG, PARAM: $PARAM, OPTION: $OPTION"
printf '%s\n' "$@" # rest arguments

It generates a simple option parser code internally and parses the following arguments.

$ example.sh -f --flag -p value --param value -o --option -ovalue --option=value 1 2 3
FLAG: 1, PARAM: value, OPTION: value
1
2
3

Automatic help generation is also provided.

$ example.sh --help

Usage: example.sh [options]... [arguments]...

Options:
  -f, --flag                  takes no arguments
  -p, --param PARAM           takes one argument
  -o, --option[=OPTION]       takes one optional argument
      --help
      --version

Table of Contents <!-- omit in toc -->

• Features
• getopt vs getopts vs getoptions
• Requirements
• Installation
  • Homebrew / Linuxbrew
• Usage
  • Use as a command
  • Use as a library
  • Use as a generator
  • Embedding into a file
• Benchmarks
• How to see the option parser code
  • Arguments containing spaces and quotes
  • Why reuse OPTARG and OPTIND for different purposes?
  • About workarounds
• References
  • Global functions
  • Helper functions
• Examples
  • Basic
  • Advanced
    • Custom error handler
    • Custom helper functions
  • Subcommand
  • Prehook
  • Extension
  • Practical example
• NOTE: 2.x breaking changes
• NOTE: 3.x breaking changes
• For developers
  • How to test getoptions
• Changelog
• License

Features

• Full support for all POSIX shells, no limitations, no bashisms
• High portability, supports all platforms (Linux, macOS, Windows, etc) where works POSIX shells
• Neither getopt nor getopts is used, and implemented with shell scripts only
• Provides DSL-like shell script way to define parsers for flexibility and extensibility
• No need for code generation from embedded special comments
• Can be used as an option parser generator to run without getoptions
• Support for POSIX [1] and GNU [2] [3] compliant option syntax
• Support for long options
• Support for subcommands
• Support for abbreviation option
• Support for automatic help generation
• Support for options to call action function
• Support for validation and custom error handler
• Works fast with small overhead and small file size (5KB - 8KB) library
• No global variables are used (except the special variables OPTARG and OPTIND)
• Only a minimum of one (and a maximum of three) global functions are defined as a library
• No worry about license, it's public domain (Creative Commons Zero v1.0 Universal)

getopt vs getopts vs getoptions

| | getopt | getopts | getoptions | | ------------------------------- | ---------------- | --------------------- | --------------------- | | Implementation | external command | shell builtin command | shell script | | Portability | No | Yes | Yes | | Short option beginning with - | ✔️ | ✔️ | ✔️ | | Short option beginning with + | ❌ | ⚠ zsh, ksh, mksh only | ✔️ | | Combining short options | ✔️ | ✔️ | ✔️ | | Long option beginning with -- | ⚠ GNU only | ❌ | ✔️ | | Long option beginning with - | ⚠ GNU only | ❌ | ✔️ limited | | Abbreviating long options | ⚠ GNU only | ❌ | ✔️ | | Optional argument | ⚠ GNU only | ❌ | ✔️ | | Option after arguments | ⚠ GNU only | ❌ | ✔️ | | Stop option parsing with -- | ✔️ | ✔️ | ✔️ | | Scanning modes | ⚠ GNU only | ❌ | ✔️ + and enhancement | | Subcommand | ❌ | ❌ | ✔️ | | Validation by pattern matching | ❌ | ❌ | ✔️ | | Custom validation | ❌ | ❌ | ✔️ | | Custom error handler | ❌ | ✔️ | ✔️ more flexible | | Automatic help generation | ❌ | ❌ | ✔️ |

Requirements

Almost no requirements.

• Any POSIX shells
  • dash 0.5.4+, bash 2.03+, ksh 88+, mksh R28+, zsh 3.1.9+, yash 2.29+, busybox ash 1.1.3+, etc
• Only cat is used for help display, but it can be removed

Installation

Download prebuild shell scripts from releases.

• getoptions: Option parser
• gengetoptions: Option parser generator

wget https://github.com/ko1nksm/getoptions/releases/latest/download/getoptions -O $HOME/bin/getoptions
chmod +x $HOME/bin/getoptions

# optional
wget https://github.com/ko1nksm/getoptions/releases/latest/download/gengetoptions -O $HOME/bin/gengetoptions
chmod +x $HOME/bin/gengetoptions

Or build and install it yourself.

git clone https://github.com/ko1nksm/getoptions.git
cd getoptions
make
make install PREFIX=$HOME

Homebrew

brew tap ko1nksm/getoptions
brew install getoptions

Usage

Support three ways of use. It is better to use it as a command at first, and then use it as a library or generator as needed.

| | command | library | generator | | ---- | ------- | ------- | --------- | | easy | ★★★ | ★★☆ | ★☆☆ | | fast | ★☆☆ | ★★☆ | ★★★ |

Use as a command

Use the getoptions command that you installed on your system. This assumes that you have the getoptions command installed, but it is the easiest to use and is suitable for personal scripts.

The execution speed is slightly slower than using it as a library. (Approx. 15ms overhead)

parser_definition() {
  setup REST help:usage -- "Usage: example.sh [options]... [arguments]..."
  ...
}

eval "$(getopti