Completion System (zsh)

## 20 Completion System ¶

### 20.1 Description ¶

This describes the shell code for the ‘new’ completion system, referred to as `compsys`. It is written in shell functions based on the features described in the previous chapter, Completion Widgets.

The features are contextual, sensitive to the point at which completion is started. Many completions are already provided. For this reason, a user can perform a great many tasks without knowing any details beyond how to initialize the system, which is described in Initialization.

The context that decides what completion is to be performed may be

- an argument or option position: these describe the position on the command line at which completion is requested. For example ‘first argument to rmdir, the word being completed names a directory’;
- a special context, denoting an element in the shell’s syntax. For example ‘a word in command position’ or ‘an array subscript’.

A full context specification contains other elements, as we shall describe.

Besides commands names and contexts, the system employs two more concepts, styles and tags. These provide ways for the user to configure the system’s behaviour.

Tags play a dual role. They serve as a classification system for the matches, typically indicating a class of object that the user may need to distinguish. For example, when completing arguments of the `ls` command the user may prefer to try `files` before `directories`, so both of these are tags. They also appear as the rightmost element in a context specification.

Styles modify various operations of the completion system, such as output formatting, but also what kinds of completers are used (and in what order), or which tags are examined. Styles may accept arguments and are manipulated using the `zstyle` command described in The zsh/zutil Module.

In summary, tags describe what the completion objects are, and style `how` they are to be completed. At various points of execution, the completion system checks what styles and/or tags are defined for the current context, and uses that to modify its behavior. The full description of context handling, which determines how tags and other elements of the context influence the behaviour of styles, is described in Completion System Configuration.

When a completion is requested, a dispatcher function is called; see the description of `_main_complete` in the list of control functions below. This dispatcher decides which function should be called to produce the completions, and calls it. The result is passed to one or more completers, functions that implement individual completion strategies: simple completion, error correction, completion with error correction, menu selection, etc.

More generally, the shell functions contained in the completion system are of two types:

- those beginning ‘`comp`’ are to be called directly; there are only a few of these;
- those beginning ‘`_`’ are called by the completion code. The shell functions of this set, which implement completion behaviour and may be bound to keystrokes, are referred to as ‘widgets’. These proliferate as new completions are required.