Completion Matching Control (zsh)

### 19.5 Completion Matching Control ¶

When the user invokes completion, the current word on the command line (that is, the word the cursor is currently on) is used to generate a match pattern. Only those completions that match the pattern are offered to the user as matches.

The default match pattern is generated from the current word by either

- appending a ‘`*`’ (matching any number of characters in a completion) or,
- if the shell option `COMPLETE_IN_WORD` is set, inserting a ‘`*`’ at the cursor position.

This narrow pattern can be broadened selectively by passing a match specification to the `compadd` builtin command through its `-M` option (see Completion Builtin Commands). A match specification consists of one or more matchers separated by whitespace. Matchers in a match specification are applied one at a time, from left to right. Once all matchers have been applied, completions are compared to the final match pattern and non-matching ones are discarded.

- Note that the `-M` option is ignored if the current word contains a glob pattern and the shell option `GLOB_COMPLETE` is set or if the `pattern_match` key of the special associative array `compstate` is set to a non-empty value (see Completion Special Parameters).
- Users of the Completion System should generally not use the `-M` option directly, but rather use the `matcher-list` and `matcher` styles (see the subsection Standard Styles in Completion System Configuration).

Each matcher consists of

- a case-sensitive letter
- a ‘`:`’,
- one or more patterns separated by pipes (‘`|`’),
- an equals sign (‘`=`’), and
- another pattern.

The patterns before the ‘`=`’ are used to match substrings of the current word. For each matched substring, the corresponding part of the match pattern is broadened with the pattern after the ‘`=`’, by means of a logical `OR`.

Each pattern in a matcher cosists of either

