Merge pull request #1022 from scop/refactor/more-api-naming

refactor: more API naming changes

Author: scop

bash_completion

@@ -1241,7 +1241,7 @@ _comp_variable_assignments()
             fi
             ;;
         TERM)
-            _terms
+            _comp_compgen_terms
             ;;
         LANG | LC_*)
             _comp_compgen_split -- "$(locale -a 2>/dev/null)"
@@ -1527,6 +1527,8 @@ _comp_compgen_usage()
 
 # This function completes on signal names (minus the SIG prefix)
 # @param $1 prefix
+#
+# @since 2.12
 _comp_compgen_signals()
 {
     local -a sigs
@@ -1536,6 +1538,7 @@ _comp_compgen_signals()
 
 # This function completes on known mac addresses
 #
+# @since 2.12
 _comp_compgen_mac_addresses()
 {
     local re='\([A-Fa-f0-9]\{2\}:\)\{5\}[A-Fa-f0-9]\{2\}'
@@ -1574,6 +1577,7 @@ _comp_compgen_mac_addresses()
 
 # This function completes on configured network interfaces
 #
+# @since 2.12
 _comp_compgen_configured_interfaces()
 {
     local -a files
@@ -1609,6 +1613,7 @@ _comp_compgen_configured_interfaces()
 # -6: IPv6 addresses only
 # -a: All addresses
 #
+# @since 2.12
 _comp_compgen_ip_addresses()
 {
     local n
@@ -1633,10 +1638,10 @@ _comp_compgen_ip_addresses()
     fi
 }
 
-# This function completes on available kernels
+# This function completes on available kernel versions
 #
-# TODO:API: rename per conventions
-_kernel_versions()
+# @since 2.12
+_comp_compgen_kernel_versions()
 {
     _comp_compgen_split -- "$(command ls /lib/modules)"
 }
@@ -1645,6 +1650,7 @@ _kernel_versions()
 # -a: restrict to active interfaces only
 # -w: restrict to wireless interfaces only
 #
+# @since 2.12
 _comp_compgen_available_interfaces()
 {
     local PATH=$PATH:/sbin
@@ -1750,34 +1756,35 @@ _expand()
 
 # Process ID related functions.
 # for AIX and Solaris we use X/Open syntax, BSD for others.
-# TODO:API: rename per conventions
+#
+# @since 2.12
 if [[ $OSTYPE == *@(solaris|aix)* ]]; then
     # This function completes on process IDs.
-    _pids()
+    _comp_compgen_pids()
     {
         _comp_compgen_split -- "$(command ps -efo pid | command sed 1d)"
     }
 
-    _pgids()
+    _comp_compgen_pgids()
     {
         _comp_compgen_split -- "$(command ps -efo pgid | command sed 1d)"
     }
-    _pnames()
+    _comp_compgen_pnames()
     {
         _comp_compgen_split -X '<defunct>' -- "$(command ps -efo comm |
             command sed -e 1d -e 's:.*/::' -e 's/^-//' | sort -u)"
     }
 else
-    _pids()
+    _comp_compgen_pids()
     {
         _comp_compgen_split -- "$(command ps ax -o pid=)"
     }
-    _pgids()
+    _comp_compgen_pgids()
     {
         _comp_compgen_split -- "$(command ps ax -o pgid=)"
     }
     # @param $1 if -s, don't try to avoid truncated command names
-    _pnames()
+    _comp_compgen_pnames()
     {
         local -a procs=()
         if [[ ${1-} == -s ]]; then
@@ -1829,8 +1836,8 @@ fi
 
 # This function completes on user IDs
 #
-# TODO:API: rename per conventions
-_uids()
+# @since 2.12
+_comp_compgen_uids()
 {
     if type getent &>/dev/null; then
         _comp_compgen_split -- "$(getent passwd | cut -d: -f3)"
@@ -1844,8 +1851,8 @@ _uids()
 
 # This function completes on group IDs
 #
-# TODO:API: rename per conventions
-_gids()
+# @since 2.12
+_comp_compgen_gids()
 {
     if type getent &>/dev/null; then
         _comp_compgen_split -- "$(getent group | cut -d: -f3)"
@@ -1863,8 +1870,8 @@ _comp_backup_glob='@(#*#|*@(~|.@(bak|orig|rej|swp|@(dpkg|ucf)-*|rpm@(orig|new|sa
 
 # Complete on xinetd services
 #
-# TODO:API: rename per conventions
-_xinetd_services()
+# @since 2.12
+_comp_compgen_xinetd_services()
 {
     local xinetddir=${_comp__test_xinetd_dir:-/etc/xinetd.d}
     if [[ -d $xinetddir ]]; then
@@ -1919,7 +1926,7 @@ _service()
 
     if [[ $cword -eq 1 && $prev == ?(*/)service ]]; then
         _services
-        [[ -e /etc/mandrake-release ]] && _xinetd_services
+        [[ -e /etc/mandrake-release ]] && _comp_compgen_xinetd_services
     else
         local sysvdirs
         _comp_sysvdirs
@@ -1943,10 +1950,11 @@ _comp__init_set_up_service_completions()
 }
 _comp__init_set_up_service_completions
 
-# This function completes on modules
+# This function completes on kernel modules
+# @param $1 kernel version
 #
-# TODO:API: rename per conventions (+ include "kernel" in the name)
-_modules()
+# @since 2.12
+_comp_compgen_kernel_modules()
 {
     local modpath
     modpath=/lib/modules/$1
@@ -1955,12 +1963,13 @@ _modules()
             -e 's/^\(.*\)\.ko\.zst$/\1/p')"
 }
 
-# This function completes on installed modules
+# This function completes on inserted kernel modules
+# @param $1 prefix to filter with, default $cur
 #
-# TODO:API: rename per conventions (+ include "kernel" in the name)
-_installed_modules()
+# @since 2.12
+_comp_compgen_inserted_kernel_modules()
 {
-    _comp_compgen -c "$1" split -- "$(PATH="$PATH:/sbin" lsmod |
+    _comp_compgen -c "${1:-$cur}" split -- "$(PATH="$PATH:/sbin" lsmod |
         awk '{if (NR != 1) print $1}')"
 }
 
@@ -1971,8 +1980,9 @@ _installed_modules()
 #
 # @param $1  If -u, only return users/groups the user has access to in
 #            context of current completion.
-# TODO:API: rename per conventions
-_usergroup()
+#
+# @since 2.12
+_comp_compgen_usergroup()
 {
     if [[ $cur == *\\\\* || $cur == *:*:* ]]; then
         # Give up early on if something seems horribly wrong.
@@ -1986,7 +1996,7 @@ _usergroup()
         prefix=${prefix//\\/}
         local mycur=${cur#*[:]}
         if [[ ${1-} == -u ]]; then
-            _allowed_groups "$mycur"
+            _comp_compgen -c "$mycur" allowed_groups
         else
             _comp_compgen -c "$mycur" -- -g
         fi
@@ -1998,7 +2008,7 @@ _usergroup()
         # and only replace the 'gr' part
         local mycur=${cur#*:}
         if [[ ${1-} == -u ]]; then
-            _allowed_groups "$mycur"
+            _comp_compgen -c "$mycur" allowed_groups
         else
             _comp_compgen -c "$mycur" -- -g
         fi
@@ -2009,32 +2019,30 @@ _usergroup()
         # slash. It's better to complete into 'chown username ' than 'chown
         # username\:'.
         if [[ ${1-} == -u ]]; then
-            _allowed_users "$cur"
+            _comp_compgen_allowed_users
         else
             _comp_compgen -- -u
         fi
     fi
 }
 
-# TODO:API: rename per conventions
-_allowed_users()
+# @since 2.12
+_comp_compgen_allowed_users()
 {
-    if _complete_as_root; then
-        _comp_compgen -c "${1:-$cur}" -- -u
+    if _comp_as_root; then
+        _comp_compgen -- -u
     else
-        _comp_compgen -c "${1:-$cur}" split -- "$(id -un 2>/dev/null ||
-            whoami 2>/dev/null)"
+        _comp_compgen split -- "$(id -un 2>/dev/null || whoami 2>/dev/null)"
     fi
 }
 
-# TODO:API: rename per conventions
-_allowed_groups()
+# @since 2.12
+_comp_compgen_allowed_groups()
 {
-    if _complete_as_root; then
-        _comp_compgen -c "$1" -- -g
+    if _comp_as_root; then
+        _comp_compgen -- -g
     else
-        _comp_compgen -c "$1" split -- "$(id -Gn 2>/dev/null ||
-            groups 2>/dev/null)"
+        _comp_compgen split -- "$(id -Gn 2>/dev/null || groups 2>/dev/null)"
     fi
 }
 
@@ -2059,8 +2067,8 @@ _shells()
 
 # This function completes on valid filesystem types
 #
-# TODO:API: rename per conventions
-_fstypes()
+# @since 2.12
+_comp_compgen_fstypes()
 {
     local fss
 
@@ -2078,7 +2086,7 @@ _fstypes()
              $([[ -d /etc/fs ]] && command ls /etc/fs)"
     fi
 
-    [[ $fss ]] && _comp_compgen -a -- -W "$fss"
+    [[ $fss ]] && _comp_compgen -- -W "$fss"
 }
 
 # Get absolute path to a file, with rudimentary canonicalization.
@@ -2164,38 +2172,40 @@ _count_args()
 
 # This function completes on PCI IDs
 #
-# TODO:API: rename per conventions
-_pci_ids()
+# @since 2.12
+_comp_compgen_pci_ids()
 {
-    _comp_compgen -a split -- "$(PATH="$PATH:/sbin" lspci -n |
-        awk '{print $3}')"
+    _comp_compgen_split -- "$(PATH="$PATH:/sbin" lspci -n | awk '{print $3}')"
 }
 
 # This function completes on USB IDs
 #
-# TODO:API: rename per conventions
-_usb_ids()
+# @since 2.12
+_comp_compgen_usb_ids()
 {
-    _comp_compgen -a split -- "$(PATH="$PATH:/sbin" lsusb | awk '{print $6}')"
+    _comp_compgen_split -- "$(PATH="$PATH:/sbin" lsusb | awk '{print $6}')"
 }
 
 # CD device names
-# TODO:API: rename per conventions
-_cd_devices()
+#
+# @since 2.12
+_comp_compgen_cd_devices()
 {
-    _comp_compgen -ac "${cur:-/dev/}" -- -f -d -X "!*/?([amrs])cd*"
+    _comp_compgen -c "${cur:-/dev/}" -- -f -d -X "!*/?([amrs])cd*"
 }
 
 # DVD device names
-# TODO:API: rename per conventions
-_dvd_devices()
+#
+# @since 2.12
+_comp_compgen_dvd_devices()
 {
-    _comp_compgen -ac "${cur:-/dev/}" -- -f -d -X "!*/?(r)dvd*"
+    _comp_compgen -c "${cur:-/dev/}" -- -f -d -X "!*/?(r)dvd*"
 }
 
 # TERM environment variable values
-# TODO:API: rename per conventions
-_terms()
+#
+# @since 2.12
+_comp_compgen_terms()
 {
     _comp_compgen -a split -- "$({
         command sed -ne 's/^\([^[:space:]#|]\{2,\}\)|.*/\1/p' /etc/termcap
@@ -2724,8 +2734,9 @@ _comp_root_command()
 complete -F _comp_root_command fakeroot gksu gksudo kdesudo really
 
 # Return true if the completion should be treated as running as root
-# TODO:API: rename per conventions
-_complete_as_root()
+#
+# @since 2.12
+_comp_as_root()
 {
     [[ $EUID -eq 0 || ${root_command-} ]]
 }