help_and_usage_messages.md

5.5. Help and usage messages

No matter how many keyword arguments are defined, as long as ARGPARSER_ADD_HELP and ARGPARSER_ADD_USAGE are set to true (the default), the Argparser interprets the flags from the ARGPARSER_HELP_OPTIONS (default: -h and -?) and --help as call for a verbose help message and the flags from the ARGPARSER_USAGE_OPTIONS (default: -u) and --usage as call for a brief usage message. Then, these options are automatically added to the script's arguments definition and override any same-named argument name (yielding an error message if ARGPARSER_CHECK_ARG_DEF is set to true). This is to ensure that the novice user of your script can do exactly what we did, above: trying the most common variants to get some help over how to use a program or script by typing

try_argparser.sh --help

or

try_argparser.sh -h

or

try_argparser.sh -?

Of course,

help try_argparser.sh

won't work as the help command only recognizes Bash builtins.

As a huge convenience, the Argparser will build the help and usage messages from the defined arguments for your script, if either of the ARGPARSER_HELP_OPTIONS, --help, ARGPARSER_USAGE_OPTIONS, or --usage options is given on the command line (even along with others, with the help message taking precedence over the usage message). These messages indicate the short and/or long names, as well as the default and choice values. In the case of the help message, the argument group, the notes, and the help text from the arguments' definitions are printed, too.

5.5.1. Help messages

Now, we can investigate the help message, just as we did above, with the very same result:

$ bash ../tutorial/try_argparser.sh --help
Usage: try_argparser.sh [OPTIONS] ARGUMENTS -- [pos_1] pos_2

Mandatory arguments to long options are mandatory for short options too.

Positional arguments:
[pos_1=                                     one positional argument with
    {1,2}]                                  default and choice (default: 2)
pos_2                                       two positional arguments without
                                            default or choice

Mandatory options:
-a, -A,    --var-1=VAL_1, --var-a=VAR_A     one value without default or choice
-b, -B,    --var-2=VAL_2...,                at least one value without default
           --var-b=VAR_B...                 or choice
-c, -C,    --var-3={A,B}...,                at least one value with choice
           --var-c={A,B}...

Optional options:
[-d, -D],  [--var-4={A-C}], [--var-d={A-C}] one value with default and choice
                                            (default: "A")
[-e, -E],  [--var-5=VAL_5], [--var-e=VAR_E] one value with default (default:
                                            "E")
[-f, -F],  [--var-6, --var-f]               no value (flag) with default
                                            (default: false)
[-g, -G],  [--var-7, --var-g]               (DEPRECATED) no value (flag) with
                                            default (default: true)

[-h, -?],  [--help]                         display this help and exit
                                            (default: false)
[-u],      [--usage]                        display the usage and exit
                                            (default: false)
[-V],      [--version]                      display the version and exit
                                            (default: false)

The help message details all short and long option names, their optionality (i.e., whether there are default values), and their choice values, using the same syntax as in the usage message (square brackets for optional arguments, curly braces for choice values). Additionally, the help text and notes from the arguments definition are given. The arguments are separated by their groups, thus structuring the help message. First, the group for the positional arguments is given (indicated by ARGPARSER_POSITIONAL_ARG_GROUP), then follow the keyword argument groups in alphabetical order. Finally, the default --help, --usage, and --version arguments (the latter for the version message) are given as separate, yet unnamed group.

The help message's structure aims at reproducing the commonly found structure in command-line programs. By setting ARGPARSER_MAX_COL_WIDTH_1, ARGPARSER_MAX_COL_WIDTH_2, or ARGPARSER_MAX_COL_WIDTH_3, the column widths may be adapted to your needs, recommendably totalling 77 characters (thus 79 characters including the separating spaces). Note that columns are automatically shrunk, when their content is narrower, but they're not expanded, when their content is wider. This is to guarantee that the help message, when e.g. sent as logging output, nicely fits in the space you have.

Alternatively, you may want to set ARGPARSER_MAX_WIDTH. By this, the help message will have a defined width, independent of shrunk columns. This is achieved by expanding the third column (with the help text) to the remaining width. For this to work, ARGPARSER_MAX_COL_WIDTH_3 must be set to 0.

5.5.2. Usage messages

As we already saw upon the occasion of an error, our try_argparser.sh usage message looks as follows:

$ bash ../tutorial/try_argparser.sh --usage
Usage: try_argparser.sh [-h,-? | -u | -V]
                        [-d,-D={A-C}]
                        [-e,-E=VAL_5,E]
                        [-f,-F]
                        [-g,-G]
                        -a,-A=VAL_1,A
                        -b,-B=VAL_2,B...
                        -c,-C={A,B}...
                        [{1,2}]
                        pos_2

The usage message clearly summarizes the arguments, including name aliases (always taking all short options, or, if absent, all long options, or vice versa, see below), indicates whether they're optional or mandatory (optionals use square brackets), and specifies the choice values (in curly braces) and, partially, the argument number (an ellipsis, i.e., "...", for an infinite number). Short options precede long options, options with default precede those without, likewise for positionals, and keyword arguments precede positional arguments. All of these groups are sorted alphabetically by the first option name as key. The help, usage, and version options precede all groups.

For a better overview when having lots of arguments, we can choose a columnar layout instead of the single row, using ARGPARSER_USAGE_MESSAGE_ORIENTATION:

$ ARGPARSER_USAGE_MESSAGE_ORIENTATION=column bash ../tutorial/try_argparser.sh --usage
Usage: try_argparser.sh [-h,-? | -u | -V]
                        [-d,-D={A-C}]
                        [-e,-E=VAL_5,E]
                        [-f,-F]
                        [-g,-G]
                        -a,-A=VAL_1,A
                        -b,-B=VAL_2,B...
                        -c,-C={A,B}...
                        [{1,2}]
                        pos_2

Additionally, we may choose to show the long options by ARGPARSER_USAGE_MESSAGE_OPTION_TYPE:

$ ARGPARSER_USAGE_MESSAGE_OPTION_TYPE=long ARGPARSER_USAGE_MESSAGE_ORIENTATION=column bash ../tutorial/try_argparser.sh --usage
Usage: try_argparser.sh [--help | --usage | --version]
                        [--var-4,--var-d={A-C}]
                        [--var-5,--var-e=VAL_5,VAR_E]
                        [--var-6,--var-f]
                        [--var-7,--var-g]
                        --var-1,--var-a=VAL_1,VAR_A
                        --var-2,--var-b=VAL_2,VAR_B...
                        --var-3,--var-c={A,B}...
                        [{1,2}]
                        pos_2

Of course, you would normally give these environment variables in your script and wouldn't rely on the user to give them on the command line—especially not, when he's looking for how to use the script.

🡄 5.4. Arguments definition files           5.6. Help and usage message files 🡆