feat(_comp_compgen): support -P prefix with auto-adjusted cur

The Bash builtin `compgen -P prefix ... -- "$cur"` prepends the prefix
AFTER filtering completions using `$cur`.  However, we usually want to
filter completions with "$cur" starting with the prefix.

To properly handle such a situation, one first needs to check if the
current content of "$cur" is compatible.  Then, one needs to modify
$cur to remove the prefix part, generate completions, and prepends the
prefix to the generated completions.  This pattern is used frequently
in the codebase, so it is good to handle it within `_comp_compgen`.

This patch implements the option `-P` of `_comp_compgen`.  When a
non-empty string is specified to the `-P` option, it performs the
necessary operations: the check and adjustment of $cur, the proper
filtering by the prefix string, and prepending of the prefix string.

Author: akinomyoga

bash_completion

@@ -439,6 +439,7 @@ _comp_split()
 # @var[in] $?
 # @var[in] _var
 # @var[in] _append
+# @var[in] _upvars
 # @return original $?
 _comp_compgen__error_fallback()
 {
@@ -449,6 +450,10 @@ _comp_compgen__error_fallback()
     else
         eval -- "$_var=()"
     fi
+    if ((${#_upvars[@]})); then
+        _comp_unlocal "${_upvars[@]}"
+        _upvars=()
+    fi
     return "$_status"
 }
 
@@ -478,6 +483,13 @@ _comp_compgen__error_fallback()
 #           is ${cur-}.
 #   -R      The same as -c ''.  Use raw outputs without filtering.
 #   -C dir  Evaluate compgen/generator in the specified directory.
+#   -P pref Prepend the prefix to the generated completions.  Unlike `compgen
+#           -P prefix`, this prefix is subject to filtering by `cur`.  When a
+#           non-empty prefix is specified, first `cur` is tested whether it is
+#           consistent with the prefix.  Then, `cur` is reduced for the part
+#           excluding the prefix, and the normal completion generation is
+#           performed.  Finally, the prefix is prepended to generated
+#           completions.
 # @var[in,opt] cur  Used as the default value of a prefix to filter the
 #   completions.
 #
@@ -562,6 +574,7 @@ _comp_compgen()
     local _var=
     local _cur=${_comp_compgen__cur-${cur-}}
     local _dir=""
+    local _prefix=""
     local _ifs=$' \t\n' _has_ifs=""
     local _icmd="" _xcmd=""
     local -a _upvars=()
@@ -572,7 +585,7 @@ _comp_compgen()
         shopt -u nocasematch
     fi
     local OPTIND=1 OPTARG="" OPTERR=0 _opt
-    while getopts ':av:U:Rc:C:lF:i:x:' _opt "$@"; do
+    while getopts ':av:U:Rc:C:P:lF:i:x:' _opt "$@"; do
         case $_opt in
             a) _append=set ;;
             v)
@@ -601,6 +614,7 @@ _comp_compgen()
                 fi
                 _dir=$OPTARG
                 ;;
+            P) _prefix=$OPTARG ;;
             l) _has_ifs=set _ifs=$'\n' ;;
             F) _has_ifs=set _ifs=$OPTARG ;;
             [ix])
@@ -636,6 +650,19 @@ _comp_compgen()
         [[ $_append ]] || _append=${_comp_compgen__append-}
     fi
 
+    local _prefix_fail=""
+    if [[ $_prefix ]]; then
+        if [[ $_cur == "$_prefix"* ]]; then
+            _cur=${_cur#"$_prefix"}
+        elif [[ $_prefix == "$_cur"* ]]; then
+            _cur=""
+        else
+            # No completions are generated because the current word does not match
+            # the prefix.
+            _prefix_fail=set
+        fi
+    fi
+
     if [[ $1 != -* ]]; then
         # usage: _comp_compgen [options] NAME args
         if [[ $_has_ifs ]]; then
@@ -657,6 +684,11 @@ _comp_compgen()
         fi
         shift
 
+        if [[ $_prefix_fail ]]; then
+            _comp_compgen__error_fallback
+            return 1
+        fi
+
         _comp_compgen__call_generator "$@"
     else
         # usage: _comp_compgen [options] -- [compgen_options]
@@ -680,6 +712,11 @@ _comp_compgen()
             return 2
         fi
 
+        if [[ $_prefix_fail ]]; then
+            _comp_compgen__error_fallback
+            return 1
+        fi
+
         _comp_compgen__call_builtin "$@"
     fi
 }
