2.7.3 Full NAMEREF declarations ¶

The following macros declare local and global variables we can use with the NAMEREF mechanism. All the variables declared with the macros below can be unset using mbfl_unset_varref(); for details Unsetting NAMEREF declarations. When defining array variables we can use specific macros, rather than the ones below; Declaring arrays as variable references.

Preprocessor Macro: mbfl_declare_varref (NAME, INIT_VALUE, DECLARE_OPTIONS) ¶

A use of this macro expands into:

declare mbfl_a_variable_NAME
mbfl_variable_alloc mbfl_a_variable_NAME
declare DECLARE_OPTIONS $mbfl_a_variable_NAME
declare -n NAME=$mbfl_a_variable_NAME

When INIT_VALUE is empty, it finishes with:

NAME=

which defines the variable and causes test -v VARNAME to return true; defining the variable this way works with scalar variables, but defines an array variables as containing an element with key ‘0’, which is probably not what we want.

When INIT_VALUE is not empty, it finishes with:

NAME=INIT_VALUE

A name variable mbfl_a_variable_NAME is declared and filled with a unique data variable name by mbfl_variable_alloc(); then the data variable is declared; finally a proxy variable NAME is defined as alias for the data variable. If the macro is used at top–level: the variables are global.

We can use the argument DECLARE_OPTIONS to declare a global data variable:

mbfl_declare_varref(VARNAME, INIT_VALUE, -g)

Preprocessor Macro: mbfl_declare_global_varref (NAME, INIT_VALUE, OPTIONS) ¶

Like mbfl_declare_varref() but always include the option -g. Its expansion is:

mbfl_declare_global_varref(NAME, INIT_VALUE, OPTIONS)
→ mbfl_declare_varref(NAME, INIT_VALUE, -g OPTIONS)

With these macros it is not possible to declare a read–only array; the macro use:

mbfl_declare_varref(ARRY, ([a]=1), -rA)

expands into:

declare mbfl_a_variable_ARRY
mbfl_variable_alloc mbfl_a_variable_ARRY
declare -rA $mbfl_a_variable_ARRY
declare -n ARRY=$mbfl_a_variable_ARRY
ARRY=([a]=1)

so when the array is initialised it has already been declared as read–only: an error results. It is not possible to modify this macro to allow such declaration, because, while this syntax works:

declare -rA ARRY=([a]=1)

the following is invalid according to Bash:

declare -rA $mbfl_a_variable_ARRY=([a]=1)

Preprocessor Macro: mbfl_declare_nameref (NAME, DATA_VARNAME_EXPR) ¶

A use of this macro expands into:

declare    mbfl_a_variable_NAME=DATA_VARNAME_EXPR
declare -n NAME=$mbfl_a_variable_NAME

Declare a proxy variable NAME aliasing the data variable whose value is the result of evaluating DATA_VARNAME_EXPR.

NOTE We cannot declare mbfl_a_variable_NAME as read–only because the we cannot unset it.

We can use this macro as follows:

function main () {
    declare VARNAME
    worker VARNAME
    mbfl_declare_nameref(VAR, $VARNAME)
    ...
}

function worker () {
    mbfl_mandatory_nameref_parameter(RV, 1)
    mbfl_declare_varref(VAR, 123, -g)
    RV=mbfl_datavar(VAR)
}

main