Nameref Variables (declare -n) for Passing Arrays by Reference

#!/bin/bash
original="hello"
declare -n alias_var=original
echo "through alias: $alias_var"
alias_var="changed"
echo "original is now: $original"

#!/bin/bash
add_item() {
    local -n target_array=$1
    target_array+=("$2")
}

fruits=("apple" "banana")
add_item fruits "cherry"
echo "fruits now: ${fruits[*]}"

#!/bin/bash
square_into() {
    local -n result_ref=$1
    result_ref=$(( $2 * $2 ))
}

square_into answer 7
echo "7 squared is $answer"

1. Forgetting that bash functions normally receive array arguments by expanding them into separate words, losing the array structure; passing the array's NAME and using a nameref preserves it.
2. Naming the nameref parameter the same as the variable being referenced in the caller, which can create a self-reference error.
3. Not realizing declare -n is a bash 4.3+ feature, so it won't work in scripts intended for very old bash or POSIX sh.

• declare -n ref=varname makes ref an alias for whatever variable varname names, including arrays.
• Passing an array's NAME (not "${arr[@]}") as an argument, then binding it with declare -n inside the function, lets the function read and modify the caller's actual array.
• Namerefs avoid the common workaround of using global variables to get array data out of a function.
• Give the nameref parameter a distinct name from any variable it might reference to avoid the "circular reference" error.