Shell Argparser

The Argparser is designed to be an easy-to-use, yet powerful command-line argument parser for your shell scripts. It is mainly targeting Bash, but other shells are supported, as well.

Applying the Argparser should lead to shorter and more concise code than the traditional getopt and getopts allow. More importantly, the user-friendliness of Argparser-powered command-line parsing is far superior thanks to a wide range of checked conditions with meaningful error messages. The Argparser is inspired by the Python argparse module.

Table of contents

1. Features
2. Quick start
3. Documentation
4. Dependencies
5. License
6. Contributions

1. Features

• Parsing of positional and keyword (option) arguments
• Any number of short and long option names for the same option (as aliases)
• Default and choice values, type checking, deprecation note
• Error and warning messages for wrongly or not set arguments
• Assignment of arguments' values to corresponding script variables
• Automatic creation of help, usage, and version message
• Full internationalization / localization support
• Inheritable arguments definition across multiple scripts
• Large configurability by environment variables and companion files to your script

2. Quick start

No installation of the Argparser is necessary, just clone the repository and add its location to the PATH variable. Alternatively, you may move the Argparser executable into a directory which is already covered by your PATH. All other files within the repository serve documentation and testing purposes, and you don't need to keep them.

# Switch to the installation directory of your choice, e.g., /usr/local/bin.
cd /path/to/directory

# Clone the repository.
git clone https://github.com/Simon-Brandt/ShellArgparser.git

# Adjust the PATH.
PATH="/path/to/ShellArgparser:${PATH}"

A very simple quick-start script may look like this:

Contents of try_argparser.sh

#!/usr/bin/env bash

# Define the arguments.
args=(
    "id    | short_opts | long_opts   | val_names | defaults | choices | type | arg_no | arg_group            | notes      | help                                              "
    "pos_1 |            |             | pos_1     | 2        | 1,2     | int  | 1      | Positional arguments |            | one positional argument with default and choice   "
    "pos_2 |            |             | pos_2     |          |         | int  | 2      | Positional arguments |            | two positional arguments without default or choice"
    "var_1 | a,A        | var-1,var-a | VAL_1     |          |         | uint | 1      | Mandatory options    |            | one value without default or choice               "
    "var_2 | b,B        | var-2,var-b | VAL_2     |          |         | int  | +      | Mandatory options    |            | at least one value without default or choice      "
    "var_3 | c,C        | var-3,var-c | VAL_3     |          | A,B     | char | +      | Mandatory options    |            | at least one value with choice                    "
    "var_4 | d,D        | var-4,var-d | VAL_4     | A        | A-C     | char | 1      | Optional options     |            | one value with default and choice                 "
    "var_5 | e,E        | var-5,var-e | VAL_5     | E        |         | str  | 1      | Optional options     |            | one value with default                            "
    "var_6 | f,F        | var-6,var-f | VAL_6     | false    |         | bool | 0      | Optional options     |            | no value (flag) with default                      "
    "var_7 | g,G        | var-7,var-g | VAL_7     | true     |         | bool | 0      | Optional options     | deprecated | no value (flag) with default                      "
)
source argparser -- "$@"

# The arguments can now be accessed as keys and values of the
# associative array "args".  Further, they are set as variables to the
# environment, from which they are expanded by globbing.
for arg in "${!var@}"; do
    printf 'The keyword argument "%s" is set to "%s".\n' \
        "${arg}" "${args[${arg}]}"
done | sort

index=1
for arg in "${!pos@}"; do
    printf 'The positional argument "%s" on index %s is set to "%s".\n' \
        "${arg}" "${index}" "${args[${arg}]}"
    (( index++ ))
done

First, you need to define the arguments your script shall accept, in a tabular manner. Then, you source the Argparser with the current command line (sourcing means in-place execution without forking). Upon this, the Argparser will parse your script's command line, check the arguments for validity, set default values, and assign the values to variables in your script's environment. Many of these steps can be customized by environment variables. The script's remainder just prints the optional and required keyword and positional arguments, and is not a part of the Argparser invokation.

3. Documentation

The Argparser's extensive documentation is stored in the docs directory, which you should consult to learn all the functionality the Argparser provides. Each file provides a chapter (section) of the documentation, and arrows on the bottom allow you to navigate through the sections, without needing to care about which file stores the requested chapter.

If you want to read the documentation end-to-end, start with the introduction. For searching through the entire documentation, you can open the source file that is used to generate the chapters, or use the main table of contents.

4. Dependencies

The Argparser is a plain Bash script that does not invoke external commands (only Bash builtins) by design decision. This allows running your script on multiple platforms, as long as Bash is installed, without adding further dependencies to your script. When contributing, you may need several other software tools listed and explained in the documentation.

For simply running the Argparser, only Bash is required. Bash ≥ 4.4 is known to be mandatory, but testing occurred mainly on Bash 5.2. Thus, please file an issue if you encounter errors for versions earlier than 5.2, such that the minimum version can be updated, here (or the bug can be fixed).

5. License

The Argparser is licensed under the terms and conditions of the Apache License, Version 2.0. This applies to all source code files (all shell scripts and Julia files) and the documentation (all Markdown files), but not to the HTML, SVG, TeX, PDF, and CSV files in the comparison directory, any file in the resources directory, as well as the Argparser's Dockerfile, the .shellcheckrc, and the .gitignore, which are all placed in the Public Domain.

The Apache License v2.0 allows running, modifying, and distributing the Argparser, even in commercial settings, provided that the license is distributed along the source code or compiled objects. (This is not legal advice. Read the license for the exact terms.)

6. Contributions

Please open an issue if you:

• found a bug in the Argparser
• discovered an error in the documentation (even a spelling or grammar mistake!)
• want to propose a new feature
• want to contribute code (please don't start a pull request prior opening an issue)
• need help with running the Argparser, after having consulted the docs to no avail
• want to enhance the documentation
• want to provide translations for the error and warning messages (very appreciated!)

You're invited to fix issues yourself, especially trivial mistakes in the docs. To this end, fork the repository, make the necessary changes, and open a pull request (PR) to merge your changes.

Prior committing non-trivial edits, especially for code, please make sure to have read and followed the contribution guidelines. This makes it easier to merge the modifications.