The Bash Argsparse Library 1.8
An high level argument parsing library for bash.
Loading...
Searching...
No Matches
Calling program usage description message.

Functions

 argsparse_usage ()
 A generic help message generated from the options and their descriptions.
 
 argsparse_usage_long ()
 Fully describe the program syntax and options to the end-user.
 
 argsparse_usage_short ()
 Print a short description of the program syntax.
 
 set_option_help ()
 Default trigger for –help option.
 
 usage ()
 Default usage function.
 

Variables

String Array __argsparse_parameters_description
 Internal use only.
 
String argsparse_usage_description
 Usage description additionnal string.
 

Detailed Description

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:

file directory pipe terminal socket link char unsignedint uint
integer int hexa ipv4 ipv6 ip hostname host portnumber port
username group date
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:
Also, still during option parsing and for every option of the form "--optionname":
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.

Function Documentation

◆ argsparse_usage()

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()

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()

set_option_help ( )

Default trigger for –help option.

Will actually only call usage().

Returns
Whatever usage() returns.

◆ usage()

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

Variable Documentation

◆ argsparse_usage_description

String argsparse_usage_description

Usage description additionnal string.

The content of this variable will be appended to the argsparse_usage() output.