@@ -694,8 +731,6 @@ _comp_compgen()
 # @var[in] _var
 _comp_compgen__call_generator()
 {
-    ((${#_upvars[@]})) && _comp_unlocal "${_upvars[@]}"
-
     if [[ $_dir ]]; then
         local _original_pwd=$PWD
         local PWD=${PWD-} OLDPWD=${OLDPWD-}
@@ -708,14 +743,28 @@ _comp_compgen__call_generator()
             }
     fi
 
+    ((${#_upvars[@]})) && _comp_unlocal "${_upvars[@]}"
+
     local _comp_compgen__append=$_append
     local _comp_compgen__var=$_var
     local _comp_compgen__cur=$_cur cur=$_cur
+    if [[ $_prefix ]]; then
+        local -a tmp=()
+        local _comp_compgen__var=tmp
+        local _comp_compgen__append=""
+    fi
     # Note: we use $1 as a part of a function name, and we use $2... as
     # arguments to the function if any.
     # shellcheck disable=SC2145
     "${_generator[@]}" "$@"
     local _status=$?
+    if [[ $_prefix ]]; then
+        local _i
+        for _i in "${!tmp[@]}"; do
+            tmp[_i]=$_prefix${tmp[_i]}
+        done
+        _comp_compgen -RU tmp ${_append:+-a} -v "$_var" -- -W '"${tmp[@]}"'
+    fi
 
     # Go back to the original directory.
     # Note: Failure of this line results in the change of the current
@@ -770,6 +819,13 @@ if ((BASH_VERSINFO[0] > 5 || BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 3)); t
 
         ((${#_upvars[@]})) && _comp_unlocal "${_upvars[@]}"
         ((${#_result[@]})) || return
+
+        if [[ $_prefix ]]; then
+            local _i
+            for _i in "${!_result[@]}"; do
+                _result[_i]=$_prefix${_result[_i]}
+            done
+        fi
         if [[ $_append ]]; then
             eval -- "$_var+=(\"\${_result[@]}\")"
         else
@@ -794,7 +850,13 @@ else
         }
 
         ((${#_upvars[@]})) && _comp_unlocal "${_upvars[@]}"
-        _comp_split -l ${_append:+-a} "$_var" "$_result"
+
+        if [[ $_prefix ]]; then
+            _comp_split -l ${_append:+-a} "$_var" \
+                "$(IFS=$'\n' compgen -W '$_result' -P "$_prefix")"
+        else
+            _comp_split -l ${_append:+-a} "$_var" "$_result"
+        fi
     }
 fi
 

doc/api-and-naming.md

@@ -143,12 +143,12 @@ concept is later extended to also mean "eXported".
 
 The generator functions, which have names of the form `_comp_compgen_NAME`, are
 used to generate completion candidates.  A generator function is supposed to be
-called by `_comp_compgen [OPTS] NAME ARGS` where `OPTS = -aRl|-v var|-c cur|-C
-dir|-F sep` are the options to modify the behavior (see the code comment of
-`_comp_compgen` for details).  When there are no `opts`, the generator function
-is supposed to be directly called as `_comp_compgen_NAME ARGS`.  The result is
-stored in the target variable (which is `COMPREPLY` by default but can be
-specified by `-v var` in `OPTS`).
+called by `_comp_compgen [OPTS] NAME ARGS` where `OPTS = -aR|-v var|-c cur|-C
+dir|-U var|-P pref` are the options to modify the behavior (see the code
+comment of `_comp_compgen` for details).  When there are no `opts`, the
+generator function is supposed to be directly called as `_comp_compgen_NAME
+ARGS`.  The result is stored in the target variable (which is `COMPREPLY` by
+default but can be specified by `-v var` in `OPTS`).
 
 ### Implementing a generator function
 

test/t/unit/test_unit_compgen.py

@@ -172,3 +172,49 @@ def test_9_inherit_a(self, bash, functions):
             bash, "_comp__test_compgen gen9", want_output=True
         )
         assert output.strip() == "<11><11>"
+
+    def test_10_option_P_unmatching_prefix(self, bash, functions):
+        output = assert_bash_exec(
+            bash,
+            "_comp__test_compgen -c 'x' -P 'prefix,' -- -W 'alpha apple beta lemon'",
+            want_output=True,
+        )
+        assert output.strip() == ""
+
+    def test_10_option_P_incomplete_prefix(self, bash, functions):
+        output = assert_bash_exec(
+            bash,
+            "_comp__test_compgen -c 'pre' -P 'prefix,' -- -W 'alpha apple beta lemon'",
+            want_output=True,
+        )
+        assert (
+            output.strip()
+            == "<prefix,alpha><prefix,apple><prefix,beta><prefix,lemon>"
+        )
+
+    def test_10_option_P_exact_prefix(self, bash, functions):
+        output = assert_bash_exec(
+            bash,
+            "_comp__test_compgen -c 'prefix,' -P 'prefix,' -- -W 'alpha apple beta lemon'",
+            want_output=True,
+        )
+        assert (
+            output.strip()
+            == "<prefix,alpha><prefix,apple><prefix,beta><prefix,lemon>"
+        )
+
+    def test_10_option_P_starts_with_prefix(self, bash, functions):
+        output = assert_bash_exec(
+            bash,
+            "_comp__test_compgen -c 'prefix,a' -P 'prefix,' -- -W 'alpha apple beta lemon'",
+            want_output=True,
+        )
+        assert output.strip() == "<prefix,alpha><prefix,apple>"
+
+    def test_10_option_P_no_match(self, bash, functions):
+        output = assert_bash_exec(
+            bash,
+            "_comp__test_compgen -c 'prefix,x' -P 'prefix,' -- -W 'alpha apple beta lemon'",
+            want_output=True,
+        )
+        assert output.strip() == ""