refactor: rename completion functions

bash_completion

@@ -1961,8 +1961,8 @@ _comp_compgen_services()
 # one, because we set it up eagerly as completer for scripts in sysv init dirs
 # below.
 #
-# TODO:API: rename per conventions, rework to use vars rather than outputting
-_service()
+# @since 2.12
+_comp_complete_service()
 {
     local cur prev words cword comp_args
     _comp_initialize -- "$@" || return
@@ -1981,7 +1981,7 @@ _service()
             "${sysvdirs[0]}/${prev##*/}" 2>/dev/null) start stop"
     fi
 } &&
-    complete -F _service service
+    complete -F _comp_complete_service service
 
 _comp__init_set_up_service_completions()
 {
@@ -1990,7 +1990,7 @@ _comp__init_set_up_service_completions()
         for svcdir in "${sysvdirs[@]}"; do
             _comp_expand_glob svcs '"$svcdir"/!($_comp_backup_glob)'
             for svc in "${svcs[@]}"; do
-                [[ -x $svc ]] && complete -F _service "$svc"
+                [[ -x $svc ]] && complete -F _comp_complete_service "$svc"
             done
         done
     unset -f "$FUNCNAME"
@@ -2353,8 +2353,8 @@ _comp_try_faketty()
 
 # This function provides simple user@host completion
 #
-# TODO:API: rename per conventions
-_user_at_host()
+# @since 2.12
+_comp_complete_user_at_host()
 {
     local cur prev words cword comp_args
     _comp_initialize -n : -- "$@" || return
@@ -2366,19 +2366,19 @@ _user_at_host()
         compopt -o nospace
     fi
 }
-shopt -u hostcomplete && complete -F _user_at_host talk ytalk finger
+shopt -u hostcomplete && complete -F _comp_complete_user_at_host talk ytalk finger
 
 # NOTE: Using this function as a helper function is deprecated.  Use
 #       `_comp_compgen_known_hosts' instead.
-# TODO:API: rename per conventions
-_known_hosts()
+# @since 2.12
+_comp_complete_known_hosts()
 {
     local cur prev words cword comp_args
     _comp_initialize -n : -- "$@" || return
 
-    # NOTE: Using `_known_hosts' as a helper function and passing options to
-    #       `_known_hosts' is deprecated: Use `_comp_compgen_known_hosts'
-    #       instead.
+    # NOTE: Using `_known_hosts' (the old name of `_comp_complete_known_hosts')
+    #       as a helper function and passing options to `_known_hosts' is
+    #       deprecated: Use `_comp_compgen_known_hosts' instead.
     local -a options=()
     [[ ${1-} == -a || ${2-} == -a ]] && options+=(-a)
     [[ ${1-} == -c || ${2-} == -c ]] && options+=(-c)
@@ -2440,7 +2440,7 @@ _comp__included_ssh_config_files()
     done
 }
 
-# Helper function for completing _known_hosts.
+# Helper function for completing _comp_complete_known_hosts.
 # This function performs host completion based on ssh's config and known_hosts
 # files, as well as hostnames reported by avahi-browse if
 # BASH_COMPLETION_KNOWN_HOSTS_WITH_AVAHI is set to a non-empty value.
@@ -2663,7 +2663,7 @@ _comp_compgen_known_hosts__impl()
 
     _comp_compgen -v known_hosts -c "$prefix$cur" ltrim_colon "${known_hosts[@]}"
 }
-complete -F _known_hosts traceroute traceroute6 \
+complete -F _comp_complete_known_hosts traceroute traceroute6 \
     fping fping6 telnet rsh rlogin ftp dig drill mtr ssh-installkeys showmount
 
 # Convert the word index in `words` to the index in `COMP_WORDS`.
