The zsh/complist Module (zsh)

### 22.7 The zsh/complist Module ¶

The `zsh/complist` module offers three extensions to completion listings: the ability to highlight matches in such a list, the ability to scroll through long lists and a different style of menu completion.

#### 22.7.1 Colored completion listings ¶

Whenever one of the parameters `ZLS_COLORS` or `ZLS_COLOURS` is set and the `zsh/complist` module is loaded or linked into the shell, completion lists will be colored. Note, however, that `complist` will not automatically be loaded if it is not linked in: on systems with dynamic loading, ‘`zmodload zsh/complist`’ is required.

The parameters `ZLS_COLORS` and `ZLS_COLOURS` describe how matches are highlighted. To turn on highlighting an empty value suffices, in which case all the default values given below will be used. The format of the value of these parameters is the same as used by the GNU version of the `ls` command: a colon-separated list of specifications of the form ‘name`=`value’. The name may be one of the following strings, most of which specify file types for which the value will be used. The strings and their default values are:

`no 0`

  for normal text (i.e. when displaying something other than a matched file)

`fi 0`

  for regular files

`di 32`

  for directories

`ln 36`

  for symbolic links. If this has the special value `target`, symbolic links are dereferenced and the target file used to determine the display format.

`pi 31`

  for named pipes (FIFOs)

`so 33`

  for sockets

`bd 44;37`

  for block devices

`cd 44;37`

  for character devices

`or` none

  for a symlink to nonexistent file (default is the value defined for `ln`)

`mi` none

  for a non-existent file (default is the value defined for `fi`); this code is currently not used

`su 37;41`

  for files with setuid bit set

`sg 30;43`

  for files with setgid bit set

`tw 30;42`

  for world writable directories with sticky bit set

`ow 34;43`

  for world writable directories without sticky bit set

`sa` none

  for files with an associated suffix alias; this is only tested after specific suffixes, as described below

`st 37;44`

  for directories with sticky bit set but not world writable

`ex 35`

  for executable files

`lc \e[`

  for the left code (see below)

`rc m`

  for the right code

`tc 0`

  for the character indicating the file type printed after filenames if the `LIST_TYPES` option is set

`sp 0`

  for the spaces printed after matches to align the next column

`ec` none

  for the end code

Apart from these strings, the name may also be an asterisk (‘`*`’) followed by any string. The value given for such a string will be used for all files whose name ends with the string. The name may also be an equals sign (‘`=`’) followed by a pattern; the `EXTENDED_GLOB` option will be turned on for evaluation of the pattern. The value given for this pattern will be used for all matches (not just filenames) whose display string are matched by the pattern. Definitions for the form with the leading equal sign take precedence over the values defined for file types, which in turn take precedence over the form with the leading asterisk (file extensions).

The leading-equals form also allows different parts of the displayed strings to be colored differently. For this, the pattern has to use the ‘`(#b)`’ globbing flag and pairs of parentheses surrounding the parts of the strings that are to be colored differently. In this case the value may consist of more than one color code separated by equal signs. The first code will be used for all parts for which no explicit code is specified and the following codes will be used for the parts matched by the sub-patterns in parentheses. For example, the specification ‘`=(#b)(?)*(?)=0=3=7`’ will be used for all matches which are at least two characters long and will use the code ‘`3`’ for the first character, ‘`7`’ for the last character and ‘`0`’ for the rest.

All three forms of name may be preceded by a pattern in parentheses. If this is given, the value will be used only for matches in groups whose names are matched by the pattern given in the parentheses. For example, ‘`(g*)m*=43`’ highlights all matches beginning with ‘`m`’ in groups whose names begin with ‘`g`’ using the color code ‘`43`’. In case of the ‘`lc`’, ‘`rc`’, and ‘`ec`’ codes, the group pattern is ignored.

Note also that all patterns are tried in the order in which they appear in the parameter value until the first one matches which is then used. Patterns may be matched against completions, descriptions (possibly with spaces appended for padding), or lines consisting of a completion followed by a description. For consistent coloring it may be necessary to use more than one pattern or a pattern with backreferences.

When printing a match, the code prints the value of `lc`, the value for the file-type or the last matching specification with a ‘`*`’, the value of `rc`, the string to display for the match itself, and then the value of `ec` if that is defined or the values of `lc`, `no`, and `rc` if `ec` is not defined.

The default values are ISO 6429 (ANSI) compliant and can be used on vt100 compatible terminals such as `xterm`s. On monochrome terminals the default values will have no visible effect. The `colors` function from the contribution can be used to get associative arrays containing the codes for ANSI terminals (see Other Functions). For example, after loading `colors`, one could use ‘`$color[red]`’ to get the code for foreground color red and ‘`$color[bg-green]`’ for the code for background color green.

If the completion system invoked by compinit is used, these parameters should not be set directly because the system controls them itself. Instead, the `list-colors` style should be used (see Completion System Configuration).

#### 22.7.2 Scrolling in completion listings ¶

To enable scrolling through a completion list, the `LISTPROMPT` parameter must be set. Its value will be used as the prompt; if it is the empty string, a default prompt will be used. The value may contain escapes of the form ‘`%x`’. It supports the escapes ‘`%B`’, ‘`%b`’, ‘`%S`’, ‘`%s`’, ‘`%U`’, ‘`%u`’, ‘`%F`’, ‘`%f`’, ‘`%K`’, ‘`%k`’ and ‘`%{`...`%}`’ used also in shell prompts as well as three pairs of additional sequences: a ‘`%l`’ or ‘`%L`’ is replaced by the number of the last line shown and the total number of lines in the form ‘number`/`total’; a ‘`%m`’ or ‘`%M`’ is replaced with the number of the last match shown and the total number of matches; and ‘`%p`’ or ‘`%P`’ is replaced with ‘`Top`’, ‘`Bottom`’ or the position of the first line shown in percent of the total number of lines, respectively. In each of these cases the form with the uppercase letter will be replaced with a string of fixed width, padded to the right with spaces, while the lowercase form will not be padded.

If the parameter `LISTPROMPT` is set, the completion code will not ask if the list should be shown. Instead it immediately starts displaying the list, stopping after the first screenful, showing the prompt at the bottom, waiting for a keypress after temporarily switching to the `listscroll` keymap. Some of the zle functions have a special meaning while scrolling lists:

`send-break`

  stops listing discarding the key pressed

`accept-line`, `down-history`, `down-line-or-history`
`down-line-or-search`, `vi-down-line-or-history`

  scrolls forward one line

`complete-word`, `menu-complete`, `expand-or-complete`
`expand-or-complete-prefix`, `menu-complete-or-expand`

  scrolls forward one screenful

`accept-search`

  stop listing but take no other action

Every other character stops listing and immediately processes the key as usual. Any key that is not bound in the `listscroll` keymap or that is bound to `undefined-key` is looked up in the keymap currently selected.

As for the `ZLS_COLORS` and `ZLS_COLOURS` parameters, `LISTPROMPT` should not be set directly when using the shell function based completion system. Instead, the `list-prompt` style should be used.