complete

NAME

complete - lists or sets completions

SYNOPSIS

complete [command[word/pattern/list[:select]/[[suffix]/] ...]]

DESCRIPTION

This command is a C-shell built-in command.

The command argument can be a full command name or a glob-pattern (see "File-name substitution" in tcsh(1)). It can begin with a dash (-) to indicate that completion should be used only when command is ambiguous.

The word argument 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 current word.

n

Next-word completion. pattern is a glob-pattern that 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 variables, 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 (built-in or external commands)

C

External commands that begin with the supplied path prefix

d

Directories

D

Directories that begin with the supplied path prefix

e

Environment variables

f

File names

F

File names that begin with the supplied path prefix

g

Group names

j

Jobs

l

Limits

n

Nothing

s

Shell variables

S

Signals

t

Plain ("text") files

T

Plain ("text") files that begin with the supplied path prefix

v

Any variables

u

User names

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, only words from list that match select are considered, and the fignore shell variable is ignored. The last three types of completion can 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.

The next part of this section provides some examples. Some commands take only directories as arguments, so it is not necessary to complete plain files. For example:

> 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') that begin with 'co' (thus matching 'co*') to 'compress' (the only word in the list). The leading '-' indicates that this completion is to be used only with 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 lowercase c was used.

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' has no options, so x does nothing when completion is attempted and prints 'Truth has no options.' when completion choices are listed.

Note that the man(1) 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

> 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 arguments, 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. Since 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 only files with particular forms as arguments. For example:

> complete cc 'p/*/f:*.[cao]/'

completes 'cc' arguments only to files ending in '.c', '.a', or '.o'. select can also exclude files, using negation of a glob-pattern as described in the section on file-name substitution. You might use:

> complete rm 'p/*/f:^*.{c,h,cc,C,tex,1,man,l,y}/'

to exclude precious source code from 'rm' completion. You could still type excluded names manually or override the completion mechanism using the complete-word-raw or list-choices-raw editor commands.

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 particular path prefix. For example, the Elm mail program uses '=' as an abbreviation for a user'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 '@' is used instead of '/' to avoid confusion with the select argument; '$HOME' is used instead of '~' because home directory substitution only works at 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.

The following example is more complex:

> 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 following '-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.

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. See also the uncomplete built-in command.