feat(bash_completion): support BASH_COMPLETION_FINALIZE{,_CMD}_HOOKS

- deal with nested completion initializations
- rename the function `_comp_{return_hook => finalize}`
- add an associative array `BASH_COMPLETION_FINALIZE_CMD_HOOKS`
  originally suggested as `_comp_return_hooks` in Ref. [1]
- add a new array `BASH_COMPLETION_FINALIZE_HOOKS`

[1] #720 (comment)

Author: akinomyoga

bash_completion

@@ -819,13 +819,46 @@ _comp_variable_assignments()
     return 0
 }
 
-_comp_return_hook()
-{
-    ((${#FUNCNAME[*]} != 2)) && return  # this _will_ need some refinement and thought
-    echo "Hello from return hook for ${FUNCNAME[1]}"
-    echo "words: ${words[@]}"
-    echo "COMPREPLY: ${COMPREPLY[@]}"
+_comp_finalize__depth=()
+_comp_finalize__original_return_trap=
+
+# This associative array contains the finalizer commands with the key
+# being the name of the completed command.
+declare -gA BASH_COMPLETION_FINALIZE_CMD_HOOKS=()
+
+# This array contains the general finalizer commands that will be
+# executed for all the commands.
+BASH_COMPLETION_FINALIZE_HOOKS=()
+
+_comp_finalize()
+{
+    ((${#_comp_finalize__depth[@]})) || return 0
+    while ((${#FUNCNAME[@]} <= ${_comp_finalize__depth[-1]})); do
+        if ((${#FUNCNAME[@]} == ${_comp_finalize__depth[-1]})); then
+            # Call finalizer for each command
+            local __comp_hook=${BASH_COMPLETION_FINALIZE_CMD_HOOKS[${words[0]-}]-}
+            eval -- "$__comp_hook"
+
+            # Call general finalizers
+            if ((${#BASH_COMPLETION_FINALIZE_HOOKS[@]})); then
+                for __comp_hook in "${BASH_COMPLETION_FINALIZE_HOOKS[@]}"; do
+                    eval -- "$__comp_hook"
+                done
+            fi
+        fi
+
+        unset -v '_comp_finalize__depth[-1]'
+        if ((${#_comp_finalize__depth[@]} == 0)); then
+            eval -- "${_comp_finalize__original_return_trap:-trap - RETURN}"
+            _comp_finalize__original_return_trap=
+            break
+        fi
+    done
 }
+# Note: We need to set "trace" function attribute of _comp_finalize to
+# make the trap restoration by "trap - RETURN" take effect in the
+# upper level.
+declare -ft _comp_finalize
 
 # Initialize completion and deal with various general things: do file
 # and variable completion where appropriate, and adjust prev, words,
@@ -846,7 +879,25 @@ _init_completion()
 {
     local exclude="" flag outx errx inx OPTIND=1
 
-    trap _comp_return_hook RETURN
+    # Install "_comp_finalize" to the RETURN trap when "_init_completion" is
+    # called for the top-level completion. [ Note: the completion function may
+    # be called recursively using "_command_offset", etc. ]
+    if ((${#_comp_finalize__depth[@]} == 0)); then
+        if shopt -q extdebug || shopt -qo functrace; then
+            # If extdebug / functrace is set, we need to explicitly save and
+            # restore the original trap handler because the outer trap handlers
+            # will be affected by "trap - RETURN" inside functions with these
+            # settings.
+            _comp_finalize__original_return_trap=$(trap -p RETURN)
+        else
+            # Otherwise, the outer RETURN trap will be restored when the RETURN
+            # trap is removed inside the functions using "trap - RETURN".  So, we
+            # do not need to explicitly save the outer trap handler.
+            _comp_finalize__original_return_trap=
+        fi
+        trap _comp_finalize RETURN
+    fi
+    _comp_finalize__depth+=(${#FUNCNAME[@]})
 
     while getopts "n:e:o:i:s" flag "$@"; do
         case $flag in