9.3 Predefined options

A set of predefined options is recognised by the library and not handed to the user defined functions.

--tmpdir=DIR

Selects a directory for temporary files. The default value is the one in the environment variable TMPDIR, or /tmp/$USER if that variable is not set. The value is stored in the variable mbfl_option_TMPDIR.

--encoded-args

Signals to the library that the non–option arguments and the option values are encoded in hexadecimal strings. Encoding is useful to avoid quoting problems when invoking a script from another one.

If this option is used: the values are decoded by mbfl_getopts_parse() before storing them in the ARGV array and before being stored in the option’s specific global variables.

-v

--verbose

Turns on verbose messages. If this option is used: The function mbfl_option_verbose() returns true. Printing messages to the console.

--silent

Turns off verbose messages. If this option is used: The function mbfl_option_verbose() returns false.

--verbose-program

If used: The --verbose option is added to the command line of external programs that support it. The function mbfl_option_verbose_program() returns true or false depending on the state of this option.

--show-program

--show-programs

Prints the command line of executed external programs.

--debug

Turns on debugging messages. Automatically turns on verbose messages and program showing. Printing messages to the console.

--test

Turns on test execution. Testing a script and external programs.

--null

Signals to the script that it has to use the null character to separate values, instead of the common newline. The global variable mbfl_option_NULL is set to yes.

-f

--force

Signals to the script that it does not have to query the user before doing dangerous operations, like overwriting files. The global variable mbfl_option_INTERACTIVE is set to no.

-i

--interactive

Signals to the script that it does have to query the user before doing dangerous operations, like overwriting files. The global variable mbfl_option_INTERACTIVE is set to yes.

--validate-programs

Validates the existence of all the programs needed by the script; then exits. The exit code is zero if all the programs were found, one otherwise.

--list-exit-codes

Prints a list of numerical exit codes and their associated names, as declared in the script. Declaring exit codes.

--print-exit-code=NAME

Prints the numerical exit code associated to NAME.

--print-exit-code-names=CODE

Prints the list of names associated to the numerical exit CODE.

--version

Prints to the standard output of the script the contents of the global variable mbfl_message_VERSION, then exits with code zero. The variable makes use of the service variables. Required user defined variables.

--version-only

Prints to the standard output of the script the contents of the global variable script_VERSION, then exits with code zero. Required user defined variables.

--license

Prints to the standard output of the script the contents of one of the global variables mbfl_message_LICENSE_*, then exits with code zero. The variable makes use of the service variables. Required user defined variables.

-h

--help

--usage

Prints to the standard output of the script: the contents of the global variable script_USAGE; a newline; the string options:; a newline; an automatically generated string describing the options declared with mbfl_declare_option(); a string describing the MBFL default options; the contents of the global variable script_EXAMPLES. Then exits with code zero. Required user defined variables.

-H

--brief-help

--brief-usage

Prints to the standard output of the script: the contents of the global variable script_USAGE; a newline; the string options:; a newline; an automatically generated string describing the options declared with mbfl_declare_option(). Then exits with code zero.

The difference with --help is that predefined options and usage examples are not displayed.

--print-options

Print all the long options with mbfl_getopts_print_long_switches(), then exit the script with code zero.

The following functions may be used to set, unset and query the state of the predefined options.

Function: mbfl_option_encoded_args

Function: mbfl_set_option_encoded_args

Function: mbfl_unset_option_encoded_args

Query/set/unset the encoded arguments option.

mbfl_option_encoded_args() returns true if the option --encoded-args was used on the command line.

Function: mbfl_option_verbose

Function: mbfl_set_option_verbose

Function: mbfl_unset_option_verbose

Query/set/unset the verbose messages option.

mbfl_option_verbose() returns true if the option --verbose was used on the command line after all the occurrences of --silent; it returns false if the option --silent was used on the command line after all the occurrences of --verbose.

Function: mbfl_option_verbose_program

Function: mbfl_set_option_verbose_program

Function: mbfl_unset_option_verbose_program

Query/set/unset verbose execution for external programs.

This option, of course, is supported only for programs that are known by MBFL (like rm): if a program is executed with mbfl_program_exec(), it is responsibility of the caller to use the option.

Function: mbfl_option_show_program

Function: mbfl_set_option_show_program

Function: mbfl_unset_option_show_program

Print the command line of executed external program. This does not disable program execution, it just prints the command line before executing it.

Function: mbfl_option_test

Function: mbfl_set_option_test

Function: mbfl_unset_option_test

Query/set/unset the test execution option.

Function: mbfl_option_debug

Function: mbfl_set_option_debug

Function: mbfl_unset_option_debug

Query/set/unset the debug messages option.

Function: mbfl_option_null

Function: mbfl_set_option_null

Function: mbfl_unset_option_null

Query/set/unset the null list separator option.

Function: mbfl_option_interactive

Function: mbfl_set_option_interactive

Function: mbfl_unset_option_interactive

Query/set/unset the interactive execution option.

mbfl_option_interactive() returns true if the option --interactive was used on the command line after all the occurrences of --force; it returns false if the option --force was used on the command line after all the occurrences of --interactive.

The following are special option functions.

Function: mbfl_option_test_save

Save the current state of the test option then invokes mbfl_unset_option_test().

Function: mbfl_option_test_restore

Restore the state of the test option to the one before the invocation to mbfl_option_test_save().

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