|
String Array | __argsparse_parameters_description |
| Internal use only.
|
|
String | argsparse_usage_description |
| Usage description additionnal string.
|
|
- URL
- https://github.com/Anvil/bash-argsparse
- Purpose
- To replace the option-parsing and usage-describing functions commonly rewritten in all scripts.
- Note
- This library is implemented for bash version 4. Prior versions of bash will fail at interpreting that code.
-
The extglob shell option will be enabled and posix mode will be disabled when loading the library. Changing those settings afterwards will make the library execution fail.
- Usage
- Use the argsparse_use_option() function to declare your options with their single letter counterparts, along with their description.
- The argsparse_use_option() syntax is:
argsparse_use_option "optstring" "option description string" \
[ "property" ... ] [ "optional default value" ]
- An "optstring" is of the form "som=estring:". This would declare a long option named somestring. The ending ":" is optional and, if present, means the long option expects a value on the command line. The "=" char is also optional and means the immediatly following letter is the short single-letter equivalent option of –something.
- The "something" string must only contains ASCII letters/numbers/dash/underscore characters.
- Note
- What is referred later as "option" or "option name" (or even "long
option name") is the optstring without the ':' and '=' characters.
- Options may have properties.
Properties are set either at option declarations through the argsparse_use_option() function, or using the argsparse_set_option_property() function
The currently supported properties are:
- "hidden"
An hidden option will not be shown in usage.
- "mandatory"
An option marked as mandatory is required on the command line. If a mandatory option is omited by the user, usage() will be triggered by argsparse_parse_options().
- "value"
On the command line, the option will require a value. Same effect if you end your optstring with a ':' char.
- "default:<defaultvalue>"
The default value for the option.
- "short:<char>"
The short single-letter equivalent of the option.
- "type:<typename>"
Give a type to the option value. User input value will be checked against built-in type verifications or the "check_type_<typename>" function. You cannot override a built-in type. Built-in types are:
file directory pipe terminal socket link char unsignedint uint
integer int hexa ipv4 ipv6 ip hostname host portnumber port
username group date
- "exclude:<option> <option>"
The exclude property value is a space-separated list of other options. User wont be able to provided two mutually exclusive options on the command line.
e.g: if you set exclude property for the –foo option this way: argsparse_set_option_property "exclude:opt1 opt2" foo
Then –opt1 and –foo are not allowed on the same command line invokation. And same goes for –opt2 and –foo. This foo exclude property setting wouldnt make –opt1 and –opt2, mutually exclusive though.
- "alias:<option> <option>"
This property allows an option to set multiple other without-value options instead. Recursive aliases are permitted but no loop detection is made, so be careful.
e.g: if you declare an option 'opt' like this: argsparse_use_option opt "my description" "alias:opt1 opt2"
Then if the user is doing –opt on the command line, it will be as if he would have done –opt1 –opt2
- cumulative
Implies 'value'. Everytime a cumulative option "optionname" is passed on the command line, the value is stored at the end of an array named "cumulated_values_<optionname>".
e.g: for a script with an opt1 option declared this way: argsparse_use_option opt1 "some description" cumulative
and invoked with: --opt1 value1 --opt1 value2
after argsparse_parse_options(), "${cumulated_values_opt1[0]}" will expand to value1, and ${cumulated_values_opt1[1]} will expand to value2.
- cumulativeset
Exactly like cumulative, except only uniq values are kept.
e.g: for a script with an opt1 option declared this way: argsparse_use_option opt1 "some description" cumulativeset
and invoked with: --opt1 value1 --opt1 value2 --opt1 value1
after argsparse_parse_options(), "${cumulated_values_opt1[0]}" will expand to value1, and "${cumulated_values_opt1[1]}" will expand to value2. There would be no "${cumulated_values_opt1[2]}" value.
- "require:<option> <option>"
Creates a dependency between options. if you declare an option with: argsparse_use_option opt1 "something" require:"opt2 opt3"
argsparse_parse_options() would return with an error if "--opt1" is given on the commande line without "--opt2" or without "--opt3".
- You can test if an option has a property using the argsparse_has_option_property() function.
argsparse_has_option_property <option> <property>
- Parsing positionnal parameters
- After the options are declared, invoke the function argsparse_parse_options() with the all script parameters. This will define:
- program_params, an array, containing all non-option parameters.
- program_options, an associative array. For each record of the array:
- The key is the long option name.
- And about values:
- If option doesn't expect a value on the command line, the value represents how many times the option has been found on the command line
- If option does require a value, the array record value is the value of the last occurence of the option found on the command line.
- If option is cumulative (or cumulativeset), the array record value is the number of values passed by the user.
After argsparse_parse_options() invokation, you can check if an option have was on the command line (or not) using the argsparse_is_option_set() function.
e.g: argsparse_is_option_set "long-option-name"
- The "usage()" function
- If a 'usage' function is defined, and shall argsparse_parse_options() return with non-zero status, 'usage' will be automatically called.
- Note
- This library automatically defines a default 'usage' function, which may be removed or overridden by the sourcing program afterwards.
- Value setting internal logic
- During option parsing, for every option of the form '–optionname' expecting a value:
- If there exists an array named "option_<optionname>_values" and the user-given value doesn't belong to that array, then the argsparse_parse_options() function immediately returns with non-zero status, triggering 'usage'.
- If the "option_<optionname>_values" array does not exist, but if the option has a type property field, then the value format will be checked agaisnt that type.
- If a function named "check_value_of_<optionname>" has been defined, it will be called with the user-given value as its first positionnal parameter. If check_value_of_<optionname> returns with non-zero status, then parse_option immediately returns with non-zero status, triggering the 'usage' function.
- Also, still during option parsing and for every option of the form "--optionname":
- After value-checking, if a function named "set_option_<optionname>" exists, then, instead of directly modifying the "program_options" associative array, this function is automatically called with 'optionname' as its first positionnal parameter, and, if 'optionname' expected a value, the value is given as the function second positionnal parameter.
- About functions return values...
All the functions will return with an error (usually a return code of 1) if called with a wrong number of parameters, and return with 0 if everything went fine.
◆ argsparse_usage()
A generic help message generated from the options and their descriptions.
Will print both a rather-short and a quite long description of the program and its options. Just provided to be wrapped in your own usage().
◆ argsparse_usage_long()
Fully describe the program syntax and options to the end-user.
This function generates and prints the "long" description of the program usage. Print all options along with their descriptions provided to argsparse_use_option().
◆ argsparse_usage_short()
argsparse_usage_short |
( |
| ) |
|
Print a short description of the program syntax.
Generate and print the "short" description of the program usage.
◆ set_option_help()
Default trigger for –help option.
Will actually only call usage().
- Returns
- Whatever usage() returns.
◆ usage()
Default usage function.
The default usage function. By default, it will be called by argsparse_parse_options() on error or if –help option provided by user on the command line. It can easily be overwritten if it does not suits your needs.
- Returns
- This function makes an exit with code 1
◆ argsparse_usage_description
String argsparse_usage_description |
Usage description additionnal string.
The content of this variable will be appended to the argsparse_usage() output.