- the empty string or
- a sequence of
  - literal characters (which may be quoted with a ‘`\`’),
  - question marks (‘`?`’),
  - bracket expressions (‘`[...]`’; see the subsection Glob Operators in Filename Generation), and/or
  - brace expressions (see below).

Other shell patterns are not allowed.

A brace expression, like a bracket expression, consists of a list of

- literal characters,
- ranges (‘`0-9`’), and/or
- character classes (‘`[:`name`:]`’).

However, they differ from each other as follows:

- A brace expression is delimited by a pair of braces (‘`{...}`’).
- Brace expressions do not support negations. That is, an initial ‘`!`’ or ‘`^`’ has no special meaning and will be interpreted as a literal character.
- When a character in the current word matches the nth pattern in a brace expression, the corresponding part of the match pattern is broadened only with the nth pattern of the brace expression on the other side of the ‘`=`’, if there is one; if there is no brace expression on the other side, then this pattern is the empty string. However, if either brace expression has more elements than the other, then the excess entries are simply ignored. When comparing indexes, each literal character or character class counts as one element, but each range is instead expanded to the full list of literal characters it represents. Additionally, if on both sides of the ‘`=`’, the nth pattern is ‘`[:upper:]`’ or ‘`[:lower:]`’, then these are expanded as ranges, too.

Note that, although the matching system does not yet handle multibyte characters, this is likely to be a future extension. Hence, using ‘`[:upper:]`’ and ‘`[:lower:]`’ is recommended over ‘`A-Z`’ and ‘`a-z`’.

Below are the different forms of matchers supported. Each uppercase form behaves exactly like its lowercase counterpart, but adds an additional step after the match pattern has filtered out non-matching completions: Each of a match’s substrings that was matched by a subpattern from an uppercase matcher is replaced with the corresponding substring of the current word. However, patterns from lowercase matchers have higher weight: If a substring of the current word was matched by patterns from both a lowercase and an uppercase matcher, then the lowercase matcher’s pattern wins and the corresponding part of the match is not modified.

Unless indicated otherwise, each example listed assumes `COMPLETE_IN_WORD` to be unset (as it is by default).

`m:` word-pat`=`match-pat
`M:` word-pat`=`match-pat

  For each substring of the current word that matches word-pat, broaden the corresponding part of the match pattern to additionally match match-pat.

  Examples:

    `m:{[:lower:]}={[:upper:]}` lets any lower case character in the current word be completed to itself or its uppercase counterpart. So, the completions ‘`foo`’, ‘`FOO`’ and ‘`Foo`’ will are be considered matches for the word ‘`fo`’.

    `M:_=` inserts every underscore from the current word into each match, in the same relative position, determined by matching the substrings around it. So, given a completion ‘`foo`’, the word ‘`f_o`’ will be completed to the match ‘`f_oo`’, even though the latter was not present as a completion.

`b:` word-pat`=`match-pat
`B:` word-pat`=`match-pat
`e:` word-pat`=`match-pat
`E:` word-pat`=`match-pat

  For each consecutive substring at the `b:`eginning or `e:`nd of the current word that matches word-pat, broaden the corresponding part of the match pattern to additionally match match-pat.

  Examples:

    ‘`b:-=+`’ lets any number of minuses at the start of the current word be completed to a minus or a plus.

    ‘`B:0=`’ adds all zeroes at the beginning of the current word to the beginning of each match.

`l:``|`word-pat`=`match-pat
`L:``|`word-pat`=`match-pat
`r:` word-pat`|``=`match-pat
`R:` word-pat`|``=`match-pat

  If there is a substring at the `l:`eft or `r:`ight edge of the current word that matches word-pat, then broaden the corresponding part of the match pattern to additionally match match-pat.

  For each `l:`, `L:`, `r:` and `R:` matcher (including the ones below), the pattern match-pat may also be a ‘`*`’. This matches any number of characters in a completion.

  Examples:

    ‘`r:|=*`’ appends a ‘`*`’ to the match pattern, even when `COMPLETE_IN_WORD` is set and the cursor is not at the end of the current word.

    If the current word starts with a minus, then ‘`L:|-=`’ will prepend it to each match.

`l:` anchor`|`word-pat`=`match-pat
`L:` anchor`|`word-pat`=`match-pat
`r:` word-pat`|`anchor`=`match-pat
`R:` word-pat`|`anchor`=`match-pat

  For each substring of the current word that matches word-pat and has on its `l:`eft or `r:`ight another substring matching anchor, broaden the corresponding part of the match pattern to additionally match match-pat.

  Note that these matchers (and the ones below) modify only what is matched by word-pat; they do not change the matching behavior of what is matched by anchor (or coanchor; see the matchers below). Thus, unless its corresponding part of the match pattern has been modified, the anchor in the current word has to match literally in each completion, just like any other substring of the current word.

  If a matcher includes at least one anchor (which includes the matchers with two anchors, below), then match-pat may also be ‘`*`’ or ‘`**`’. ‘`*`’ can match any part of a completion that does not contain any substrings matching anchor, whereas a ‘`**`’ can match any part of a completion, period. (Note that this is different from the behavior of ‘`*`’ in the anchorless forms of ‘`l:`’ and ‘`r:`’ and and also different from ‘`*`’ and ‘`**`’ in glob expressions.)

  Examples:

    ‘`r:|.=*`’ makes the completion ‘`comp.sources.unix`’ a match for the word ‘`..u`’ — but not for the word ‘`.u`’.

    Given a completion ‘`-``-foo`’, the matcher ‘`L:--|no-=`’ will complete the word ‘`-``-no-`’ to the match ‘`-``-no-foo`’.

`l:` anchor`||`coanchor`=`match-pat
`L:` anchor`||`coanchor`=`match-pat
`r:` coanchor`||`anchor`=`match-pat
`R:` coanchor`||`anchor`=`match-pat

  For any two consecutive substrings of the current word that match anchor and coanchor, in the order given, insert the pattern match-pat between their corresponding parts in the match pattern.

  Note that, unlike anchor, the pattern coanchor does not change what ‘`*`’ can match.

  Examples:

    ‘`r:?||[[:upper:]]=*`’ will complete the current word ‘`fB`’ to ‘`fooBar`’, but it will not complete it to ‘`fooHooBar`’ (because ‘`*`’ here cannot match anything that includes a match for ‘`[[:upper:]]`), nor will it complete ‘`B`’ to ‘`fooBar`’ (because there is no character in the current word to match coanchor).

    Given the current word ‘`pass.n`’ and a completion ‘`pass.byname`’, the matcher ‘`L:.||[[:alpha:]]=by`’ will produce the match ‘`pass.name`’.

`x:`

  Ignore this matcher and all matchers to its right.

  This matcher is used to mark the end of a match specification. In a single standalone list of matchers, this has no use, but where match specifications are concatenated, as is often the case when using the Completion System, it can allow one match specification to override another.