feat(bash_completion): add a utility _comp_xfunc

Co-authored-by: Ville Skyttä <[email protected]>

Author: akinomyoga

bash_completion

@@ -2426,6 +2426,22 @@ _completion_loader()
 } &&
     complete -D -F _completion_loader
 
+# Function for loading and calling functions from dynamically loaded
+# completion files that may not have been sourced yet.
+# @param $1 completion file to load function from in case it is missing
+# @param $2 the xfunc name.  When it does not start with `_',
+#   `_comp_xfunc_${1//[^a-zA-Z0-9_]/_}_$2' is used for the actual name of the
+#   shell function.
+# @param $3... if any, specifies the arguments that are passed to the xfunc.
+_comp_xfunc()
+{
+    local xfunc_name=$2
+    [[ $xfunc_name == _* ]] ||
+        xfunc_name=_comp_xfunc_${1//[^a-zA-Z0-9_]/_}_$xfunc_name
+    declare -F "$xfunc_name" &>/dev/null || __load_completion "$1"
+    "$xfunc_name" "${@:3}"
+}
+
 # Function for loading and calling functions from dynamically loaded
 # completion files that may not have been sourced yet.
 # @param $1 completion file to load function from in case it is missing

test/fixtures/_comp_xfunc/completions/xfunc-test1

@@ -0,0 +1,12 @@
+# Dummy completion file for _comp_xfunc tests              -*- shell-script -*-
+
+if declare -F _comp_xfunc_xfunc_test1_utility1 &>/dev/null; then
+  echo "_comp_xfunc_xfunc_test1_utility1 is already defined"
+  return 1
+fi
+
+_comp_xfunc_xfunc_test1_utility1() {
+  printf 'util1['
+  printf '<%s>' "$@"
+  printf ']\n'
+}

test/fixtures/_comp_xfunc/completions/xfunc-test2

@@ -0,0 +1,12 @@
+# Dummy completion file for _comp_xfunc tests              -*- shell-script -*-
+
+if declare -F _comp_xfunc_non_standard_name &>/dev/null; then
+  echo "_comp_xfunc_non_standard_name is already defined"
+  return 1
+fi
+
+_comp_xfunc_non_standard_name() {
+  printf 'util2['
+  printf '<%s>' "$@"
+  printf ']\n'
+}

test/t/conftest.py

@@ -267,7 +267,7 @@ def bash(request) -> pexpect.spawn:
             # FIXME: Tests shouldn't depend on dimensions, but it's difficult to
             # expect robustly enough for Bash to wrap lines anywhere (e.g. inside
             # MAGIC_MARK).  Increase window width to reduce wrapping.
-            dimensions=(24, 160),
+            dimensions=(24, 200),
             # TODO? codec_errors="replace",
         )
         bash.expect_exact(PS1)

test/t/unit/test_unit_xfunc.py

@@ -0,0 +1,71 @@
+import pytest
+
+from conftest import assert_bash_exec, bash_env_saved
+
+
+@pytest.mark.bashcomp(cmd=None)
+class TestUnitXfunc:
+    def test_1(self, bash):
+        with bash_env_saved(bash) as bash_env:
+            bash_env.write_variable(
+                "BASH_COMPLETION_USER_DIR", "$PWD/_comp_xfunc", quote=False
+            )
+
+            # test precondition
+            assert_bash_exec(
+                bash,
+                "! declare -F _comp_xfunc_xfunc_test1_utility1 &>/dev/null",
+            )
+
+            # first invocation (completion/xfunc-test1 is sourced)
+            output = assert_bash_exec(
+                bash,
+                "_comp_xfunc xfunc-test1 utility1 'a b' cde fgh",
+                want_output=True,
+            )
+            assert output.strip() == "util1[<a b><cde><fgh>]"
+
+            # test precondition
+            assert_bash_exec(
+                bash, "declare -F _comp_xfunc_xfunc_test1_utility1 &>/dev/null"
+            )
+
+            # second invocation (completion/xfunc-test1 is not sourced)
+            output = assert_bash_exec(
+                bash,
+                "_comp_xfunc xfunc-test1 utility1 'a b' cde fgh",
+                want_output=True,
+            )
+            assert output.strip() == "util1[<a b><cde><fgh>]"
+
+    def test_2(self, bash):
+        with bash_env_saved(bash) as bash_env:
+            bash_env.write_variable(
+                "BASH_COMPLETION_USER_DIR", "$PWD/_comp_xfunc", quote=False
+            )
+
+            # test precondition
+            assert_bash_exec(
+                bash, "! declare -F _comp_xfunc_non_standard_name &>/dev/null"
+            )
+
+            # first invocation (completion/xfunc-test2 is sourced)
+            output = assert_bash_exec(
+                bash,
+                "_comp_xfunc xfunc-test2 _comp_xfunc_non_standard_name 'a b' cde fgh",
+                want_output=True,
+            )
+            assert output.strip() == "util2[<a b><cde><fgh>]"
+
+            # test precondition
+            assert_bash_exec(
+                bash, "declare -F _comp_xfunc_non_standard_name &>/dev/null"
+            )
+
+            # second invocation (completion/xfunc-test2 is not sourced)
+            output = assert_bash_exec(
+                bash,
+                "_comp_xfunc xfunc-test2 _comp_xfunc_non_standard_name 'a b' cde fgh",
+                want_output=True,
+            )
+            assert output.strip() == "util2[<a b><cde><fgh>]"