The Argparser is not only able to compile a help message, but can also be guided by a separate file. Using the ARGPARSER_HELP_FILE environment variable pointing to this file, to a certain degree, you can customize the help message's look and structure by moving the blocks the message consists of around and enriching it by arbitrary text. Again, we use a simplified script as try_help_file.sh without alias names for the short and long options.
Contents of try_help_file.sh
#!/usr/bin/env bash
# Source the Argparser, reading the help message from a file.
dir="$(dirname "$(readlink --canonicalize-existing "$0")")"
dir="$(readlink --canonicalize-existing "${dir}/../resources/")"
ARGPARSER_HELP_FILE="${dir}/help_message.txt"
# 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 | var-1 | VAL_1 | | | uint | 1 | Mandatory options | | one value without default or choice "
"var_2 | b | var-2 | VAL_2 | | | int | + | Mandatory options | | at least one value without default or choice "
"var_3 | c | var-3 | VAL_3 | | A,B | char | + | Mandatory options | | at least one value with choice "
"var_4 | d | | VAL_4 | A | A-C | char | 1 | Optional options | | one value with default and choice "
"var_5 | | var-5 | VAL_5 | E | | str | 1 | Optional options | | one value with default "
"var_6 | f | var-6 | VAL_6 | false | | bool | 0 | Optional options | | no value (flag) with default "
"var_7 | g | var-7 | VAL_7 | true | | bool | 0 | Optional options | deprecated | no value (flag) with default "
)
source argparser -- "$@"Additionally, we need a separate file, which we'll call help_message.txt and have passed as value to ARGPARSER_HELP_FILE. This plain-text file stores the help message's structure and can contain arbitrary additional content.
$ sed '1,15d' ../resources/help_message.txt
# Print the header.
A brief header summarizes the way how to interpret the help message.
@Header
# Print the positional arguments.
The following arguments are positional:
@@Positional arguments
# Print the options from the "Mandatory options" group.
The following options have no default value:
@@Mandatory options
# Print the options from the "Optional options" group.
The following options have a default value:
@@Optional options
# Print the three help options.
There are always three options for the help messages:
@@HelpNow, we get the following help message:
$ bash ../tutorial/try_help_file.sh -h
A brief header summarizes the way how to interpret the help message.
Usage: try_help_file.sh [OPTIONS] ARGUMENTS -- [pos_1] pos_2
Mandatory arguments to long options are mandatory for short options too.
The following arguments are positional:
+---------------------------------------------------------------------------------+
| [pos_1= one positional argument with default and choice |
| {1,2}] (default: 2) |
| pos_2 two positional arguments without default or choice |
+---------------------------------------------------------------------------------+
The following options have no default value:
+---------------------------------------------------------------------------------+
| -a, --var-1=VAL_1 one value without default or choice |
| -b, --var-2=VAL_2... at least one value without default or choice |
| -c, --var-3={A,B}... at least one value with choice |
+---------------------------------------------------------------------------------+
The following options have a default value:
+---------------------------------------------------------------------------------+
| [-d= one value with default and choice (default: "A") |
| {A-C}] |
| [--var-5=VAL_5] one value with default (default: "E") |
| [-f], [--var-6] no value (flag) with default (default: false) |
| [-g], [--var-7] (DEPRECATED) no value (flag) with default (default: |
| true) |
+---------------------------------------------------------------------------------+
There are always three options for the help messages:
+---------------------------------------------------------------------------------+
| [-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) |
+---------------------------------------------------------------------------------+When you compare the structure of this help message with both the previous version and the help file, you see that there, you can include the sections from the auto-generated help message by prefixing their names with an ARGPARSER_HELP_FILE_INCLUDE_CHAR character, defaulting to an "@". Generally speaking, an include directive, as the commands are referred to, like @Section, includes the section named "Section".
The following section names (include directives) are supported, explained in greater detail in the reference below:
Thereby, <ArgumentGroup> can be the name of any argument group given in the arguments definition, like "Mandatory options" for the include directive @Mandatory options or "Optional options" for the include directive @Optional options. @Description prints the ARGPARSER_HELP_DESCRIPTION, @Help prints the help, usage, and version options (depending on which of them are defined by ARGPARSER_ADD_HELP, ARGPARSER_ADD_USAGE, or ARGPARSER_ADD_VERSION), @Remark prints the remark that mandatory arguments to long options are mandatory for short options too, and @Usage prints the usage line. Finally, the shorthand @All means to print the usage line, the description, the remark, all argument groups, and the help options, in this order, while @Header prints the usage line, the description, and the remark.
If the include character is doubled, the section name (the respective arguments group) is suppressed, like in our example above. Since we wrote introductory sentences for the sections, there is no need to have them given, as well. Likewise, given that we had just one arguments group, we likely wouldn't need to list its name, since the sections serve structuring purposes which would be rather superfluous for a single group.
Further, lines starting with a "#" character in the help file aren't printed if ARGPARSER_HELP_FILE_KEEP_COMMENTS is set to false (the default). This allows you to comment your help file, perhaps to explain the structure—or just to write a header or footer with your name and debug email address inside.
The same as for help messages can be done for usage messages, using the ARGPARSER_USAGE_FILE, ARGPARSER_USAGE_FILE_INCLUDE_CHAR, and ARGPARSER_USAGE_FILE_KEEP_COMMENTS environment variables. However there, only the @All directive is supported, yet. Further, since there are no sections, the include character cannot be doubled.
🡄 5.5. Help and usage messages 5.7. Help and usage message localization 🡆