@@ -2761,7 +2761,7 @@ _comp_command_offset()
                 if ((${#COMPREPLY[@]} == 0)); then
                     # XXX will probably never happen as long as completion loader loads
                     #     *something* for every command thrown at it ($cspec != empty)
-                    _minimal "${args[@]}"
+                    _comp_complete_minimal "${args[@]}"
                 fi
             elif [[ $cspec == *' -F '* ]]; then
                 # complete -F <function>
@@ -2865,7 +2865,7 @@ _comp_compgen_commands()
 }
 
 # @since 2.12
-_comp_longopt()
+_comp_complete_longopt()
 {
     local cur prev words cword was_split comp_args
     _comp_initialize -s -- "$@" || return
@@ -2915,7 +2915,7 @@ _comp_longopt()
     fi
 }
 # makeinfo and texi2dvi are defined elsewhere.
-complete -F _comp_longopt \
+complete -F _comp_complete_longopt \
     a2ps awk base64 bash bc bison cat chroot colordiff cp \
     csplit cut date df diff dir du enscript env expand fmt fold gperf \
     grep grub head irb ld ldd less ln ls m4 mkdir mkfifo mknod \
@@ -2926,12 +2926,17 @@ complete -F _comp_longopt \
 # @since 2.12
 declare -Ag _comp_xspecs
 
-# TODO:API: rename per conventions
-_filedir_xspec()
+# @since 2.12
+_comp_complete_filedir_xspec()
 {
     local cur prev words cword comp_args
     _comp_initialize -- "$@" || return
+    _comp_compgen_filedir_xspec "$1"
+}
 
+# @since 2.12
+_comp_compgen_filedir_xspec()
+{
     _comp_compgen_tilde && return
 
     local ret
@@ -2960,10 +2965,10 @@ _filedir_xspec()
         ${#toks[@]} -lt 1 ]] &&
         _comp_compgen -av toks -c "$quoted" -- -f
 
-    if ((${#toks[@]} != 0)); then
-        compopt -o filenames
-        COMPREPLY=("${toks[@]}")
-    fi
+    ((${#toks[@]})) || return 1
+
+    compopt -o filenames
+    _comp_compgen -RU toks -- -W '"${toks[@]}"'
 }
 
 _comp__init_install_xspec()
@@ -3035,15 +3040,15 @@ unset -f _comp__init_install_xspec
 
 # Minimal completion to use as fallback in _comp_complete_load.
 # TODO:API: rename per conventions
-_minimal()
+_comp_complete_minimal()
 {
     local cur prev words cword comp_args
     _comp_initialize -- "$@" || return
     compopt -o bashdefault -o default
 }
 # Complete the empty string to allow completion of '>', '>>', and '<' on < 4.3
 # https://lists.gnu.org/archive/html/bug-bash/2012-01/msg00045.html
-complete -F _minimal ''
+complete -F _comp_complete_minimal ''
 
 # @since 2.12
 _comp_load()
@@ -3168,10 +3173,10 @@ _comp_load()
 
     # Look up simple "xspec" completions
     [[ -v _comp_xspecs[$cmdname] || -v _xspecs[$cmdname] ]] &&
-        complete -F _filedir_xspec "$cmdname" "$backslash$cmdname" && return 0
+        complete -F _comp_complete_filedir_xspec "$cmdname" "$backslash$cmdname" && return 0
 
     if [[ $flag_fallback_default ]]; then
-        complete -F _minimal -- "$origcmd" && return 0
+        complete -F _comp_complete_minimal -- "$origcmd" && return 0
     fi
 
     return 1

bash_completion.d/000_bash_completion_compat.bash

@@ -11,7 +11,6 @@ _comp_deprecate_func 2.12 _xfunc _comp_xfunc
 _comp_deprecate_func 2.12 _upvars _comp_upvars
 _comp_deprecate_func 2.12 _get_comp_words_by_ref _comp_get_words
 _comp_deprecate_func 2.12 _known_hosts_real _comp_compgen_known_hosts
-_comp_deprecate_func 2.12 _longopt _comp_longopt
 _comp_deprecate_func 2.12 __ltrim_colon_completions _comp_ltrim_colon_completions
 _comp_deprecate_func 2.12 _variables _comp_compgen_variables
 _comp_deprecate_func 2.12 _signals _comp_compgen_signals
@@ -35,6 +34,14 @@ _comp_deprecate_func 2.12 _usergroup _comp_compgen_usergroups
 _comp_deprecate_func 2.12 _complete_as_root _comp_as_root
 _comp_deprecate_func 2.12 __load_completion _comp_load
 
+# completers
+_comp_deprecate_func 2.12 _service _comp_complete_service
+_comp_deprecate_func 2.12 _user_at_host _comp_complete_user_at_host
+_comp_deprecate_func 2.12 _known_hosts _comp_complete_known_hosts
+_comp_deprecate_func 2.12 _longopt _comp_complete_longopt
+_comp_deprecate_func 2.12 _filedir_xspec _comp_complete_filedir_xspec
+_comp_deprecate_func 2.12 _minimal _comp_complete_minimal
+
 # @deprecated 2.12 Use `_comp_xspecs`
 declare -Ag _xspecs
 

completions/7z

@@ -87,7 +87,7 @@ _comp_cmd_7z()
     local ret
     _comp_count_args
     if ((ret == 2)); then
-        _filedir_xspec unzip "${@:2}"
+        _comp_compgen_filedir_xspec unzip
         # TODO: parsing 7z i output?
         # - how to figure out if the format is input or output?
         # - find string Formats:, read until next empty line

completions/abook

@@ -15,7 +15,7 @@ _comp_cmd_abook()
 
     case $cur in
         -*)
-            _comp_longopt "$@"
+            _comp_complete_longopt "$@"
             return
             ;;
     esac

completions/file-roller

@@ -18,7 +18,7 @@ _comp_cmd_file_roller()
             return
             ;;
         --add-to | -${noargopts}a)
-            _filedir_xspec unzip "${@:2}"
+            _comp_compgen_filedir_xspec unzip
             _comp_compgen -a filedir "$exts"
             return
             ;;
@@ -36,7 +36,7 @@ _comp_cmd_file_roller()
         return
     fi
 
-    _filedir_xspec unzip "${@:2}"
+    _comp_compgen_filedir_xspec unzip
     _comp_compgen -a filedir "$exts"
 } &&
     complete -F _comp_cmd_file_roller file-roller

completions/gcc

@@ -65,7 +65,7 @@ _comp_cmd_gcc()
             "$1" --version 2>/dev/null | command grep -q GCC; then
             complete -F _comp_cmd_gcc "$1"
         else
-            complete -F _minimal "$1"
+            complete -F _comp_complete_minimal "$1"
         fi
     } &&
         _comp_cmd_gcc__setup_cmd cc gcc &&

completions/jar

@@ -15,7 +15,7 @@ _comp_cmd_jar()
             _comp_compgen_filedir
             ;;
         *f)
-            _filedir_xspec unzip "${@:2}"
+            _comp_compgen_filedir_xspec unzip
             ;;
         *)
             _comp_compgen_filedir

completions/makepkg

@@ -33,7 +33,7 @@ _comp_cmd_makepkg__bootstrap()
             fname=_comp_cmd_makepkg__slackware
             ;;
         *)
-            fname=_minimal
+            fname=_comp_complete_minimal
             ;;
     esac
 

completions/mussh

@@ -34,7 +34,7 @@ _comp_cmd_mussh()
             return
             ;;
         -p | -h)
-            [[ $cur == *@* ]] && _user_at_host "$@" || _comp_compgen_known_hosts -a -- "$cur"
+            [[ $cur == *@* ]] && _comp_complete_user_at_host "$@" || _comp_compgen_known_hosts -a -- "$cur"
             return
             ;;
         -c)

