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
*
’ (matching any number of characters in a completion)
or,
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.
-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).
-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
:
’,
|
’),
=
’), and
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
\
’),
?
’),
[...]
’; see the subsection Glob Operators in
Filename Generation), and/or
Other shell patterns are not allowed.
A brace expression, like a bracket expression, consists of a list of
0-9
’), and/or
[:
name:]
’).
However, they differ from each other as follows:
{...}
’).
!
’ or ‘^
’ has no special meaning and will be interpreted as a literal
character.
=
’,
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-patM:
word-pat=
match-patFor each substring of the current word that matches word-pat, broaden the corresponding part of the match pattern to additionally match match-pat.
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-patB:
word-pat=
match-pate:
word-pat=
match-patE:
word-pat=
match-patFor 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.
‘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-patL:
|
word-pat=
match-patR:
word-pat|
=
match-patr:
word-pat|
=
match-patIf 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.
‘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-patL:
anchor|
word-pat=
match-patr:
word-pat|
anchor=
match-patR:
word-pat|
anchor=
match-patFor 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.)
‘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-patL:
anchor||
coanchor=
match-patr:
coanchor||
anchor=
match-patR:
coanchor||
anchor=
match-patFor 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.
‘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.