17.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 on stderr.

--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.

An use of the option --force on the command line overrides all the previous uses of the option --interactive.

-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.

An use of the option --interactive on the command line overrides all the previous uses of the option --force.

--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. We can pair this option with --verbose to see the list of programs and checks.

--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_debug
Function: mbfl_set_option_debug
Function: mbfl_unset_option_debug

Query/set/unset the encoded arguments option.

mbfl_option_debug() returns true if the option --debug was used on the command line.

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_force
Function: mbfl_set_option_force
Function: mbfl_unset_option_force

Query/set/unset the encoded arguments option.

mbfl_option_force() returns true if the option --force was used on the command line.

Function: mbfl_option_interactive
Function: mbfl_set_option_interactive
Function: mbfl_unset_option_interactive

Query/set/unset the encoded arguments option.

mbfl_option_interactive() returns true if the option --interactive was used on the command line.

Function: mbfl_option_null
Function: mbfl_set_option_null
Function: mbfl_unset_option_null

Query/set/unset the encoded arguments option.

mbfl_option_null() returns true if the option --null was used on the command line.

Function: mbfl_option_show_program
Function: mbfl_set_option_show_program
Function: mbfl_unset_option_show_program

Query/set/unset the encoded arguments option.

mbfl_option_show_program() returns true if the option --show-program was used on the command line. Print the command line of executed external program on stderr. 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 encoded arguments option.

mbfl_option_test() returns true if the option --test was used on the command line.

Function: mbfl_option_verbose
Function: mbfl_set_option_verbose
Function: mbfl_unset_option_verbose

Query/set/unset the encoded arguments option.

mbfl_option_verbose() returns true if the option --verbose was used on the command line.

Function: mbfl_option_verbose_program
Function: mbfl_set_option_verbose_program
Function: mbfl_unset_option_verbose_program

Query/set/unset the encoded arguments option.

mbfl_option_verbose_program() returns true if the option --verbose-program was used on the command line. 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.

The following are special option functions.

Function: mbfl_option_debug_save
Function: mbfl_option_debug_restore

Save/restore the current state of the --debug option then invoke mbfl_unset_option_debug(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_encoded_args_save
Function: mbfl_option_encoded_args_restore

Save/restore the current state of the --encoded-args option then invoke mbfl_unset_option_encoded_args(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_force_save
Function: mbfl_option_force_restore

Save/restore the current state of the --force option then invoke mbfl_unset_option_force(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_interactive_save
Function: mbfl_option_interactive_restore

Save/restore the current state of the --interactive option then invoke mbfl_unset_option_interactive(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_null_save
Function: mbfl_option_null_restore

Save/restore the current state of the --null option then invoke mbfl_unset_option_null(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_show_program_save
Function: mbfl_option_show_program_restore

Save/restore the current state of the --show-program option then invoke mbfl_unset_option_show_program(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_test_save
Function: mbfl_option_test_restore

Save/restore the current state of the --test option then invoke mbfl_unset_option_test(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_verbose_save
Function: mbfl_option_verbose_restore

Save/restore the current state of the --verbose option then invoke mbfl_unset_option_verbose(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.

Function: mbfl_option_verbose_program_save
Function: mbfl_option_verbose_program_restore

Save/restore the current state of the --verbose-program option then invoke mbfl_unset_option_verbose_program(). Upon entering these functions: the value of $? is saved, the options states are processed, then the saved $? value is used as return value for the function call.


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