Where can I find documentation for _get_comp_words_by_ref function used in autocompletion scripts?

Question

I am trying to write tests for a bash completion script that was contributed by a user of a tool I am developing (so that I can keep it up to date with the tool itself) and I am wondering what _get_comp_words_by_ref exactly does.

Sample:

local cur prev
if type _get_comp_words_by_ref &>/dev/null ; then
    _get_comp_words_by_ref cur prev
else
    cur=$2 prev=$3
fi

Camelliacamelopard

See: type _get_comp_words_by_ref – Marable

Answer 1

It's part of the bash-completions package, which might be installed in the directory /usr/share/bash-completion (although the precise path depends on the distro).

You may find the documentation in the top-level file bash-completion, which contains a number of utility functions.

Gallery

Answer 2

Unfortunately it appears that these functions are getting deprecated and are no longer in the current version of bash_completion the functions and documentation still exist in an old commit here: https://github.com/scop/bash-completion/blob/1.x/bash_completion#L374

From the docs:

# Get the word to complete and optional previous words.
# This is nicer than ${COMP_WORDS[$COMP_CWORD]}, since it handles cases
# where the user is completing in the middle of a word.
# (For example, if the line is "ls foobar",
# and the cursor is here -------->   ^
# Also one is able to cross over possible wordbreak characters.
# Usage: _get_comp_words_by_ref [OPTIONS] [VARNAMES]
# Available VARNAMES:
#     cur         Return cur via $cur
#     prev        Return prev via $prev
#     words       Return words via $words
#     cword       Return cword via $cword
#
# Available OPTIONS:
#     -n EXCLUDE  Characters out of $COMP_WORDBREAKS which should NOT be 
#                 considered word breaks. This is useful for things like scp
#                 where we want to return host:path and not only path, so we
#                 would pass the colon (:) as -n option in this case.  Bash-3
#                 doesn't do word splitting, so this ensures we get the same
#                 word on both bash-3 and bash-4.
#     -c VARNAME  Return cur via $VARNAME
#     -p VARNAME  Return prev via $VARNAME
#     -w VARNAME  Return words via $VARNAME
#     -i VARNAME  Return cword via $VARNAME
#
# Example usage:
#
#    $ _get_comp_words_by_ref -n : cur prev
#
_get_comp_words_by_ref()

Noachian