---

2.5 Function parameters handling ¶

Preprocessor Macro: mbfl_mandatory_parameter (VARNAME, NUMBER, DESCRIPTION, OPTIONS) ¶

Define a variable local to a shell function holding an argument to the function. VARNAME is the name of the variable; NUMBER is the positional parameter number; DESCRIPTION is a description of the argument; OPTIONS are options for the shell built–in declare.

For example, the following:

mbfl_mandatory_parameter(PATHNAME, 2, file pathname)

is expanded to:

declare PATHNAME=${2:?"missing file pathname parameter to '$FUNCNAME'"}

Another example the following function:

function message () {
  mbfl_mandatory_parameter(PROGNAME, 1, program name, -r)
  mbfl_mandatory_parameter(STRING,   2, message string)

  printf '%s: %s\n' "$PROGNAME" "$STRING"
}

is expanded to:

function message () {
  declare -r PROGNAME=${1:?"missing program name parameter to '$FUNCNAME'"}
  declare    STRING=${2:?"missing message string parameter to '$FUNCNAME'"}

  printf '%s: %s\n' "$PROGNAME" "$STRING"
}

and so it is a function with two mandatory parameters.

Preprocessor Macro: mbfl_mandatory_nameref_parameter (NAME, NUMBER, DESCRIPTION) ¶

Similar to mbfl_mandatory_parameter() but use the -n attribute when declaring the variable. This makes the new variable a NAMEREF for the given variable name; See Shell Parameters.

A use of this macro roughly expands into:

declare mbfl_a_variable_NAME=${NUMBER:?}
declare -n NAME=$mbfl_a_variable_NAME

where the proxy variable NAME is defined as an alias of the data variable, whose name is stored in the numeric parameter; the additional name variable mbfl_a_variable_NAME holds the name of the data variable. We can use the macro mbfl_datavar() to retrieve the name of the data variable. Variable name references.

Preprocessor Macro: mbfl_mandatory_integer_parameter (VARNAME, NUMBER, DESCRIPTION) ¶

Like mbfl_mandatory_parameter() but use the -i attribute when declaring the variable. This assigns the integer attribute to the variable; See Bash Builtins.

Preprocessor Macro: mbfl_optional_parameter (VARNAME, NUMBER) ¶

Preprocessor Macro: mbfl_optional_parameter (VARNAME, NUMBER, DEFAULT_VALUE) ¶

Preprocessor Macro: mbfl_optional_parameter (VARNAME, NUMBER, DEFAULT_VALUE, OPTIONS) ¶

Define a variable local to a shell function holding an argument to the function.

The argument VARNAME is the name of the variable. The argument NUMBER is the positional parameter number. The argument DEFAULT_VALUE is the initialisation value for the variable if the argument is not used; when DEFAULT_VALUE is not present: the variable is left empty; OPTIONS are options for the shell built–in declare.

Example, the following:

mbfl_optional_parameter(COUNT, 2, 123)

is expanded to:

declare COUNT=${2:-123}"

and the following:

mbfl_optional_parameter(COUNT, 2,,-i)

is expanded to:

declare -i COUNT=${2:-}"

Preprocessor Macro: mbfl_optional_integer_parameter (VARNAME, NUMBER) ¶

Preprocessor Macro: mbfl_optional_integer_parameter (VARNAME, NUMBER, DEFAULT_VALUE) ¶

Like mbfl_optional_parameter() but use the -i attribute when declaring the variable; this assigns the integer attribute to the variable; See Bash Builtins.

NOTE When the default value is missing: Bash automatically sets the variable to zero!