|
|
complete
Create, edit or list command completions.
SYNTAX
complete [command [word/pattern/list[:select]/[[suffix]/] ...]] (+)
Without arguments, lists all completions. With command, lists completions
for command. With command and word etc., defines completions.
command may be a full command name or a glob-pattern (see File-name substitution).
It can begin with `-' to indicate that completion should be used only
when command is ambiguous.
word specifies which word relative to the current word is to be completed,
and may be one of the following:
c Current-word completion. pattern is a glob-pattern
which must match the beginning of the current word on
the command line. pattern is ignored when completing
the current word.
C Like c, but includes pattern when completing the cur-
rent word.
n Next-word completion. pattern is a glob-pattern which
must match the beginning of the previous word on the
command line.
N Like n, but must match the beginning of the word two
before the current word.
p Position-dependent completion. pattern is a numeric
range, with the same syntax used to index shell vari-
ables, which must include the current word.
list, the list of possible completions, may be one of the following:
a Aliases
b Bindings (editor commands)
c Commands (builtin or external commands)
C External commands which begin with the supplied
path prefix
d Directories
D Directories which begin with the supplied path pre-
fix
e Environment variables
f Filenames
F Filenames which begin with the supplied path prefix
g Groupnames
j Jobs
l Limits
n Nothing
s Shell variables
S Signals
t Plain (``text'') files
T Plain (``text'') files which begin with the sup-
plied path prefix
v Any variables
u Usernames
x Like n, but prints select when list-choices is
used.
X Completions
$var Words from the variable var
(...) Words from the given list
`...` Words from the output of command
select is an optional glob-pattern. If given, words from only
list that match select are considered and the fignore shell
variable is ignored. The last three types of completion may
not have a select pattern, and x uses select as an explanatory
message when the list-choices editor command is used.
suffix is a single character to be appended to a successful
completion. If null, no character is appended. If omitted (in
which case the fourth delimiter can also be omitted), a slash
is appended to directories and a space to other words.
Now for some examples. Some commands take only directories as
arguments, so there's no point completing plain files.
> complete cd 'p/1/d/'
completes only the first word following `cd' (`p/1') with a
directory. p-type completion can also be used to narrow down
command completion:
> co[^D]
complete compress
> complete -co* 'p/0/(compress)/'
> co[^D]
> compress
This completion completes commands (words in position 0, `p/0')
which begin with `co' (thus matching `co*') to `compress' (the
only word in the list). The leading `-' indicates that this
completion is to be used with only ambiguous commands.
> complete find 'n/-user/u/'
is an example of n-type completion. Any word following `find'
and immediately following `-user' is completed from the list of
users.
> complete cc 'c/-I/d/'
demonstrates c-type completion. Any word following `cc' and
beginning with `-I' is completed as a directory. `-I' is not
taken as part of the directory because we used lowercase c.
Different lists are useful with different commands.
> complete alias 'p/1/a/'
> complete man 'p/*/c/'
> complete set 'p/1/s/'
> complete true 'p/1/x:Truth has no options./'
These complete words following `alias' with aliases, `man' with
commands, and `set' with shell variables. `true' doesn't have
any options, so x does nothing when completion is attempted and
prints `Truth has no options.' when completion choices are
listed.
Note that the man example, and several other examples below,
could just as well have used 'c/*' or 'n/*' as 'p/*'.
Words can be completed from a variable evaluated at completion
time,
> complete ftp 'p/1/$hostnames/'
> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu)
> ftp [^D]
rtfm.mit.edu tesla.ee.cornell.edu
> ftp [^C]
> set hostnames = (rtfm.mit.edu tesla.ee.cornell.edu
uunet.uu.net)
> ftp [^D]
rtfm.mit.edu tesla.ee.cornell.edu uunet.uu.net
or from a command run at completion time:
> complete kill 'p/*/`ps | awk \{print\ \$1\}`/'
> kill -9 [^D]
23113 23377 23380 23406 23429 23529 23530 PID
Note that the complete command does not itself quote its argu-
ments, so the braces, space and `$' in `{print $1}' must be
quoted explicitly.
One command can have multiple completions:
> complete dbx 'p/2/(core)/' 'p/*/c/'
completes the second argument to `dbx' with the word `core' and
all other arguments with commands. Note that the positional
completion is specified before the next-word completion.
Because completions are evaluated from left to right, if the
next-word completion were specified first it would always match
and the positional completion would never be executed. This is
a common mistake when defining a completion.
The select pattern is useful when a command takes files with
only particular forms as arguments. For example,
> complete cc 'p/*/f:*.[cao]/'
completes `cc' arguments to files ending in only `.c', `.a', or
`.o'. select can also exclude files, using negation of a glob-
pattern as described under Filename substitution. One might
use
> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'
to exclude precious source code from `rm' completion. Of
course, one could still type excluded names manually or over-
ride the completion mechanism using the complete-word-raw or
list-choices-raw editor commands (q.v.).
The `C', `D', `F' and `T' lists are like `c', `d', `f' and `t'
respectively, but they use the select argument in a different
way: to restrict completion to files beginning with a particu-
lar path prefix. For example, the Elm mail program uses `=' as
an abbreviation for one's mail directory. One might use
> complete elm c@=@F:$HOME/Mail/@
to complete `elm -f =' as if it were `elm -f ~/Mail/'. Note
that we used `@' instead of `/' to avoid confusion with the
select argument, and we used `$HOME' instead of `~' because
home directory substitution works at only the beginning of a
word.
suffix is used to add a nonstandard suffix (not space or `/'
for directories) to completed words.
> complete finger 'c/*@/$hostnames/' 'p/1/u/@'
completes arguments to `finger' from the list of users, appends
an `@', and then completes after the `@' from the `hostnames'
variable. Note again the order in which the completions are
specified.
Finally, here's a complex example for inspiration:
> complete find \
'n/-name/f/' 'n/-newer/f/' 'n/-{,n}cpio/f/' \
'n/-exec/c/' 'n/-ok/c/' 'n/-user/u/' \
'n/-group/g/' 'n/-fstype/(nfs 4.2)/' \
'n/-type/(b c d f l p s)/' \
'c/-/(name newer cpio ncpio exec ok user \
group fstype type atime ctime depth inum \
ls mtime nogroup nouser perm print prune \
size xdev)/' \
'p/*/d/'
This completes words following `-name', `-newer', `-cpio' or
`ncpio' (note the pattern which matches both) to files, words
following `-exec' or `-ok' to commands, words following `user'
and `group' to users and groups respectively and words follow-
ing `-fstype' or `-type' to members of the given lists. It
also completes the switches themselves from the given list
(note the use of c-type completion) and completes anything not
otherwise completed to a directory. Whew.
Notes
Remember that programmed completions are ignored if the word being completed
is a tilde substitution (beginning with `~') or a variable (beginning with `$').
complete is an experimental feature, and the syntax may change in future versions of the shell.
"Price is what you pay. Value is what you get" - Warren Buffett
Related commands:
uncomplete - remove a command completion.
history - Command History
