Manual Pages for UNIX Darwin command on man zshcompwid

ZSHCOMPWID(1) ZSHCOMPWID(1)

NAME

zshcompwid - zsh completion widgets

DESCRIPTION

The shell's programmable completion mechanism can be manipulated in two

ways; here the low-level features supporting the newer, function-based

mechanism are defined. A complete set of shell functions based on

these features is described in zshcompsys(1), and users with no inter-

est in adding to that system (or, potentially, writing their own --

see dictionary entry for `hubris') should skip this section. The older

system based on the ccoommppccttll builtin command is described in zshcom-

pctl(1).

Completion widgets are defined by the -CC option to the zzllee builtin com-

mand provided by the zzsshh//zzllee module (see zshzle(1)). For example,

zzllee -CC ccoommpplleettee eexxppaanndd-oorr-ccoommpplleettee ccoommpplleetteerr

defines a widget named `ccoommpplleettee'. The second argument is the name of

any of the builtin widgets that handle completions: ccoommpplleettee-wwoorrdd,

eexxppaanndd-oorr-ccoommpplleettee, eexxppaanndd-oorr-ccoommpplleettee-pprreeffiixx, mmeennuu-ccoommpplleettee,

mmeennuu-eexxppaanndd-oorr-ccoommpplleettee, rreevveerrssee-mmeennuu-ccoommpplleettee, lliisstt-cchhooiicceess, or

ddeelleettee-cchhaarr-oorr-lliisstt. Note that this will still work even if the widget

in question has been re-bound.

When this newly defined widget is bound to a key using the bbiinnddkkeeyy builtin command defined in the zzsshh//zzllee module (see zshzle(1)), typing that key will call the shell function `ccoommpplleetteerr'. This function is responsible for generating the possible matches using the builtins described below. As with other ZLE widgets, the function is called with its standard input closed. Once the function returns, the completion code takes over control again

and treats the matches in the same manner as the specified builtin wid-

get, in this case eexxppaanndd-oorr-ccoommpplleettee.

SSPPEECCIIAALL PPAARRAAMMEETTEERRSS Inside completion widgets, and any functions called from them, some parameters have special meaning; outside these functions they are not special to the shell in any way. These parameters are used to pass information between the completion code and the completion widget. Some

of the builtin commands and the condition codes use or change the cur-

rent values of these parameters. Any existing values will be hidden during execution of completion widgets; except for ccoommppssttaattee, the parameters are reset on each function exit (including nested function calls from within the completion widget) to the values they had when the function was entered. CCUURRRREENNTT This is the number of the current word, i.e. the word the cursor is currently on in the wwoorrddss array. Note that this value is only correct if the kksshhaarrrraayyss option is not set. IIPPRREEFFIIXX Initially this will be set to the empty string. This parameter functions like PPRREEFFIIXX; it contains a string which precedes the one in PPRREEFFIIXX and is not considered part of the list of matches. Typically, a string is transferred from the beginning of PPRREEFFIIXX to the end of IIPPRREEFFIIXX, for example:

IIPPRREEFFIIXX==$${{PPRREEFFIIXX%%%%\\==**}}==

PPRREEFFIIXX==$${{PPRREEFFIIXX##**==}}

causes the part of the prefix up to and including the first equal sign not to be treated as part of a matched string. This can be done automatically by the ccoommppsseett builtin, see below. IISSUUFFFFIIXX As IIPPRREEFFIIXX, but for a suffix that should not be considered part of the matches; note that the IISSUUFFFFIIXX string follows the SSUUFFFFIIXX string. PPRREEFFIIXX Initially this will be set to the part of the current word from the beginning of the word up to the position of the cursor; it may be altered to give a common prefix for all matches. QQIIPPRREEFFIIXX

This parameter is read-only and contains the quoted string up to

the word being completed. E.g. when completing `""ffoooo', this

parameter contains the double quote. If the -qq option of ccoommppsseett

is used (see below), and the original string was `""ffoooo bbaarr' with the cursor on the `bbaarr', this parameter contains `""ffoooo '. QQIISSUUFFFFIIXX Like QQIIPPRREEFFIIXX, but containing the suffix. SSUUFFFFIIXX Initially this will be set to the part of the current word from

the cursor position to the end; it may be altered to give a com-

mon suffix for all matches. It is most useful when the option

CCOOMMPPLLEETTEEIINNWWOORRDD is set, as otherwise the whole word on the com-

mand line is treated as a prefix. ccoommppssttaattee This is an associative array with various keys and values that

the completion code uses to exchange information with the com-

pletion widget. The keys are: aallllqquuootteess

The -qq option of the ccoommppsseett builtin command (see below)

allows a quoted string to be broken into separate words; if the cursor is on one of those words, that word will be

completed, possibly invoking `ccoommppsseett -qq' recursively.

With this key it is possible to test the types of quoted strings which are currently broken into parts in this

fashion. Its value contains one character for each quot-

ing level. The characters are a single quote or a double quote for strings quoted with these characters and a

backslash for strings not starting with a quote charac-

ter. The first character in the value always corresponds to the innermost quoting level. ccoonntteexxtt This will be set by the completion code to the overall context in which completion is attempted. Possible values are: aarrrraayyvvaalluuee when completing inside the value of an array parameter assignment; in this case the wwoorrddss array contains the words inside the parentheses. bbrraacceeppaarraammeetteerr when completing the name of a parameter in a

parameter expansion beginning with $${{.

aassssiiggnnppaarraammeetteerr when completing the name of a parameter in a parameter assignment. ccoommmmaanndd when completing for a normal command (either in

command position or for an argument of the com-

mand). ccoonnddiittiioonn when completing inside a `[[[[...]]]]' conditional expression; in this case the wwoorrddss array contains only the words inside the conditional expression. mmaatthh when completing in a mathematical environment such as a `((((...))))' construct. ppaarraammeetteerr when completing the name of a parameter in a

parameter expansion beginning with $$ but not $${{.

rreeddiirreecctt when completing after a redirection operator. ssuubbssccrriipptt when completing inside a parameter subscript.

vvaalluuee when completing the value of a parameter assign-

ment. eexxaacctt Controls the behaviour when the RREECCEEXXAACCTT option is set. It will be set to aacccceepptt if an exact match would be accepted, and will be unset otherwise. If it was set when at least one match equal to the string on the line was generated, the match is accepted. eexxaaccttssttrriinngg The string of an exact match if one was found, otherwise unset. iiggnnoorreedd The number of words that were ignored because they

matched one of the patterns given with the -FF option to

the ccoommppaadddd builtin command. iinnsseerrtt This controls the manner in which a match is inserted into the command line. On entry to the widget function, if it is unset the command line is not to be changed; if set to uunnaammbbiigguuoouuss, any prefix common to all matches is

to be inserted; if set to aauuttoommeennuu-uunnaammbbiigguuoouuss, the com-

mon prefix is to be inserted and the next invocation of the completion code may start menu completion (due to the AAUUTTOOMMEENNUU option being set); if set to mmeennuu or aauuttoommeennuu menu completion will be started for the matches currently generated (in the latter case this will happen because the AAUUTTOOMMEENNUU is set). The value may also contain the string `ttaabb' when the completion code would normally not really do completion, but only insert the TAB character. On exit it may be set to any of the values above (where setting it to the empty string is the same as unsetting it), or to a number, in which case the match whose number

is given will be inserted into the command line. Nega-

tive numbers count backward from the last match (with

`-11' selecting the last match) and out-of-range values

are wrapped around, so that a value of zero selects the last match and a value one more than the maximum selects the first. Unless the value of this key ends in a space,

the match is inserted as in a menu completion, i.e. with-

out automatically appending a space. Both mmeennuu and aauuttoommeennuu may also specify the the number of the match to insert, given after a colon. For example, `mmeennuu::22' says to start menu completion, beginning with the second match. Note that a value containing the substring `ttaabb' makes the matches generated be ignored and only the TAB be inserted. Finally, it may also be set to aallll, which makes all matches generated be inserted into the line. iinnsseerrttppoossiittiioonnss When the completion system inserts an unambiguous string

into the line, there may be multiple places where charac-

ters are missing or where the character inserted differs from at least one match. The value of this key contains a colon separated list of all these positions, as indexes into the command line. llaassttpprroommpptt

If this is set to a non-empty string for every match

added, the completion code will move the cursor back to the previous prompt after the list of completions has been displayed. Initially this is set or unset according to the AALLWWAAYYSSLLAASSTTPPRROOMMPPTT option. lliisstt This controls whether or how the list of matches will be displayed. If it is unset or empty they will never be listed; if its value begins with lliisstt, they will always be listed; if it begins with aauuttoolliisstt or aammbbiigguuoouuss, they will be listed when the AAUUTTOOLLIISSTT or LLIISSTTAAMMBBIIGGUUOOUUSS options respectively would normally cause them to be. If the substring ffoorrccee appears in the value, this makes

the list be shown even if there is only one match. Nor-

mally, the list would be shown only if there are at least two matches. The value contains the substring ppaacckkeedd if the LLIISSTTPPAACCKKEEDD option is set. If this substring is given for all matches added to a group, this group will show the LLIISSTTPPAACCKKEEDD behavior. The same is done for the LLIISSTTRROOWWSSFFIIRRSSTT option with the substring rroowwss. Finally, if the value contains the string eexxppllaannaattiioonnss, only the explanation strings, if any, will be listed and if it contains mmeessssaaggeess, only the messages (added with

the -xx option of ccoommppaadddd) will be listed. If it contains

both eexxppllaannaattiioonnss and mmeessssaaggeess both kinds of explanation strings will be listed. It will be set appropriately on entry to a completion widget and may be changed there. lliissttlliinneess This gives the number of lines that are needed to display the full list of completions. Note that to calculate the

total number of lines to display you need to add the num-

ber of lines needed for the command line to this value, this is available as the value of the BBUUFFFFEERRLLIINNEESS special parameter. lliissttmmaaxx

Initially this is set to the value of the LLIISSTTMMAAXX parame-

ter. It may be set to any other value; when the widget exits this value will be used in the same way as the value of LLIISSTTMMAAXX. nnmmaattcchheess

The number of matches generated and accepted by the com-

pletion code so far. oollddiinnsseerrtt On entry to the widget this will be set to the number of the match of an old list of completions that is currently inserted into the command line. If no match has been inserted, this is unset. As with oollddlliisstt, the value of this key will only be used if it is the string kkeeeepp. If it was set to this value by the widget and there was an old match inserted into the command line, this match will be kept and if the value of the iinnsseerrtt key specifies that another match should be inserted, this will be inserted after the old one. oollddlliisstt

This is set to yyeess if there is still a valid list of com-

pletions from a previous completion at the time the wid-

get is invoked. This will usually be the case if and only if the previous editing operation was a completion widget or one of the builtin completion functions. If there is a valid list and it is also currently shown on the screen, the value of this key is sshhoowwnn. After the widget has exited the value of this key is only used if it was set to kkeeeepp. In this case the completion code will continue to use this old list. If the widget generated new matches, they will not be used. ppaarraammeetteerr The name of the parameter when completing in a subscript or in the value of a parameter assignment. ppaatttteerrnniinnsseerrtt Normally this is set to mmeennuu, which specifies that menu completion will be used whenever a set of matches was generated using pattern matching. If it is set to any

other non-empty string by the user and menu completion is

not selected by other option settings, the code will instead insert any common prefix for the generated matches as with normal completion. ppaatttteerrnnmmaattcchh Locally controls the behaviour given by the GGLLOOBBCCOOMMPPLLEETTEE option. Initially it is set to `**' if and only if the option is set. The completion widget may set it to this value, to an empty string (which has the same effect as

unsetting it), or to any other non-empty string. If it

is non-empty, unquoted metacharacters on the command line

will be treated as patterns; if it is `**', then addition-

ally a wildcard `**' is assumed at the cursor position; if

it is empty or unset, metacharacters will be treated lit-

erally. Note that the matcher specifications given to the ccoommppaadddd builtin command are not used if this is set to a

non-empty string.

qquuoottee When completing inside quotes, this contains the quota-

tion character (i.e. either a single quote, a double quote, or a backtick). Otherwise it is unset. qquuoottiinngg When completing inside single quotes, this is set to the string ssiinnggllee; inside double quotes, the string ddoouubbllee; inside backticks, the string bbaacckkttiicckk. Otherwise it is unset. rreeddiirreecctt The redirection operator when completing in a redirection position, i.e. one of <<, >>, etc. rreessttoorree This is set to aauuttoo before a function is entered, which forces the special parameters mentioned above (wwoorrddss, CCUURRRREENNTT, PPRREEFFIIXX, IIPPRREEFFIIXX, SSUUFFFFIIXX, and IISSUUFFFFIIXX) to be restored to their previous values when the function exits. If a function unsets it or sets it to any other string, they will not be restored. ttooeenndd Specifies the occasions on which the cursor is moved to the end of a string when a match is inserted. On entry

to a widget function, it may be ssiinnggllee if this will hap-

pen when a single unambiguous match was inserted or mmaattcchh

if it will happen any time a match is inserted (for exam-

ple, by menu completion; this is likely to be the effect of the AALLWWAAYYSSTTOOEENNDD option). On exit, it may be set to ssiinnggllee as above. It may also be set to aallwwaayyss, or to the empty string or unset; in those cases the cursor will be moved to the end of the string always or never respectively. Any other string is treated as mmaattcchh. uunnaammbbiigguuoouuss

This key is read-only and will always be set to the com-

mon (unambiguous) prefix the completion code has gener-

ated for all matches added so far. uunnaammbbiigguuoouussccuurrssoorr This gives the position the cursor would be placed at if the common prefix in the uunnaammbbiigguuoouuss key were inserted, relative to the value of that key. The cursor would be placed before the character whose index is given by this key. uunnaammbbiigguuoouussppoossiittiioonnss

This contains all positions where characters in the unam-

biguous string are missing or where the character inserted differs from at least one of the matches. The positions are given as indexes into the string given by the value of the uunnaammbbiigguuoouuss key. vvaarreedd If completion is called while editing a line using the vvaarreedd builtin, the value of this key is set to the name of the parameter given as an argument to vvaarreedd. This key is only set while a vvaarreedd command is active.

wwoorrddss This array contains the words present on the command line cur-

rently being edited. BBUUIILLTTIINN CCOOMMMMAANNDDSS

ccoommppaadddd [ -aakkqqQQffeennUUll1122CC ] [ -FF array ]

[ -PP prefix ] [ -SS suffix ]

[ -pp hidden-prefix ] [ -ss hidden-suffix ]

[ -ii ignored-prefix ] [ -II ignored-suffix ]

[ -WW file-prefix ] [ -dd array ]

[ -JJ name ] [ -VV name ] [ -XX explanation ] [ -xx message ]

[ -rr remove-chars ] [ -RR remove-func ]

[ -DD array ] [ -OO array ] [ -AA array ]

[ -EE number ]

[ -MM match-spec ] [ -- ] [ words ... ]

This builtin command can be used to add matches directly and control all the information the completion code stores with each possible match. The return value is zero if at least one match

was added and non-zero if no matches were added.

The completion code breaks the string to complete into seven fields in the order: The first field is an ignored prefix taken from the command line, the contents of the IIPPRREEFFIIXX parameter plus the string

given with the -ii option. With the -UU option, only the string

from the -ii option is used. The field is an optional pre-

fix string given with the -PP option. The field is a

string that is considered part of the match but that should not

be shown when listing completions, given with the -pp option; for

example, functions that do filename generation might specify a common path prefix this way. is the part of the match that should appear in the list of completions, i.e. one of the words given at the end of the ccoommppaadddd command line. The suffixes , and correspond to the prefixes ,

and and are given by the options -ss, -SS and -II,

respectively. The supported flags are:

-PP prefix

This gives a string to be inserted before the given words. The string given is not considered as part of the match and any shell metacharacters in it will not be quoted when the string is inserted.

-SS suffix

Like -PP, but gives a string to be inserted after the

match.

-pp hidden-prefix

This gives a string that should be inserted into the com-

mand line before the match but that should not appear in

the list of matches. Unless the -UU option is given, this

string must be matched as part of the string on the com-

mand line.

-ss hidden-suffix

Like `-pp', but gives a string to insert after the match.

-ii ignored-prefix

This gives a string to insert into the command line just

before any string given with the `-PP' option. Without

`-PP' the string is inserted before the string given with

`-pp' or directly before the match.

-II ignored-suffix

Like -ii, but gives an ignored suffix.

-aa With this flag the words are taken as names of arrays and

the possible matches are their values. If only some ele-

ments of the arrays are needed, the words may also con-

tain subscripts, as in `ffoooo[[22,,-11]]'.

-kk With this flag the words are taken as names of associa-

tive arrays and the possible matches are their keys. As

for -aa, the words may also contain subscripts, as in

`ffoooo[[((RR))**bbaarr**]]'.

-dd array

This adds per-match display strings. The array should

contain one element per word given. The completion code will then display the first element instead of the first word, and so on. The array may be given as the name of an

array parameter or directly as a space-separated list of

words in parentheses.

If there are fewer display strings than words, the left-

over words will be displayed unchanged and if there are more display strings than words, the leftover display strings will be silently ignored.

-ll This option only has an effect if used together with the

-dd option. If it is given, the display strings are listed

one per line, not arrayed in columns.

-JJ name

Gives the name of the group of matches the words should be stored in.

-VV name

Like -JJ but naming a unsorted group. These are in a dif-

ferent name space than groups created with the -JJ flag.

-11 If given together with the -VV option, makes only consecu-

tive duplicates in the group be removed. If combined with

the -JJ option, this has no visible effect. Note that

groups with and without this flag are in different name spaces.

-22 If given together with the -JJ or -VV option, makes all

duplicates be kept. Again, groups with and without this flag are in different name spaces.

-XX explanation

The explanation string will be printed with the list of matches, above the group currently selected.

-xx message

Like -XX, but the message will be printed even if there

are no matches in the group.

-qq The suffix given with -SS will be automatically removed if

the next character typed is a blank or does not insert anything, or if the suffix consists of only one character and the next character typed is the same character.

-rr remove-chars

This is a more versatile form of the -qq option. The suf-

fix given with -SS or the slash automatically added after

completing directories will be automatically removed if the next character typed inserts one of the characters

given in the remove-chars. This string is parsed as a

characters class and understands the backslash sequences

used by the pprriinntt command. For example, `-rr ""aa-zz\\tt""'

removes the suffix if the next character typed inserts a

lowercase character or a TAB, and `-rr ""^^00-99""' removes the

suffix if the next character typed inserts anything but a digit. One extra backslash sequence is understood in this

string: `\\-' stands for all characters that insert noth-

ing. Thus `-SS ""=="" -qq' is the same as `-SS ""=="" -rr ""==

\\tt\\nn\\-""'.

This option may also be used without the -SS option; then

any automatically added space will be removed when one of the characters in the list is typed.

-RR remove-func

This is another form of the -rr option. When a suffix has

been inserted and the completion accepted, the function

remove-func will be called after the next character

typed. It is passed the length of the suffix as an argu-

ment and can use the special parameters available in

ordinary (non-completion) zle widgets (see zshzle(1)) to

analyse and modify the command line.

-ff If this flag is given, all of the matches built from

words are marked as being the names of files. They are not required to be actual filenames, but if they are, and the option LLIISSTTTTYYPPEESS is set, the characters describing the types of the files in the completion lists will be shown. This also forces a slash to be added when the name of a directory is completed.

-ee This flag can be used to tell the completion code that

the matches added are parameter names for a parameter expansion. This will make the AAUUTTOOPPAARRAAMMSSLLAASSHH and AAUUTTOOPPAARRAAMMKKEEYYSS options be used for the matches.

-WW file-prefix

This string is a pathname that will be prepended to each of the matches formed by the given words together with

any prefix specified by the -pp option to form a complete

filename for testing. Hence it is only useful if com-

bined with the -ff flag, as the tests will not otherwise

be performed.

-FF array

Specifies an array containing patterns. Words matching one of these patterns are ignored, i.e. not considered to be possible matches. The array may be the name of an array parameter or a list of literal patterns enclosed in parentheses and quoted,

as in `-FF ""((**??..oo **??..hh))""'. If the name of an array is

given, the elements of the array are taken as the pat-

terns.

-QQ This flag instructs the completion code not to quote any

metacharacters in the words when inserting them into the command line.

-MM match-spec

This gives local match specifications as described below in the section `Matching Control'. This option may be

given more than once. In this case all match-specs given

are concatenated with spaces between them to form the specification string to use. Note that they will only be

used if the -UU option is not given.

-nn Specifies that the words added are to be used as possible

matches, but are not to appear in the completion listing.

-UU If this flag is given, all words given will be accepted

and no matching will be done by the completion code. Nor-

mally this is used in functions that do the matching themselves.

-OO array

If this option is given, the words are not added to the set of possible completions. Instead, matching is done as usual and all of the words given as arguments that match the string on the command line will be stored in the array parameter whose name is given as array.

-AA array

As the -OO option, except that instead of those of the

words which match being stored in array, the strings gen-

erated internally by the completion code are stored. For

example, with a matching specification of `-MM ""LL::||nnoo==""',

the string `nnooff' on the command line and the string `ffoooo' as one of the words, this option stores the string

`nnooffoooo' in the array, whereas the -OO option stores the

`ffoooo' originally given.

-DD array

As with -OO, the words are not added to the set of possi-

ble completions. Instead, the completion code tests whether each word in turn matches what is on the line. If the n'th word does not match, the n'th element of the array is removed. Elements for which the corresponding word is matched are retained.

-CC This option adds a special match which expands to all

other matches when inserted into the line, even those that are added after this option is used. Together with

the -dd option it is possible to specify a string that

should be displayed in the list for this special match.

If no string is given, it will be shown as a string con-

taining the strings that would be inserted for the other matches, truncated to the width of the screen.

-EE This option adds number empty matches after the words

have been added. An empty match takes up space in com-

pletion listings but will never be inserted in the line

and can't be selected with menu completion or menu selec-

tion. This makes empty matches only useful to format completion lists and to make explanatory string be shown in completion lists (since empty matches can be given

display strings with the -dd option). And because all but

one empty string would otherwise be removed, this option

implies the -VV and -22 options (even if an explicit -JJ

option is given).

-- This flag ends the list of flags and options. All argu-

ments after it will be taken as the words to use as matches even if they begin with hyphens.

Except for the -MM flag, if any of these flags is given more than

once, the first one (and its argument) will be used.

ccoommppsseett -pp number

ccoommppsseett -PP [ number ] pattern

ccoommppsseett -ss number

ccoommppsseett -SS [ number ] pattern

ccoommppsseett -nn begin [ end ]

ccoommppsseett -NN beg-pat [ end-pat ]

ccoommppsseett -qq

This command simplifies modification of the special parameters, while its return value allows tests on them to be carried out. The options are:

-pp number

If the contents of the PPRREEFFIIXX parameter is longer than number characters, the first number characters are removed from it and appended to the contents of the IIPPRREEFFIIXX parameter.

-PP [ number ] pattern

If the value of the PPRREEFFIIXX parameter begins with anything that matches the pattern, the matched portion is removed from PPRREEFFIIXX and appended to IIPPRREEFFIIXX. Without the optional number, the longest match is taken, but if number is given, anything up to the number'th match is moved. If the number is negative, the number'th longest match is moved. For example, if PPRREEFFIIXX contains

the string `aa==bb==cc', then ccoommppsseett -PP ''**\\=='' will move the

string `aa==bb==' into the IIPPRREEFFIIXX parameter, but ccoommppsseett -PP

11 ''**\\=='' will move only the string `aa=='.

-ss number

As -pp, but transfer the last number characters from the

value of SSUUFFFFIIXX to the front of the value of IISSUUFFFFIIXX.

-SS [ number ] pattern

As -PP, but match the last portion of SSUUFFFFIIXX and transfer

the matched portion to the front of the value of IISSUUFFFFIIXX.

-nn begin [ end ]

If the current word position as specified by the parame-

ter CCUURRRREENNTT is greater than or equal to begin, anything up to the begin'th word is removed from the wwoorrddss array and the value of the parameter CCUURRRREENNTT is decremented by begin. If the optional end is given, the modification is done only if the current word position is also less than or equal to end. In this case, the words from position end onwards are also removed from the wwoorrddss array. Both begin and end may be negative to count backwards from the last element of the wwoorrddss array.

-NN beg-pat [ end-pat ]

If one of the elements of the wwoorrddss array before the one at the index given by the value of the parameter CCUURRRREENNTT

matches the pattern beg-pat, all elements up to and

including the matching one are removed from the wwoorrddss array and the value of CCUURRRREENNTT is changed to point to the same word in the changed array.

If the optional pattern end-pat is also given, and there

is an element in the wwoorrddss array matching this pattern, the parameters are modified only if the index of this

word is higher than the one given by the CCUURRRREENNTT parame-

ter (so that the matching word has to be after the cur-

sor). In this case, the words starting with the one

matching eenndd-ppaatt are also removed from the wwoorrddss array.

If wwoorrddss contains no word matching end-pat, the testing

and modification is performed as if it were not given.

-qq The word currently being completed is split on spaces

into separate words, respecting the usual shell quoting conventions. The resulting words are stored in the wwoorrddss

array, and CCUURRRREENNTT, PPRREEFFIIXX, SSUUFFFFIIXX, QQIIPPRREEFFIIXX, and QQIISSUUFF-

FFIIXX are modified to reflect the word part that is com-

pleted.

In all the above cases the return value is zero if the test suc-

ceeded and the parameters were modified and non-zero otherwise.

This allows one to use this builtin in tests such as:

iiff ccoommppsseett -PP ''**\\=='';; tthheenn ......

This forces anything up to and including the last equal sign to be ignored by the completion code.

ccoommppccaallll [ -TTDD ]

This allows the use of completions defined with the ccoommppccttll builtin from within completion widgets. The list of matches

will be generated as if one of the non-widget completion func-

tion (ccoommpplleettee-wwoorrdd, etc.) had been called, except that only

ccoommppccttlls given for specific commands are used. To force the code

to try completions defined with the -TT option of ccoommppccttll and/or

the default completion (whether defined by ccoommppccttll -DD or the

builtin default) in the appropriate places, the -TT and/or -DD

flags can be passed to ccoommppccaallll.

The return value can be used to test if a matching ccoommppccttll defi-

nition was found. It is non-zero if a ccoommppccttll was found and zero

otherwise. Note that this builtin is defined by the zzsshh//ccoommppccttll module. CCOONNDDIITTIIOONN CCOODDEESS The following additional condition codes for use within the [[[[ ...... ]]]]

construct are available in completion widgets. These work on the spe-

cial parameters. All of these tests can also be performed by the ccoommppsseett builtin, but in the case of the condition codes the contents of the special parameters are not modified.

-pprreeffiixx [ number ] pattern

true if the test for the -PP option of ccoommppsseett would succeed.

-ssuuffffiixx [ number ] pattern

true if the test for the -SS option of ccoommppsseett would succeed.

-aafftteerr beg-pat

true if the test of the -NN option with only the beg-pat given

would succeed.

-bbeettwweeeenn beg-pat end-pat

true if the test for the -NN option with both patterns would suc-

ceed. MMAATTCCHHIINNGG CCOONNTTRROOLL

It is possible by use of the -MM option of the ccoommppaadddd builtin command

to specify how the characters in the string to be completed (referred to here as the command line) map onto the characters in the list of matches produced by the completion code (referred to here as the trial completions). Note that this is not used if the command line contains a glob pattern and the GGLLOOBBCCOOMMPPLLEETTEE option is set or the ppaatttteerrnnmmaattcchh

of the ccoommppssttaattee special association is set to a non-empty string.

The match-spec given as the argument to the -MM option (see `Builtin

Commands' above) consists of one or more matching descriptions sepa-

rated by whitespace. Each description consists of a letter followed by a colon and then the patterns describing which character sequences on the line match which character sequences in the trial completion. Any sequence of characters not handled in this fashion must match exactly, as usual.

The forms of match-spec understood are as follows. In each case, the

form with an uppercase initial character retains the string already typed on the command line as the final result of completion, while with a lowercase initial character the string on the command line is changed into the corresponding part of the trial completion. mm::lpat==tpat MM::lpat==tpat

Here, lpat is a pattern that matches on the command line, corre-

sponding to tpat which matches in the trial completion. ll::lanchor||lpat==tpat LL::lanchor||lpat==tpat ll::lanchor||||ranchor==tpat LL::lanchor||||ranchor==tpat bb::lpat==tpat BB::lpat==tpat

These letters are for patterns that are anchored by another pat-

tern on the left side. Matching for lpat and tpat is as for mm and MM, but the pattern lpat matched on the command line must be preceded by the pattern lanchor. The lanchor can be blank to

anchor the match to the start of the command line string; other-

wise the anchor can occur anywhere, but must match in both the command line and trial completion strings. If no lpat is given but a ranchor is, this matches the gap

between substrings matched by lanchor and ranchor. Unlike lan-

chor, the ranchor only needs to match the trial completion string. The bb and BB forms are similar to ll and LL with an empty anchor, but need to match only the beginning of the trial completion or the word on the command line, respectively. rr::lpat||ranchor==tpat RR::lpat||ranchor==tpat rr::lanchor||||ranchor==tpat RR::lanchor||||ranchor==tpat ee::lpat==tpat EE::lpat==tpat As ll, LL, bb and BB, with the difference that the command line and trial completion patterns are anchored on the right side. Here an empty ranchor and the ee and EE forms force the match to the end of the trial completion or command line string. Each lpat, tpat or anchor is either an empty string or consists of a sequence of literal characters (which may be quoted with a backslash), question marks, character classes, and correspondence classes; ordinary shell patterns are not used. Literal characters match only themselves, question marks match any character, and character classes are formed as for globbing and match any character in the given set. Correspondence classes are defined like character classes, but with two differences: they are delimited by a pair of braces, and negated classes are not allowed, so the characters !! and ^^ have no special meaning directly after the opening brace. They indicate that a range

of characters on the line match a range of characters in the trial com-

pletion, but (unlike ordinary character classes) paired according to the corresponding position in the sequence. For example, to make any lowercase letter on the line match the corresponding uppercase letter

in the trial completion, you can use `mm::{{aa-zz}}=={{AA-ZZ}}'. More than one

pair of classes can occur, in which case the first class before the == corresponds to the first after it, and so on. If one side has more such classes than the other side, the superfluous classes behave like normal character classes. In anchor patterns correspondence classes also behave like normal character classes. The pattern tpat may also be one or two stars, `**' or `****'. This means that the pattern on the command line can match any number of characters in the trial completion. In this case the pattern must be anchored (on either side); in the case of a single star, the anchor then determines

how much of the trial completion is to be included -- only the charac-

ters up to the next appearance of the anchor will be matched. With two stars, substrings matched by the anchor can be matched, too. Examples: The keys of the ooppttiioonnss association defined by the ppaarraammeetteerr module are

the option names in all-lowercase form, without underscores, and with-

out the optional nnoo at the beginning even though the builtins sseettoopptt

and uunnsseettoopptt understand option names with uppercase letters, under-

scores, and the optional nnoo. The following alters the matching rules so that the prefix nnoo and any underscore are ignored when trying to match the trial completions generated and uppercase letters on the line match the corresponding lowercase letters in the words:

ccoommppaadddd -MM ''LL::||[[nnNN]][[ooOO]]== MM::== MM::{{AA-ZZ}}=={{aa-zz}}'' - \\

$${{((kk))ooppttiioonnss}}

The first part says that the pattern `[[nnNN]][[ooOO]]' at the beginning (the empty anchor before the pipe symbol) of the string on the line matches the empty string in the list of words generated by completion, so it

will be ignored if present. The second part does the same for an under-

score anywhere in the command line string, and the third part uses cor-

respondence classes so that any uppercase letter on the line matches

the corresponding lowercase letter in the word. The use of the upper-

case forms of the specification characters (LL and MM) guarantees that

what has already been typed on the command line (in particular the pre-

fix nnoo) will not be deleted. Note that the use of LL in the first part means that it matches only when at the beginning of both the command line string and the trial completion. I.e., the string `NNOOff' would not be completed to `NNOOffoooo', nor would `NNOONNOOff' be completed to `NNOONNOOffoooo' because of the

leading underscore or the second `NNOO' on the line which makes the pat-

tern fail even though they are otherwise ignored. To fix this, one would use `BB::[[nnNN]][[ooOO]]==' instead of the first part. As described above, this matches at the beginning of the trial completion, independent of other characters or substrings at the beginning of the command line

word which are ignored by the same or other match-specs.

The second example makes completion case insensitive. This is just the

same as in the option example, except here we wish to retain the char-

acters in the list of completions:

ccoommppaadddd -MM ''mm::{{aa-zz}}=={{AA-ZZ}}'' ......

This makes lowercase letters match their uppercase counterparts. To make uppercase letters match the lowercase forms as well:

ccoommppaadddd -MM ''mm::{{aa-zzAA-ZZ}}=={{AA-ZZaa-zz}}'' ......

A nice example for the use of ** patterns is partial word completion. Sometimes you would like to make strings like `cc..ss..uu' complete to

strings like `ccoommpp..ssoouurrccee..uunniixx', i.e. the word on the command line con-

sists of multiple parts, separated by a dot in this example, where each

part should be completed separately -- note, however, that the case

where each part of the word, i.e. `ccoommpp', `ssoouurrccee' and `uunniixx' in this

example, is to be completed from separate sets of matches is a differ-

ent problem to be solved by the implementation of the completion wid-

get. The example can be handled by:

ccoommppaadddd -MM ''rr::||..==** rr::||==**'' \\

- ccoommpp..ssoouurrcceess..uunniixx ccoommpp..ssoouurrcceess..mmiisscc ......

The first specification says that lpat is the empty string, while anchor is a dot; tpat is **, so this can match anything except for the `..' from the anchor in the trial completion word. So in `cc..ss..uu', the matcher sees `cc', followed by the empty string, followed by the anchor `..', and likewise for the second dot, and replaces the empty strings before the anchors, giving `cc[oommpp]..ss[oouurrcceess]..uu[nniixx]', where the last part of the completion is just as normal. With the pattern shown above, the string `cc..uu' could not be completed to `ccoommpp..ssoouurrcceess..uunniixx' because the single star means that no dot (matched by the anchor) can be skipped. By using two stars as in `rr::||..==****', however, `cc..uu' could be completed to `ccoommpp..ssoouurrcceess..uunniixx'. This also shows that in some cases, especially if the anchor is a real pattern, like a character class, the form with two stars may result in more matches than one would like. The second specification is needed to make this work when the cursor is

in the middle of the string on the command line and the option CCOOMM-

PPLLEETTEEIINNWWOORRDD is set. In this case the completion code would normally try to match trial completions that end with the string as typed so far, i.e. it will only insert new characters at the cursor position rather then at the end. However in our example we would like the code to recognise matches which contain extra characters after the string on the line (the `nniixx' in the example). Hence we say that the empty string at the end of the string on the line matches any characters at the end of the trial completion. More generally, the specification

ccoommppaadddd -MM ''rr::||[[..,,-]]==** rr::||==**'' ......

allows one to complete words with abbreviations before any of the char-

acters in the square brackets. For example, to complete vveerryyvveerryylloonngg-

ffiillee..cc rather than vveerryyvveerryylloonngghheeaaddeerr..hh with the above in effect, you can just type vveerryy..cc before attempting completion. The specifications with both a left and a right anchor are useful to complete partial words whose parts are not separated by some special character. For example, in some places strings have to be completed that are formed `LLiikkeeTThhiiss' (i.e. the separate parts are determined by a leading uppercase letter) or maybe one has to complete strings with trailing numbers. Here one could use the simple form with only one anchor as in:

ccoommppaadddd -MM ''rr::||[[AA-ZZ00-99]]==** rr::||==**'' LLiikkeeTTHHIISS FFooooHHoooo 55ffoooo112233 55bbaarr223344

But with this, the string `HH' would neither complete to `FFooooHHoooo' nor to `LLiikkeeTTHHIISS' because in each case there is an uppercase letter before the `HH' and that is matched by the anchor. Likewise, a `22' would not be completed. In both cases this could be changed by using

`rr::||[[AA-ZZ00-99]]==****', but then `HH' completes to both `LLiikkeeTTHHIISS' and

`FFooooHHoooo' and a `22' matches the other strings because characters can be inserted before every uppercase letter and digit. To avoid this one would use:

ccoommppaadddd -MM ''rr::[[^^AA-ZZ00-99]]||||[[AA-ZZ00-99]]==**** rr::||==**'' \\

LLiikkeeTTHHIISS FFooooHHoooo ffoooo112233 bbaarr223344 By using these two anchors, a `HH' matches only uppercase `HH's that are

immediately preceded by something matching the left anchor `[[^^AA-ZZ00-99]]'.

The effect is, of course, that `HH' matches only the string `FFooooHHoooo', a `22' matches only `bbaarr223344' and so on. When using the completion system (see zshcompsys(1)), users can define match specifications that are to be used for specific contexts by using

the mmaattcchheerr and mmaattcchheerr-lliisstt styles. The values for the latter will be

used everywhere. CCOOMMPPLLEETTIIOONN WWIIDDGGEETT EEXXAAMMPPLLEE The first step is to define the widget:

zzllee -CC ccoommpplleettee ccoommpplleettee-wwoorrdd ccoommpplleettee-ffiilleess

Then the widget can be bound to a key using the bbiinnddkkeeyy builtin com-

mand: bbiinnddkkeeyy ''^^XX\\tt'' ccoommpplleettee

After that the shell function ccoommpplleettee-ffiilleess will be invoked after typ-

ing control-X and TAB. The function should then generate the matches,

e.g.:

ccoommpplleettee-ffiilleess (()) {{ ccoommppaadddd - ** }}

This function will complete files in the current directory matching the current word. zsh 4.2.3 January 13, 2005 ZSHCOMPWID(1)