bash: Programmable Completion Builtins
1
1 8.7 Programmable Completion Builtins
1 ====================================
1
1 Three builtin commands are available to manipulate the programmable
1 completion facilities: one to specify how the arguments to a particular
1 command are to be completed, and two to modify the completion as it is
1 happening.
1
1 'compgen'
1 compgen [OPTION] [WORD]
1
1 Generate possible completion matches for WORD according to the
1 OPTIONs, which may be any option accepted by the 'complete' builtin
1 with the exception of '-p' and '-r', and write the matches to the
1 standard output. When using the '-F' or '-C' options, the various
1 shell variables set by the programmable completion facilities,
1 while available, will not have useful values.
1
1 The matches will be generated in the same way as if the
1 programmable completion code had generated them directly from a
1 completion specification with the same flags. If WORD is
1 specified, only those completions matching WORD will be displayed.
1
1 The return value is true unless an invalid option is supplied, or
1 no matches were generated.
1
1 'complete'
1 complete [-abcdefgjksuv] [-o COMP-OPTION] [-DE] [-A ACTION] [-G GLOBPAT] [-W WORDLIST]
1 [-F FUNCTION] [-C COMMAND] [-X FILTERPAT]
1 [-P PREFIX] [-S SUFFIX] NAME [NAME ...]
1 complete -pr [-DE] [NAME ...]
1
1 Specify how arguments to each NAME should be completed. If the
1 '-p' option is supplied, or if no options are supplied, existing
1 completion specifications are printed in a way that allows them to
1 be reused as input. The '-r' option removes a completion
1 specification for each NAME, or, if no NAMEs are supplied, all
1 completion specifications. The '-D' option indicates that the
1 remaining options and actions should apply to the "default" command
1 completion; that is, completion attempted on a command for which no
1 completion has previously been defined. The '-E' option indicates
1 that the remaining options and actions should apply to "empty"
1 command completion; that is, completion attempted on a blank line.
1
1 The process of applying these completion specifications when word
11 completion is attempted is described above (⇒Programmable
Completion). The '-D' option takes precedence over '-E'.
1
1 Other options, if specified, have the following meanings. The
1 arguments to the '-G', '-W', and '-X' options (and, if necessary,
1 the '-P' and '-S' options) should be quoted to protect them from
1 expansion before the 'complete' builtin is invoked.
1
1 '-o COMP-OPTION'
1 The COMP-OPTION controls several aspects of the compspec's
1 behavior beyond the simple generation of completions.
1 COMP-OPTION may be one of:
1
1 'bashdefault'
1 Perform the rest of the default Bash completions if the
1 compspec generates no matches.
1
1 'default'
1 Use Readline's default filename completion if the
1 compspec generates no matches.
1
1 'dirnames'
1 Perform directory name completion if the compspec
1 generates no matches.
1
1 'filenames'
1 Tell Readline that the compspec generates filenames, so
1 it can perform any filename-specific processing (like
1 adding a slash to directory names quoting special
1 characters, or suppressing trailing spaces). This option
1 is intended to be used with shell functions specified
1 with '-F'.
1
1 'noquote'
1 Tell Readline not to quote the completed words if they
1 are filenames (quoting filenames is the default).
1
1 'nosort'
1 Tell Readline not to sort the list of possible
1 completions alphabetically.
1
1 'nospace'
1 Tell Readline not to append a space (the default) to
1 words completed at the end of the line.
1
1 'plusdirs'
1 After any matches defined by the compspec are generated,
1 directory name completion is attempted and any matches
1 are added to the results of the other actions.
1
1 '-A ACTION'
1 The ACTION may be one of the following to generate a list of
1 possible completions:
1
1 'alias'
1 Alias names. May also be specified as '-a'.
1
1 'arrayvar'
1 Array variable names.
1
1 'binding'
11 Readline key binding names (⇒Bindable Readline
Commands).
1
1 'builtin'
1 Names of shell builtin commands. May also be specified
1 as '-b'.
1
1 'command'
1 Command names. May also be specified as '-c'.
1
1 'directory'
1 Directory names. May also be specified as '-d'.
1
1 'disabled'
1 Names of disabled shell builtins.
1
1 'enabled'
1 Names of enabled shell builtins.
1
1 'export'
1 Names of exported shell variables. May also be specified
1 as '-e'.
1
1 'file'
1 File names. May also be specified as '-f'.
1
1 'function'
1 Names of shell functions.
1
1 'group'
1 Group names. May also be specified as '-g'.
1
1 'helptopic'
11 Help topics as accepted by the 'help' builtin (⇒Bash
Builtins).
1
1 'hostname'
1 Hostnames, as taken from the file specified by the
1 'HOSTFILE' shell variable (⇒Bash Variables).
1
1 'job'
1 Job names, if job control is active. May also be
1 specified as '-j'.
1
1 'keyword'
1 Shell reserved words. May also be specified as '-k'.
1
1 'running'
1 Names of running jobs, if job control is active.
1
1 'service'
1 Service names. May also be specified as '-s'.
1
1 'setopt'
1 Valid arguments for the '-o' option to the 'set' builtin
1 (⇒The Set Builtin).
1
1 'shopt'
1 Shell option names as accepted by the 'shopt' builtin
1 (⇒Bash Builtins).
1
1 'signal'
1 Signal names.
1
1 'stopped'
1 Names of stopped jobs, if job control is active.
1
1 'user'
1 User names. May also be specified as '-u'.
1
1 'variable'
1 Names of all shell variables. May also be specified as
1 '-v'.
1
1 '-C COMMAND'
1 COMMAND is executed in a subshell environment, and its output
1 is used as the possible completions.
1
1 '-F FUNCTION'
1 The shell function FUNCTION is executed in the current shell
1 environment. When it is executed, $1 is the name of the
1 command whose arguments are being completed, $2 is the word
1 being completed, and $3 is the word preceding the word being
11 completed, as described above (⇒Programmable
Completion). When it finishes, the possible completions are
1 retrieved from the value of the 'COMPREPLY' array variable.
1
1 '-G GLOBPAT'
1 The filename expansion pattern GLOBPAT is expanded to generate
1 the possible completions.
1
1 '-P PREFIX'
1 PREFIX is added at the beginning of each possible completion
1 after all other options have been applied.
1
1 '-S SUFFIX'
1 SUFFIX is appended to each possible completion after all other
1 options have been applied.
1
1 '-W WORDLIST'
1 The WORDLIST is split using the characters in the 'IFS'
1 special variable as delimiters, and each resultant word is
1 expanded. The possible completions are the members of the
1 resultant list which match the word being completed.
1
1 '-X FILTERPAT'
1 FILTERPAT is a pattern as used for filename expansion. It is
1 applied to the list of possible completions generated by the
1 preceding options and arguments, and each completion matching
1 FILTERPAT is removed from the list. A leading '!' in
1 FILTERPAT negates the pattern; in this case, any completion
1 not matching FILTERPAT is removed.
1
1 The return value is true unless an invalid option is supplied, an
1 option other than '-p' or '-r' is supplied without a NAME argument,
1 an attempt is made to remove a completion specification for a NAME
1 for which no specification exists, or an error occurs adding a
1 completion specification.
1
1 'compopt'
1 compopt [-o OPTION] [-DE] [+o OPTION] [NAME]
1 Modify completion options for each NAME according to the OPTIONs,
1 or for the currently-executing completion if no NAMEs are supplied.
1 If no OPTIONs are given, display the completion options for each
1 NAME or the current completion. The possible values of OPTION are
1 those valid for the 'complete' builtin described above. The '-D'
1 option indicates that the remaining options should apply to the
1 "default" command completion; that is, completion attempted on a
1 command for which no completion has previously been defined. The
1 '-E' option indicates that the remaining options should apply to
1 "empty" command completion; that is, completion attempted on a
1 blank line.
1
1 The '-D' option takes precedence over '-E'.
1
1 The return value is true unless an invalid option is supplied, an
1 attempt is made to modify the options for a NAME for which no
1 completion specification exists, or an output error occurs.
1