zsh: Extended Completion

Next: Example, Previous: Alternative Completion, Up: Completion Using compctl [Contents][Index]

Additional options are available that restrict completion to some part of the command line; this is referred to as ‘extended completion’.

### 21.6 Extended Completion

`compctl` [ `-CDT` ] options `-x` pattern options `-` ... `-``-`
`` [ command ... ]
`compctl` [ `-CDT` ] options [ `-x` pattern options `-` ... `-``-` ]
`` [ `+` options [ `-x` ... `-``-` ] ... [`+`] ] [ command ... ]

The form with ‘`-x`’ specifies extended completion for the commands given; as shown, it may be combined with alternative completion using ‘`+`’. Each pattern is examined in turn; when a match is found, the corresponding options, as described in Option Flags above, are used to generate possible completions. If no pattern matches, the options given before the `-x` are used.

Note that each pattern should be supplied as a single argument and should be quoted to prevent expansion of metacharacters by the shell.

A pattern is built of sub-patterns separated by commas; it matches if at least one of these sub-patterns matches (they are ‘or’ed). These sub-patterns are in turn composed of other sub-patterns separated by white spaces which match if all of the sub-patterns match (they are ‘and’ed). An element of the sub-patterns is of the form ‘c`[`...`][`...`]`’, where the pairs of brackets may be repeated as often as necessary, and matches if any of the sets of brackets match (an ‘or’). The example below makes this clearer.

The elements may be any of the following:

`s[`string`]`...

  Matches if the current word on the command line starts with one of the strings given in brackets. The string is not removed and is not part of the completion.

`S[`string`]`...

  Like `s[`string`]` except that the string is part of the completion.

`p[`from`,`to`]`...

  Matches if the number of the current word is between one of the from and to pairs inclusive. The comma and to are optional; to defaults to the same value as from. The numbers may be negative: `-`n refers to the n’th last word on the line.

`c[`offset`,`string`]`...

  Matches if the string matches the word offset by offset from the current word position. Usually offset will be negative.

`C[`offset`,`pattern`]`...

  Like `c` but using pattern matching instead.

`w[`index`,`string`]`...

  Matches if the word in position index is equal to the corresponding string. Note that the word count is made after any alias expansion.

`W[`index`,`pattern`]`...

  Like `w` but using pattern matching instead.

`n[`index`,`string`]`...

  Matches if the current word contains string. Anything up to and including the indexth occurrence of this string will not be considered part of the completion, but the rest will. index may be negative to count from the end: in most cases, index will be 1 or -1. For example,

      compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk

  will usually complete usernames, but if you insert an `@` after the name, names from the array hosts (assumed to contain hostnames, though you must make the array yourself) will be completed. Other commands such as `rcp` can be handled similarly.

`N[`index`,`string`]`...

  Like `n` except that the string will be taken as a character class. Anything up to and including the indexth occurrence of any of the characters in string will not be considered part of the completion.

`m[`min`,`max`]`...

  Matches if the total number of words lies between min and max inclusive.

`r[`str1`,`str2`]`...

  Matches if the cursor is after a word with prefix str1. If there is also a word with prefix str2 on the command line after the one matched by str1 it matches only if the cursor is before this word. If the comma and str2 are omitted, it matches if the cursor is after a word with prefix str1.

`R[`str1`,`str2`]`...

  Like `r` but using pattern matching instead.

`q[`str`]`...

  Matches the word currently being completed is in single quotes and the str begins with the letter ‘s’, or if completion is done in double quotes and str starts with the letter ‘d’, or if completion is done in backticks and str starts with a ‘b’.

Next: Example, Previous: Alternative Completion, Up: Completion Using compctl [Contents][Index]