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

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: