9.15. TC Shell Command, Filename, and Variable Completion

To save typing, tcsh has a mechanism called completion that allows you to type part of a command, filename, or variable, and then by pressing the Tab key, have the rest of the word completed for you.

If you type the first few letters of a command, and press the Tab key, tcsh will attempt to complete the command name. If tcsh cannot complete the command, because it doesn't exist, the terminal will beep and the cursor will stay at the end of the command. If there is more than one command starting with those characters, by pressing Ctrl-D, all commands that start with those characters will be listed.

Filename and variable completion work the same as command completion. With filename completion, if there are several files starting with the same letters, tcsh will complete the shortest name that matches, expand out the filename until the characters differ, and then flash the cursor for you to complete the rest. See Example 9.87.

9.15.1 The autolist Variable

If the autolist variable is set, and there are a number of possible completions, all of the possible commands, variables, or filenames will be listed depending on what type of completion is being performed when the Tab key is entered.

Example 9.87.

All files are listed for the current working directory.
After fu is typed, the Tab key is pressed, causing the filename to be completed to fumble, and listed.
Because none of the files start with fx, the terminal beeps and the cursor remains but does nothing.
There are a number of files starting with fi; the filenames are completed until the letters are no longer the same. When you press Ctrl-D, all files with that spelling are listed.
The autolist variable is set. If there are a number of choices, when you press the Tab key, autolist displays all the possibilities.
After you press the Tab key, a list of all files beginning with f are printed.
When the Tab key is pressed, the filename is expanded to foobarckle.
When the Tab key is pressed after da, the only command that begins with da is the date command. The command name is expanded and executed.
Because autolist is set, when the Tab key is pressed after ca, all commands starting with ca are listed. If autolist is not set, type Ctrl-D to get a list.
The leading $ on a word indicates that the shell should perform variable expansion when the Tab key is pressed to complete the word. The variable home is completed.
Variable completion is ambiguous in this example. When completion is attempted by pressing the Tab key, all possible shell variables are listed.

9.15.2 The fignore Variable

The shell variable, fignore, can be set to ignore certain filename extensions when filename completion is in use. For example, you may not want to expand files that end in .o because they are unreadable object files. Or maybe you don't want the .gif files to be accidently removed when filenames are expanded. For whatever reason, the fignore variable can be assigned a list of extensions for files that will be excluded from filename expansion.

Example 9.88.

The files in the current working directory are listed. Note that some of the files have extensions on their names.
The fignore variable allows you to list those filename extensions that should be ignored when filename completion is performed. All filenames ending in either .o or .gif will be ignored.
By pressing the Tab key, only the file baby is listed, not baby.gif. The .gif files are ignored.
Even though .gif is listed as a suffix to be ignored, fignore will not take effect when there are no other possible completions, such as the same filename without the .gif extension as in line 3.
When the vi editor is invoked, prog is expanded to prog.c.

9.15.3 The complete Shell Variable

This is a variable that does a lot! It is a little tricky trying to decipher all it can do from the tcsh man page, but you may find some of these examples helpful for a start. You can control what kind of completion you are doing. For example, maybe you only want completion to expand directory names, or a filename depending on its position in the command line, or maybe you would like certain commands to be expanded and others excluded, or even create a list of possible words that can be expanded. Whatever it is you want to do with completion the complete shell variable will no doubt accommodate you.

Filename completion can be even more sophisticated if the complete shell variable is set to enhance. This causes Tab completion to ignore case; to treat hyphens, periods, and underscores as word separators; and to consider hyphens and underscores as equivalent.

Example 9.89.

By setting the complete shell variable to enhance, Tab completion will ignore case; will treat hyphens, periods, and underscores as word separators; and will consider hyphens and underscores as equivalent.
With enhance set, filename completion expands g.. to any files starting with a g, followed by any two characters (..), and any characters to complete the filename, including hyphens, periods, and so forth.
With enhance set, filename completion expands GAW to any files starting with GAW , where GAW can be any combination of uppercase and lowercase letters, and the remaining characters can be any characters even if they contain hyphens, periods, and underscores.

9.15.4 Programming Completions

To customize completions to a more specific functionality, you can program the completions, and then store them in the ~/.tcshrc file, making them part of your tcsh environment each time you start a new TC shell. The purpose of programming completions is to improve efficiency and select types of commands and arguments that will be affected. (The Tab key for word completion and Ctrl-D to list possible completions still work the same way as they did for simple completions.)

Types of Completions

There three types of completions: p, n, and c. A p-type completion is position-dependent. It rules the way a completion is performed based on the position of a word in the command line, where position 0 is the command, position 1 is the first argument, position 2 is the second argument, and so on. Suppose, for example, you wanted to guarantee that any time a completion is performed for the built-in cd command, the first (and only) argument to cd is completed only if it is a directory name, nothing else; then you can program the completion as shown in the following example:

The complete command is followed by the cd command and what is called the completion rule. The p stands for the word position in the command line. The command, cd, is position 0 and its first argument is position 1. The pattern part of the rule is enclosed in slashes (p/1/ means position 1, the first argument to cd), and will be affected by the completion rule. The d part of the pattern is called a word type. See Table 9.17 on page 487 for a complete list of word types. The d word type means that only directories are to be affected by the completion. A filename or alias, for example, would not be completed if given as the first argument to cd. The rule states that whenever Tab completion is performed on the cd command, it will only take place if the first argument is a directory, and Ctrl-D will only list directories if the match is ambiguous; that is, there is more than one possible completion. See Example 9.90 for p-type completions.

Example 9.90.

Table 9.17. Completion Word Types
Word	Type
`a`	Alias
`b`	Editor keybinding commands
`c`	Commands (built-in or external commands)
`C`	External commands that begin with the supplied path prefix
`d`	Directory
`D`	Directories that begin with the supplied path prefix
`e`	Environment variables
`f`	Filenames (not directory)
`F`	Filenames that 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 beginning with the supplied path prefix
`v`	Any variables
`u`	Usernames
`X`	Command names for which completions have been defined
`x`	Like `n`, but prints a message if ^D is typed
`C, D, F, T`	Like `c, d, f, t`, but selects completions from a given directory
`(list)`	Selects completions from words in a list

The complete built-in command, without arguments, lists all programmed completions. The following examples (lines 2 through 11) use these completion rules.
This rule states that if Tab completion is used when typing arguments to the vi command, that all arguments (*), must be of type "t" (i.e., plain text files) for completion to performed.
The complete command, with the name of a command as its argument, displays the completion rule for that command. The completion rule for vi is displayed.
By setting the built-in command, autolist, all possible Tab completions will automatically be printed. (You don't have to press Ctrl-D.)
The man command has a programmed completion: complete man 'p/1/c/'. This rule states that the first argument given to the man command must be a command, because c is defined as a command word type. In this example, completion is attempted with the letters fin as the argument to man. All manual commands starting with fin will be displayed.
Only filenames will be completed, because the vi editor completion was programmed to complete only text files, not directories.
According to the vi completion rule, only text filenames will be completed, no matter how many arguments are passed.
When filename completion is performed on the first argument to the built-in cd command, the only word that will be completed must be the name of a directory as stated in the completion rule. The argument in this example will expand to a directory called shellsolutions.
The variable hosts is set to a list of IP addresses or hostnames.
The completion rule for telnet states that completion will be performed if position 1 contains one of the hostnames set in the hosts variable. This is a list word type completion.
The telnet command is executed and the word beginning with net, followed by pressing the Tab key, is completed to netcom.com, which is one of the hostnames in the hosts variable, previously set.
The alias completion is performed if the user types the word alias followed by a word that will be expanded to all aliases that contain that word. Word type a means only aliases are expanded for p, position 1.

A c-type completion is used to complete a pattern in the current word. The current word refers to the pattern enclosed in forward slashes. It rules that if the pattern is matched, any completion performed will finish the pattern.

Example 9.91.

These examples demonstrate a c-type completion. If the pattern in the first set of forward slashes is typed, that pattern will be completed by one of the words listed in the parentheses when a character(s) from that list is typed, followed by the Tab key.
When the stty command is typed, followed by a dash (–) character, the word will be completed to –raw if a dash, an r, and the Tab key are entered. One of the words from the rule list in parentheses (raw xcase noflsh) can be completed.
When the bash command is typed, followed by the pattern, –no, that pattern will be completed to –noprofile if the pattern –no is followed by a p and the Tab key. Completion is performed from one of the words in the rule list (profile rc braceexpansion); in this example, resulting in –noprofile.
Arguments to the find command are completed if the dash (–) character is completed by typing significant characters from any of the words in the find rule list (user name type exec).
When the man command is typed, the pattern perl is completed to perldelta because the pattern is followed by one of the words from the list (delta faq toc data modlib locale).
The uncomplete built-in command removes the completion rule for stty. The other completion rules remain.
The uncomplete built-in command, with the asterisk as its argument, removes all completion rules.

Example 9.92.

These examples demonstrate an n-type completion. If the word in the first set of forward slashes is typed (the current word) and matched, the next word (in the second set of forward slashes) will be completed according to the word type. The complete command lists two n-type completions, one for the rm command and one for the find command. When the rm command is executed with the –r switch, the word following –r must be of type directory if completion is to be performed. The rule for the find command is: if the –exec option is given, any words following it must be commands if completion is to be performed.
The output of the ls command shows that testing is a directory.
Filename completion is successful for the rm command because word completion is attempted for a directory named testing. If testing were a plain file, the completion would not have been performed.