2.5 Function parameters handling

Preprocessor Macro: mbfl_mandatory_parameter varname number description

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.

Example, the following:

mbfl_mandatory_parameter(PATHNAME, 2, file pathname)

is expanded to:

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

Another example the following function:

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

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

is expanded to:

function message () {
  local PROGNAME=${1:?"missing program name parameter to '$FUNCNAME'"}
  local 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; (bash)Shell Parameters.

A use of this macro roughly expands into:

local mbfl_a_variable_NAME=${NUMBER:?}
local -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.

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; (bash)Bash Builtins.

Preprocessor Macro: mbfl_optional_parameter varname number

Preprocessor Macro: mbfl_optional_parameter varname number default_value

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.

Example, the following:

mbfl_optional_parameter(COUNT, 2, 123)

is expanded to:

local COUNT=${2:-123}"

and the following:

mbfl_optional_parameter(COUNT, 2)

is expanded to:

local 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; (bash)Bash Builtins.

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

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