GNU Info

(bashref.info)Programmable Completion

---

Next: Programmable Completion Builtins Prev: Readline vi Mode Up: Command Line Editing

---

Enter node , (file) or (file)node

Programmable Completion
=======================

   When word completion is attempted for an argument to a command for
which a completion specification (a COMPSPEC) has been defined using
the `complete' builtin (Note: Programmable Completion Builtins), the
programmable completion facilities are invoked.

   First, the command name is identified.  If a compspec has been
defined for that command, the compspec is used to generate the list of
possible completions for the word.  If the command word is a full
pathname, a compspec for the full pathname is searched for first.  If
no compspec is found for the full pathname, an attempt is made to find
a compspec for the portion following the final slash.

   Once a compspec has been found, it is used to generate the list of
matching words.  If a compspec is not found, the default Bash completion
described above (Note: Commands For Completion) is performed.

   First, the actions specified by the compspec are used.  Only matches
which are prefixed by the word being completed are returned.  When the
`-f' or `-d' option is used for filename or directory name completion,
the shell variable `FIGNORE' is used to filter the matches.  Note: Bash
Variables, for a description of `FIGNORE'.

   Any completions specified by a filename expansion pattern to the
`-G' option are generated next.  The words generated by the pattern
need not match the word being completed.  The `GLOBIGNORE' shell
variable is not used to filter the matches, but the `FIGNORE' shell
variable is used.

   Next, the string specified as the argument to the `-W' option is
considered.  The string is first split using the characters in the `IFS'
special variable as delimiters.  Shell quoting is honored.  Each word
is then expanded using brace expansion, tilde expansion, parameter and
variable expansion, command substitution, arithmetic expansion, and
pathname expansion, as described above (Note: Shell Expansions).  The
results are split using the rules described above (Note: Word
Splitting).  The results of the expansion are prefix-matched against
the word being completed, and the matching words become the possible
completions.

   After these matches have been generated, any shell function or
command specified with the `-F' and `-C' options is invoked.  When the
command or function is invoked, the `COMP_LINE' and `COMP_POINT'
variables are assigned values as described above (Note: Bash
Variables).  If a shell function is being invoked, the `COMP_WORDS'
and `COMP_CWORD' variables are also set.  When the function or command
is invoked, the first argument is the name of the command whose
arguments are being completed, the second argument is the word being
completed, and the third argument is the word preceding the word being
completed on the current command line.  No filtering of the generated
completions against the word being completed is performed; the function
or command has complete freedom in generating the matches.

   Any function specified with `-F' is invoked first.  The function may
use any of the shell facilities, including the `compgen' builtin
described below (Note: Programmable Completion Builtins), to generate
the matches.  It must put the possible completions in the `COMPREPLY'
array variable.

   Next, any command specified with the `-C' option is invoked in an
environment equivalent to command substitution.  It should print a list
of completions, one per line, to the standard output.  Backslash may be
used to escape a newline, if necessary.

   After all of the possible completions are generated, any filter
specified with the `-X' option is applied to the list.  The filter is a
pattern as used for pathname expansion; a `&' in the pattern is
replaced with the text of the word being completed.  A literal `&' may
be escaped with a backslash; the backslash is removed before attempting
a match.  Any completion that matches the pattern will be removed from
the list.  A leading `!' negates the pattern; in this case any
completion not matching the pattern will be removed.

   Finally, any prefix and suffix specified with the `-P' and `-S'
options are added to each member of the completion list, and the result
is returned to the Readline completion code as the list of possible
completions.

   If the previously-applied actions do not generate any matches, and
the `-o dirnames' option was supplied to `complete' when the compspec
was defined, directory name completion is attempted.

   By default, if a compspec is found, whatever it generates is
returned to the completion code as the full set of possible completions.
The default Bash completions are not attempted, and the Readline default
of filename completion is disabled.  If the `-o default' option was
supplied to `complete' when the compspec was defined, Readline's
default completion will be performed if the compspec generates no
matches.