9.2 Using the module

To use this module we have to declare a set of script options with the function mbfl_declare_option(). Options declarations should be done at the beginning of the script, before doing anything else, or in the “before parsing options” functions.

In the main block of the script, options are parsed by invoking mbfl_getopts_parse(): this function will update global variables and invoke a script function for each option on the command line. It can also select a function to be invoked as the main action of the script.

Option with no argument

Example of option declaration:

mbfl_declare_option ALPHA no a alpha noarg "enable alpha option"

this code declares an option with no argument having properties:

• Global variable script_option_ALPHA, which will be set to no by default and to yes if the option is used.
• Brief switch -a.
• Long switch --alpha.
• Description enable alpha option, to be shown in the usage help screen.

If the option is used: the function script_option_update_alpha is invoked (if it exists) with no arguments, after the variable script_option_ALPHA has been set to yes; in the function name: alpha is the lower case variant of the keyword ALPHA. Valid option uses are:

$ script.sh -a
$ script.sh --alpha

Option with argument

Example of option declaration:

mbfl_declare_option BETA 123 b beta witharg "select beta value"

this code declares an option with argument having properties:

• Global variable script_option_BETA, which will be set to 123 by default and to the value selected on the command line if the option is used.
• Brief switch -b.
• Long switch --beta.
• Description select beta value, to be shown in the usage output.

If the option is used: the function script_option_update_beta is invoked (if it exists) with no arguments, after the variable script_option_BETA has been set to the selected value; in the function name: beta is the lower case variant of the keyword BETA. Valid option uses are:

$ script.sh -b456
$ script.sh --beta=456

it is an error to use the switch -b or --beta with no argument (that is: with an empty string as argument).

Action options

A special option example:

mbfl_declare_option ACTION_GAMMA \
   no g gamma noarg "do gamma action"
mbfl_declare_option ACTION_DELTA \
   yes d delta noarg "do delta action"

this code declares two options with no arguments; the difference from the other declarations is that the keywords are prefixed with ACTION_: this prefix is recognised by the module and causes, if the option is used on the command line, the following code to be evaluated at arguments parsing time:

mbfl_main_set_main script_action_gamma

or:

mbfl_main_set_main script_action_delta

where the argument script_action_gamma is built by prefixing the lower case version of the keyword with script_. The code selects a function as main function for the script. Driving script execution.

Additionally, if the default value is yes: the main function is selected at declaration time (that is by mbfl_declare_option()); this is useful to declare an action option and select automatically the action function. In the example: the function script_action_delta() is selected as main action function.

It is an error to declare a keyword prefixed with ACTION_ with an option with argument (witharg as argument to mbfl_declare_option()).

This document describes version 3.0.0-devel.0 of Marcos Bash Functions Library.