+
+@ifset BashFeatures
+@node Programmable Completion
+@section Programmable Completion
+@cindex programmable completion
+
+When word completion is attempted for an argument to a command for
+which a completion specification (a @var{compspec}) has been defined
+using the @code{complete} builtin (@pxref{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 (@pxref{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 @option{-f} or @option{-d} option is used for filename or
+directory name completion, the shell variable @env{FIGNORE} is
+used to filter the matches.
+@xref{Bash Variables}, for a description of @env{FIGNORE}.
+
+Any completions specified by a filename expansion pattern to the
+@option{-G} option are generated next.
+The words generated by the pattern need not match the word being completed.
+The @env{GLOBIGNORE} shell variable is not used to filter the matches,
+but the @env{FIGNORE} shell variable is used.
+
+Next, the string specified as the argument to the @option{-W} option
+is considered.
+The string is first split using the characters in the @env{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 (@pxref{Shell Expansions}).
+The results are split using the rules described above
+(@pxref{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 @option{-F} and @option{-C} options is invoked.
+When the command or function is invoked, the @env{COMP_LINE} and
+@env{COMP_POINT} variables are assigned values as described above
+(@pxref{Bash Variables}).
+If a shell function is being invoked, the @env{COMP_WORDS} and
+@env{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 @option{-F} is invoked first.
+The function may use any of the shell facilities, including the
+@code{compgen} builtin described below
+(@pxref{Programmable Completion Builtins}), to generate the matches.
+It must put the possible completions in the @env{COMPREPLY} array
+variable.
+
+Next, any command specified with the @option{-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 @option{-X} option is applied to the list.
+The filter is a pattern as used for pathname expansion; a @samp{&}
+in the pattern is replaced with the text of the word being completed.
+A literal @samp{&} 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 @samp{!} negates the pattern; in this case any completion
+not matching the pattern will be removed.
+
+Finally, any prefix and suffix specified with the @option{-P} and @option{-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
+@option{-o dirnames} option was supplied to @code{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 @option{-o default} option was supplied to @code{complete} when the
+compspec was defined, Readline's default completion will be performed
+if the compspec generates no matches.
+
+When a compspec indicates that directory name completion is desired,
+the programmable completion functions force Readline to append a slash
+to completed names which are symbolic links to directories, subject to
+the value of the @var{mark-directories} Readline variable, regardless
+of the setting of the @var{mark-symlinked-directories} Readline variable.
+
+@node Programmable Completion Builtins
+@section Programmable Completion Builtins
+@cindex completion builtins
+
+Two builtin commands are available to manipulate the programmable completion
+facilities.
+
+@table @code
+@item compgen
+@btindex compgen
+@example
+@code{compgen [@var{option}] [@var{word}]}
+@end example
+
+Generate possible completion matches for @var{word} according to
+the @var{option}s, which may be any option accepted by the
+@code{complete}
+builtin with the exception of @option{-p} and @option{-r}, and write
+the matches to the standard output.
+When using the @option{-F} or @option{-C} options, the various shell variables
+set by the programmable completion facilities, while available, will not
+have useful values.
+
+The matches will be generated in the same way as if the programmable
+completion code had generated them directly from a completion specification
+with the same flags.
+If @var{word} is specified, only those completions matching @var{word}
+will be displayed.
+
+The return value is true unless an invalid option is supplied, or no
+matches were generated.
+
+@item complete
+@btindex complete
+@example
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
+[-P @var{prefix}] [-S @var{suffix}] [-X @var{filterpat}] [-F @var{function}]
+[-C @var{command}] @var{name} [@var{name} @dots{}]}
+@code{complete -pr [@var{name} @dots{}]}
+@end example
+
+Specify how arguments to each @var{name} should be completed.
+If the @option{-p} option is supplied, or if no options are supplied, existing
+completion specifications are printed in a way that allows them to be
+reused as input.
+The @option{-r} option removes a completion specification for
+each @var{name}, or, if no @var{name}s are supplied, all
+completion specifications.
+
+The process of applying these completion specifications when word completion
+is attempted is described above (@pxref{Programmable Completion}).
+
+Other options, if specified, have the following meanings.
+The arguments to the @option{-G}, @option{-W}, and @option{-X} options
+(and, if necessary, the @option{-P} and @option{-S} options)
+should be quoted to protect them from expansion before the
+@code{complete} builtin is invoked.
+
+
+@table @code
+@item -o @var{comp-option}
+The @var{comp-option} controls several aspects of the compspec's behavior
+beyond the simple generation of completions.
+@var{comp-option} may be one of:
+
+@table @code
+
+@item default
+Use Readline's default filename completion if the compspec generates
+no matches.
+
+@item dirnames
+Perform directory name completion if the compspec generates no matches.
+
+@item filenames
+Tell Readline that the compspec generates filenames, so it can perform any
+filename\-specific processing (like adding a slash to directory names or
+suppressing trailing spaces). This option is intended to be used with
+shell functions specified with @option{-F}.
+
+@item nospace
+Tell Readline not to append a space (the default) to words completed at
+the end of the line.
+@end table
+
+@item -A @var{action}
+The @var{action} may be one of the following to generate a list of possible
+completions:
+
+@table @code
+@item alias
+Alias names. May also be specified as @option{-a}.
+
+@item arrayvar
+Array variable names.
+
+@item binding
+Readline key binding names (@pxref{Bindable Readline Commands}).
+
+@item builtin
+Names of shell builtin commands. May also be specified as @option{-b}.
+
+@item command
+Command names. May also be specified as @option{-c}.
+
+@item directory
+Directory names. May also be specified as @option{-d}.
+
+@item disabled
+Names of disabled shell builtins.
+
+@item enabled
+Names of enabled shell builtins.
+
+@item export
+Names of exported shell variables. May also be specified as @option{-e}.
+
+@item file
+File names. May also be specified as @option{-f}.
+
+@item function
+Names of shell functions.
+
+@item group
+Group names. May also be specified as @option{-g}.
+
+@item helptopic
+Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
+
+@item hostname
+Hostnames, as taken from the file specified by the
+@env{HOSTFILE} shell variable (@pxref{Bash Variables}).
+
+@item job
+Job names, if job control is active. May also be specified as @option{-j}.
+
+@item keyword
+Shell reserved words. May also be specified as @option{-k}.
+
+@item running
+Names of running jobs, if job control is active.
+
+@item service
+Service names. May also be specified as @option{-s}.
+
+@item setopt
+Valid arguments for the @option{-o} option to the @code{set} builtin
+(@pxref{The Set Builtin}).
+
+@item shopt
+Shell option names as accepted by the @code{shopt} builtin
+(@pxref{Bash Builtins}).
+
+@item signal
+Signal names.
+
+@item stopped
+Names of stopped jobs, if job control is active.
+
+@item user
+User names. May also be specified as @option{-u}.
+
+@item variable
+Names of all shell variables. May also be specified as @option{-v}.
+@end table
+
+@item -G @var{globpat}
+The filename expansion pattern @var{globpat} is expanded to generate
+the possible completions.
+
+@item -W @var{wordlist}
+The @var{wordlist} is split using the characters in the
+@env{IFS} special variable as delimiters, and each resultant word
+is expanded.
+The possible completions are the members of the resultant list which
+match the word being completed.
+
+@item -C @var{command}
+@var{command} is executed in a subshell environment, and its output is
+used as the possible completions.
+
+@item -F @var{function}
+The shell function @var{function} is executed in the current shell
+environment.
+When it finishes, the possible completions are retrieved from the value
+of the @env{COMPREPLY} array variable.
+
+@item -X @var{filterpat}
+@var{filterpat} is a pattern as used for filename expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+@var{filterpat} is removed from the list.
+A leading @samp{!} in @var{filterpat} negates the pattern; in this
+case, any completion not matching @var{filterpat} is removed.
+
+@item -P @var{prefix}
+@var{prefix} is added at the beginning of each possible completion
+after all other options have been applied.
+
+@item -S @var{suffix}
+@var{suffix} is appended to each possible completion
+after all other options have been applied.
+@end table
+
+The return value is true unless an invalid option is supplied, an option
+other than @option{-p} or @option{-r} is supplied without a @var{name}
+argument, an attempt is made to remove a completion specification for
+a @var{name} for which no specification exists, or
+an error occurs adding a completion specification.
+
+@end table
+@end ifset