complete built-in command for tcsh: List completions

Examples

1. Some commands take only directories as arguments, so there is no point in completing plain files. For example:

   > complete cd 'p/1/d/'

   completes only the first word following cd (p/1) with a directory.
2. p-type completion can be used to narrow down command completion. For example:

           > 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 only with ambiguous commands.
3. This is an example of n-type completion. Any word following find and immediately following -user is completed from the list of users.

   > complete find 'n/-user/u/'

4. This 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.

   > complete cc 'c/-I/d/'

5. 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.

   The man example, and several other examples that follow, could just as well have used c/* or n/* as p/*.

6. 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

   The complete command does not itself quote its arguments, so the braces, space and $ in {print $1} must be quoted explicitly.
7. One command can have multiple completions:

           > complete dbx 'p/2/(core)/' 'p/*/c/'

   This example completes the second argument to dbx with the word core and all other arguments with commands. 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.
8. 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 under File name substitution.
9. 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 override the completion mechanism using the complete-word-raw or list-choices-raw editor command.
10. The D, F and Tlists are like 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 one's mail directory. One might use

            > complete elm c@=@F:$HOME/Mail/@ 

    to complete elm -f = as if it were elm -f ~/Mail/. We used @ instead of / to avoid confusion with the select argument, and we used $HOME instead of ~ because home directory substitution only works at the beginning of a word.
11. suffix is used to add a nonstandard suffix (not space or '/' for directories) to completed words. For example,

            > 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 the order in which the completions are specified.
12. A more complex example:

            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 might change in future versions of the shell. See also the uncomplete built-in command.