completions/pyvenv

@@ -14,7 +14,7 @@ _comp_cmd_pyvenv()
     [[ $was_split ]] && return
 
     if [[ $cur == -* ]]; then
-        _comp_longopt "$@"
+        _comp_complete_longopt "$@"
         return
     fi
 

completions/sha256sum

@@ -14,7 +14,7 @@ _comp_cmd_sha256sum()
     [[ $was_split ]] && return
 
     if [[ $cur == -* ]]; then
-        _comp_longopt "$@"
+        _comp_complete_longopt "$@"
         return
     fi
 

completions/vncviewer

@@ -7,7 +7,7 @@ _comp_cmd_vncviewer__bootstrap()
     case $ret in
         *xvnc4viewer) fname=_comp_cmd_xvnc4viewer ;;
         *tightvncviewer) fname=_comp_cmd_tightvncviewer ;;
-        *) fname=_known_hosts ;;
+        *) fname=_comp_complete_known_hosts ;;
     esac
 
     # Install real completion for subsequent completions

doc/api-and-naming.md

@@ -41,17 +41,17 @@ deprecated in.
 Due to its nature, bash-completion adds a number of functions and variables in
 the shell's environment.
 
-|                                     | `bash_completion`       | `completions/*`                                                                       |
-|:------------------------------------|:------------------------|:--------------------------------------------------------------------------------------|
-| public configuration variables      | `BASH_COMPLETION_*`     | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}`                                        |
-| private non-local variables         | `_comp__*`              | `_comp_cmd_${Command}__${Data}`                                                       |
-| private non-local mutable variables | `_comp__*_mut_*`        | `_comp_cmd_${Command}__mut_${Data}`                                                   |
-| exporter function local variables   | `_*` (not `_comp*`)     | `_*` (not `_comp*`)                                                                   |
-| public/exported functions           | `_comp_*`               | `_comp_cmd_${Command}` (functions for `complete -F`)                                  |
-|                                     |                         | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`)            |
-|                                     | `_comp_compgen_${Name}` | `_comp_xfunc_${Command}_compgen_${Name}` (generators for use with `_comp_compgen -x`) |
-| private/internal functions          | `_comp__*`              | `_comp_cmd_${Command}__${Utility}` (utility functions)                                |
-|                                     |                         | `_comp_cmd_${Command}__compgen_${Name}` (generators for use with `_comp_compgen -i`)  |
+|                                     | `bash_completion`   | `completions/*`                                                                       |
+|:------------------------------------|:--------------------|:--------------------------------------------------------------------------------------|
+| public configuration variables      | `BASH_COMPLETION_*` | `BASH_COMPLETION_CMD_${Command^^}_${Config^^}`                                        |
+| private non-local variables         | `_comp__*`          | `_comp_cmd_${Command}__${Data}`                                                       |
+| private non-local mutable variables | `_comp__*_mut_*`    | `_comp_cmd_${Command}__mut_${Data}`                                                   |
+| exporter function local variables   | `_*` (not `_comp*`) | `_*` (not `_comp*`)                                                                   |
+| public/exported functions           | `_comp_*`           | `_comp_xfunc_${Command}_${Utility}` (functions for use with `_comp_xfunc`)            |
+| - completers (for `complete -F`)    | `_comp_complete_*`  | `_comp_cmd_${Command}`                                                                |
+| - generators                        | `_comp_compgen_*`   | `_comp_xfunc_${Command}_compgen_${Name}` (generators for use with `_comp_compgen -x`) |
+| private/internal functions          | `_comp__*`          | `_comp_cmd_${Command}__${Utility}` (utility functions)                                |
+| - generators                        |                     | `_comp_cmd_${Command}__compgen_${Name}` (generators for use with `_comp_compgen -i`)  |
 
 `${Command}` refers to a command name (with characters not allowed in POSIX
 function or variable names replaced by an underscore), `${Config}` the name of

test/t/test_grep.py

@@ -11,7 +11,7 @@ def test_2(self, completion):
         """
         Test --no-*dir isn't restricted to dirs only.
 
-        Not really a grep option, but tests _comp_longopt.
+        Not really a grep option, but tests _comp_complete_longopt.
         """
         assert completion == "foo foo.d/".split()
 

test/t/unit/test_unit_longopt.py

@@ -10,9 +10,9 @@ class TestUnitLongopt:
     @pytest.fixture(scope="class")
     def functions(self, request, bash):
         assert_bash_exec(bash, "_grephelp() { cat _longopt/grep--help.txt; }")
-        assert_bash_exec(bash, "complete -F _comp_longopt _grephelp")
+        assert_bash_exec(bash, "complete -F _comp_complete_longopt _grephelp")
         assert_bash_exec(bash, "_various() { cat _longopt/various.txt; }")
-        assert_bash_exec(bash, "complete -F _comp_longopt _various")
+        assert_bash_exec(bash, "complete -F _comp_complete_longopt _various")
 
     @pytest.mark.complete("_grephelp --")
     def test_1(self, functions, completion):