1ZSHCOMPWID(1)               General Commands Manual              ZSHCOMPWID(1)
2
3
4

NAME

6       zshcompwid - zsh completion widgets
7

DESCRIPTION

9       The shell's programmable completion mechanism can be manipulated in two
10       ways; here the low-level features supporting the newer,  function-based
11       mechanism  are  defined.   A  complete  set of shell functions based on
12       these features is described in zshcompsys(1), and users with no  inter‐
13       est in adding to that system (or, potentially, writing their own -- see
14       dictionary entry for `hubris') should skip the  current  section.   The
15       older  system based on the compctl builtin command is described in zsh‐
16       compctl(1).
17
18       Completion widgets are defined by the -C option to the zle builtin com‐
19       mand provided by the zsh/zle module (see zshzle(1)). For example,
20
21              zle -C complete expand-or-complete completer
22
23       defines  a widget named `complete'.  The second argument is the name of
24       any of the builtin  widgets  that  handle  completions:  complete-word,
25       expand-or-complete,      expand-or-complete-prefix,      menu-complete,
26       menu-expand-or-complete,   reverse-menu-complete,   list-choices,    or
27       delete-char-or-list.  Note that this will still work even if the widget
28       in question has been re-bound.
29
30       When this newly defined widget is bound to  a  key  using  the  bindkey
31       builtin  command  defined in the zsh/zle module (see zshzle(1)), typing
32       that key will call the shell function  `completer'.  This  function  is
33       responsible  for  generating  the  possible  matches using the builtins
34       described below.  As with other ZLE widgets,  the  function  is  called
35       with its standard input closed.
36
37       Once the function returns, the completion code takes over control again
38       and treats the matches in the same manner as the specified builtin wid‐
39       get, in this case expand-or-complete.
40

COMPLETION SPECIAL PARAMETERS

42       The  parameters  ZLE_REMOVE_SUFFIX_CHARS and ZLE_SPACE_SUFFIX_CHARS are
43       used by the completion mechanism, but are not special.  See  Parameters
44       Used By The Shell in zshparam(1).
45
46       Inside  completion  widgets,  and  any functions called from them, some
47       parameters have special meaning; outside these functions they  are  not
48       special  to  the  shell  in any way.  These parameters are used to pass
49       information between the completion code and the completion widget. Some
50       of  the builtin commands and the condition codes use or change the cur‐
51       rent values of these parameters.  Any existing values  will  be  hidden
52       during  execution  of  completion  widgets;  except  for compstate, the
53       parameters are reset on each function exit (including  nested  function
54       calls  from  within  the completion widget) to the values they had when
55       the function was entered.
56
57       CURRENT
58              This is the number of the current word, i.e. the word the cursor
59              is  currently  on  in  the words array.  Note that this value is
60              only correct if the ksharrays option is not set.
61
62       IPREFIX
63              Initially this will be set to the empty string.  This  parameter
64              functions  like  PREFIX; it contains a string which precedes the
65              one in PREFIX and is not considered part of the list of matches.
66              Typically,  a string is transferred from the beginning of PREFIX
67              to the end of IPREFIX, for example:
68
69                     IPREFIX=${PREFIX%%\=*}=
70                     PREFIX=${PREFIX#*=}
71
72              causes the part of the prefix up  to  and  including  the  first
73              equal  sign not to be treated as part of a matched string.  This
74              can be done automatically by the compset builtin, see below.
75
76       ISUFFIX
77              As IPREFIX, but for a suffix that should not be considered  part
78              of  the matches; note that the ISUFFIX string follows the SUFFIX
79              string.
80
81       PREFIX Initially this will be set to the part of the current word  from
82              the  beginning  of the word up to the position of the cursor; it
83              may be altered to give a common prefix for all matches.
84
85       QIPREFIX
86              This parameter is read-only and contains the quoted string up to
87              the  word  being  completed.  E.g.  when completing `"foo', this
88              parameter contains the double quote. If the -q option of compset
89              is used (see below), and the original string was `"foo bar' with
90              the cursor on the `bar', this parameter contains `"foo '.
91
92       QISUFFIX
93              Like QIPREFIX, but containing the suffix.
94
95       SUFFIX Initially this will be set to the part of the current word  from
96              the cursor position to the end; it may be altered to give a com‐
97              mon suffix for all matches.  It is most useful when  the  option
98              COMPLETE_IN_WORD is set, as otherwise the whole word on the com‐
99              mand line is treated as a prefix.
100
101       compstate
102              This is an associative array with various keys and  values  that
103              the  completion  code uses to exchange information with the com‐
104              pletion widget.  The keys are:
105
106              all_quotes
107                     The -q option of the compset builtin command (see  below)
108                     allows  a quoted string to be broken into separate words;
109                     if the cursor is on one of those words, that word will be
110                     completed,  possibly  invoking  `compset -q' recursively.
111                     With this key it is possible to test the types of  quoted
112                     strings  which  are  currently  broken into parts in this
113                     fashion.  Its value contains one character for each quot‐
114                     ing level.  The characters are a single quote or a double
115                     quote for strings quoted with these characters, a dollars
116                     sign  for  strings quoted with $'...' and a backslash for
117                     strings not starting with a quote character.   The  first
118                     character  in  the value always corresponds to the inner‐
119                     most quoting level.
120
121              context
122                     This will be set by the completion code  to  the  overall
123                     context in which completion is attempted. Possible values
124                     are:
125
126                     array_value
127                            when completing  inside  the  value  of  an  array
128                            parameter assignment; in this case the words array
129                            contains the words inside the parentheses.
130
131                     brace_parameter
132                            when completing the  name  of  a  parameter  in  a
133                            parameter  expansion beginning with ${.  This con‐
134                            text will also be set  when  completing  parameter
135                            flags  following  ${(; the full command line argu‐
136                            ment is presented and the handler  must  test  the
137                            value  to  be  completed to ascertain that this is
138                            the case.
139
140                     assign_parameter
141                            when completing the  name  of  a  parameter  in  a
142                            parameter assignment.
143
144                     command
145                            when  completing  for  a normal command (either in
146                            command position or for an argument  of  the  com‐
147                            mand).
148
149                     condition
150                            when  completing  inside  a  `[[...]]' conditional
151                            expression; in this case the words array  contains
152                            only the words inside the conditional expression.
153
154                     math   when completing in a mathematical environment such
155                            as a `((...))' construct.
156
157                     parameter
158                            when completing the  name  of  a  parameter  in  a
159                            parameter expansion beginning with $ but not ${.
160
161                     redirect
162                            when completing after a redirection operator.
163
164                     subscript
165                            when completing inside a parameter subscript.
166
167                     value  when  completing  the value of a parameter assign‐
168                            ment.
169
170              exact  Controls the behaviour when the REC_EXACT option is  set.
171                     It  will  be  set  to  accept  if an exact match would be
172                     accepted, and will be unset otherwise.
173
174                     If it was set when at least one match equal to the string
175                     on the line was generated, the match is accepted.
176
177              exact_string
178                     The  string of an exact match if one was found, otherwise
179                     unset.
180
181              ignored
182                     The number  of  words  that  were  ignored  because  they
183                     matched  one  of the patterns given with the -F option to
184                     the compadd builtin command.
185
186              insert This controls the manner in which  a  match  is  inserted
187                     into  the command line.  On entry to the widget function,
188                     if it is unset the command line is not to be changed;  if
189                     set  to  unambiguous, any prefix common to all matches is
190                     to be inserted; if set to automenu-unambiguous, the  com‐
191                     mon  prefix  is to be inserted and the next invocation of
192                     the completion code may start menu completion (due to the
193                     AUTO_MENU  option  being set); if set to menu or automenu
194                     menu completion will be started for the matches currently
195                     generated  (in  the  latter case this will happen because
196                     the AUTO_MENU is set). The value  may  also  contain  the
197                     string  `tab' when the completion code would normally not
198                     really do completion, but only insert the TAB character.
199
200                     On exit it may be set to any of the values  above  (where
201                     setting  it  to the empty string is the same as unsetting
202                     it), or to a number, in which case the match whose number
203                     is  given  will be inserted into the command line.  Nega‐
204                     tive numbers count backward from  the  last  match  (with
205                     `-1'  selecting  the  last match) and out-of-range values
206                     are wrapped around, so that a value of zero  selects  the
207                     last  match and a value one more than the maximum selects
208                     the first. Unless the value of this key ends in a  space,
209                     the match is inserted as in a menu completion, i.e. with‐
210                     out automatically appending a space.
211
212                     Both menu and automenu may also specify the number of the
213                     match  to  insert,  given  after  a  colon.  For example,
214                     `menu:2' says to start menu  completion,  beginning  with
215                     the second match.
216
217                     Note  that  a  value containing the substring `tab' makes
218                     the matches generated be ignored  and  only  the  TAB  be
219                     inserted.
220
221                     Finally,  it  may  also  be  set  to all, which makes all
222                     matches generated be inserted into the line.
223
224              insert_positions
225                     When the completion system inserts an unambiguous  string
226                     into the line, there may be multiple places where charac‐
227                     ters are missing or where the character inserted  differs
228                     from  at least one match.  The value of this key contains
229                     a colon separated list of all these positions, as indexes
230                     into the command line.
231
232              last_prompt
233                     If  this  is  set  to  a non-empty string for every match
234                     added, the completion code will move the cursor  back  to
235                     the  previous  prompt  after  the list of completions has
236                     been displayed.  Initially this is set or unset according
237                     to the ALWAYS_LAST_PROMPT option.
238
239              list   This  controls whether or how the list of matches will be
240                     displayed.  If it is unset or empty they  will  never  be
241                     listed;  if  its value begins with list, they will always
242                     be listed; if it begins with autolist or ambiguous,  they
243                     will  be  listed  when  the  AUTO_LIST  or LIST_AMBIGUOUS
244                     options respectively would normally cause them to be.
245
246                     If the substring force appears in the value,  this  makes
247                     the  list  be shown even if there is only one match. Nor‐
248                     mally, the list would be shown only if there are at least
249                     two matches.
250
251                     The   value   contains   the   substring  packed  if  the
252                     LIST_PACKED option is set. If this substring is given for
253                     all  matches  added  to a group, this group will show the
254                     LIST_PACKED  behavior.  The  same   is   done   for   the
255                     LIST_ROWS_FIRST option with the substring rows.
256
257                     Finally,  if  the value contains the string explanations,
258                     only the explanation strings, if any, will be listed  and
259                     if  it  contains  messages, only the messages (added with
260                     the -x option of compadd) will be listed.  If it contains
261                     both  explanations and messages both kinds of explanation
262                     strings will be listed.  It will be set appropriately  on
263                     entry to a completion widget and may be changed there.
264
265              list_lines
266                     This gives the number of lines that are needed to display
267                     the full list of completions.  Note that to calculate the
268                     total number of lines to display you need to add the num‐
269                     ber of lines needed for the command line to  this  value,
270                     this is available as the value of the BUFFERLINES special
271                     parameter.
272
273              list_max
274                     Initially this is set to the value of the LISTMAX parame‐
275                     ter.   It  may be set to any other value; when the widget
276                     exits this value will be used in  the  same  way  as  the
277                     value of LISTMAX.
278
279              nmatches
280                     The  number of matches generated and accepted by the com‐
281                     pletion code so far.
282
283              old_insert
284                     On entry to the widget this will be set to the number  of
285                     the match of an old list of completions that is currently
286                     inserted into the command line.  If  no  match  has  been
287                     inserted, this is unset.
288
289                     As with old_list, the value of this key will only be used
290                     if it is the string keep. If it was set to this value  by
291                     the  widget  and there was an old match inserted into the
292                     command line, this match will be kept and if the value of
293                     the  insert  key  specifies  that another match should be
294                     inserted, this will be inserted after the old one.
295
296              old_list
297                     This is set to yes if there is still a valid list of com‐
298                     pletions  from a previous completion at the time the wid‐
299                     get is invoked.  This will usually be  the  case  if  and
300                     only  if  the previous editing operation was a completion
301                     widget or one of the builtin  completion  functions.   If
302                     there  is  a valid list and it is also currently shown on
303                     the screen, the value of this key is shown.
304
305                     After the widget has exited the value of this key is only
306                     used  if it was set to keep.  In this case the completion
307                     code will continue to use this old list.  If  the  widget
308                     generated new matches, they will not be used.
309
310              parameter
311                     The  name of the parameter when completing in a subscript
312                     or in the value of a parameter assignment.
313
314              pattern_insert
315                     Normally this is set to menu, which specifies  that  menu
316                     completion  will  be  used  whenever a set of matches was
317                     generated using pattern matching.  If it is  set  to  any
318                     other non-empty string by the user and menu completion is
319                     not selected by other  option  settings,  the  code  will
320                     instead  insert  any  common  prefix  for  the  generated
321                     matches as with normal completion.
322
323              pattern_match
324                     Locally controls the behaviour given by the GLOB_COMPLETE
325                     option.   Initially  it  is set to `*' if and only if the
326                     option is set.  The completion widget may set it to  this
327                     value,  to  an empty string (which has the same effect as
328                     unsetting it), or to any other non-empty string.   If  it
329                     is non-empty, unquoted metacharacters on the command line
330                     will be treated as patterns; if it is `*', then addition‐
331                     ally a wildcard `*' is assumed at the cursor position; if
332                     it is empty or unset, metacharacters will be treated lit‐
333                     erally.
334
335                     Note that the matcher specifications given to the compadd
336                     builtin command  are  not  used  if  this  is  set  to  a
337                     non-empty string.
338
339              quote  When  completing  inside quotes, this contains the quota‐
340                     tion character (i.e. either  a  single  quote,  a  double
341                     quote, or a backtick).  Otherwise it is unset.
342
343              quoting
344                     When  completing inside single quotes, this is set to the
345                     string single; inside double quotes, the  string  double;
346                     inside  backticks,  the string backtick.  Otherwise it is
347                     unset.
348
349              redirect
350                     The redirection operator when completing in a redirection
351                     position, i.e. one of <, >, etc.
352
353              restore
354                     This  is  set to auto before a function is entered, which
355                     forces the special  parameters  mentioned  above  (words,
356                     CURRENT,  PREFIX,  IPREFIX,  SUFFIX,  and  ISUFFIX) to be
357                     restored to  their  previous  values  when  the  function
358                     exits.    If a function unsets it or sets it to any other
359                     string, they will not be restored.
360
361              to_end Specifies the occasions on which the cursor is  moved  to
362                     the  end  of a string when a match is inserted.  On entry
363                     to a widget function, it may be single if this will  hap‐
364                     pen when a single unambiguous match was inserted or match
365                     if it will happen any time a match is inserted (for exam‐
366                     ple,  by menu completion; this is likely to be the effect
367                     of the ALWAYS_TO_END option).
368
369                     On exit, it may be set to single as above.  It  may  also
370                     be  set  to  always,  or to the empty string or unset; in
371                     those cases the cursor will be moved to the  end  of  the
372                     string always or never respectively.  Any other string is
373                     treated as match.
374
375              unambiguous
376                     This key is read-only and will always be set to the  com‐
377                     mon  (unambiguous)  prefix the completion code has gener‐
378                     ated for all matches added so far.
379
380              unambiguous_cursor
381                     This gives the position the cursor would be placed at  if
382                     the  common  prefix in the unambiguous key were inserted,
383                     relative to the value of that key. The  cursor  would  be
384                     placed  before the character whose index is given by this
385                     key.
386
387              unambiguous_positions
388                     This contains all positions where characters in the unam‐
389                     biguous   string  are  missing  or  where  the  character
390                     inserted differs from at least one of the  matches.   The
391                     positions  are  given as indexes into the string given by
392                     the value of the unambiguous key.
393
394              vared  If completion is called while editing a  line  using  the
395                     vared  builtin,  the value of this key is set to the name
396                     of the parameter given as an argument to vared.  This key
397                     is only set while a vared command is active.
398
399       words  This  array  contains the words present on the command line cur‐
400              rently being edited.
401

COMPLETION BUILTIN COMMANDS

403       compadd [ -akqQfenUlo12C ] [ -F array ]
404               [-P prefix ] [ -S suffix ]
405               [-p hidden-prefix ] [ -s hidden-suffix ]
406               [-i ignored-prefix ] [ -I ignored-suffix ]
407               [-W file-prefix ] [ -d array ]
408               [-J name ] [ -V name ] [ -X explanation ] [ -x message ]
409               [-r remove-chars ] [ -R remove-func ]
410               [-D array ] [ -O array ] [ -A array ]
411               [-E number ]
412               [-M match-spec ] [ -- ] [ words ... ]
413
414              This builtin command can be used to  add  matches  directly  and
415              control all the information the completion code stores with each
416              possible match. The return status is zero if at least one  match
417              was added and non-zero if no matches were added.
418
419              The  completion  code  breaks  the string to complete into seven
420              fields in the order:
421
422                     <ipre><apre><hpre><word><hsuf><asuf><isuf>
423
424              The first field is an ignored  prefix  taken  from  the  command
425              line,  the  contents  of  the  IPREFIX parameter plus the string
426              given with the -i option. With the -U option,  only  the  string
427              from the -i option is used. The field <apre> is an optional pre‐
428              fix string given with the -P option.   The  <hpre>  field  is  a
429              string  that is considered part of the match but that should not
430              be shown when listing completions, given with the -p option; for
431              example,  functions  that do filename generation might specify a
432              common path prefix this way.  <word> is the part  of  the  match
433              that  should  appear in the list of completions, i.e. one of the
434              words given at the end of the compadd command line. The suffixes
435              <hsuf>,  <asuf>  and  <isuf>  correspond to the prefixes <hpre>,
436              <apre> and <ipre> and are given by the options -s,  -S  and  -I,
437              respectively.
438
439              The supported flags are:
440
441              -P prefix
442                     This  gives  a  string  to  be  inserted before the given
443                     words.  The string given is not considered as part of the
444                     match  and  any  shell  metacharacters  in it will not be
445                     quoted when the string is inserted.
446
447              -S suffix
448                     Like -P, but gives a string  to  be  inserted  after  the
449                     match.
450
451              -p hidden-prefix
452                     This gives a string that should be inserted into the com‐
453                     mand line before the match but that should not appear  in
454                     the  list of matches. Unless the -U option is given, this
455                     string must be matched as part of the string on the  com‐
456                     mand line.
457
458              -s hidden-suffix
459                     Like `-p', but gives a string to insert after the match.
460
461              -i ignored-prefix
462                     This  gives a string to insert into the command line just
463                     before any string given with the  `-P'  option.   Without
464                     `-P'  the string is inserted before the string given with
465                     `-p' or directly before the match.
466
467              -I ignored-suffix
468                     Like -i, but gives an ignored suffix.
469
470              -a     With this flag the words are taken as names of arrays and
471                     the possible matches are their values.  If only some ele‐
472                     ments of the arrays are needed, the words may  also  con‐
473                     tain subscripts, as in `foo[2,-1]'.
474
475              -k     With  this  flag the words are taken as names of associa‐
476                     tive arrays and the possible matches are their keys.   As
477                     for  -a,  the  words  may  also contain subscripts, as in
478                     `foo[(R)*bar*]'.
479
480              -d array
481                     This adds per-match display  strings.  The  array  should
482                     contain  one  element per word given. The completion code
483                     will then display the first element instead of the  first
484                     word, and so on. The array may be given as the name of an
485                     array parameter or directly as a space-separated list  of
486                     words in parentheses.
487
488                     If  there are fewer display strings than words, the left‐
489                     over words will be displayed unchanged and if  there  are
490                     more  display  strings  than  words, the leftover display
491                     strings will be silently ignored.
492
493              -l     This option only has an effect if used together with  the
494                     -d option. If it is given, the display strings are listed
495                     one per line, not arrayed in columns.
496
497              -o     This option only has an effect if used together with  the
498                     -d  option.   If  it is given, the order of the output is
499                     determined by the match strings;  otherwise it is  deter‐
500                     mined  by  the display strings (i.e. the strings given by
501                     the -d option).
502
503              -J name
504                     Gives the name of the group of matches the  words  should
505                     be stored in.
506
507              -V name
508                     Like -J but naming an unsorted group. These are in a dif‐
509                     ferent name space than groups created with the -J flag.
510
511              -1     If given together with the -V option, makes only consecu‐
512                     tive duplicates in the group be removed. If combined with
513                     the -J option, this has  no  visible  effect.  Note  that
514                     groups  with  and without this flag are in different name
515                     spaces.
516
517              -2     If given together with the -J or  -V  option,  makes  all
518                     duplicates  be  kept. Again, groups with and without this
519                     flag are in different name spaces.
520
521              -X explanation
522                     The explanation string will be printed with the  list  of
523                     matches, above the group currently selected.
524
525              -x message
526                     Like  -X,  but  the message will be printed even if there
527                     are no matches in the group.
528
529              -q     The suffix given with -S will be automatically removed if
530                     the  next  character  typed is a blank or does not insert
531                     anything, or if the suffix consists of only one character
532                     and the next character typed is the same character.
533
534              -r remove-chars
535                     This is a more versatile form of the -q option.  The suf‐
536                     fix given with -S or the slash automatically added  after
537                     completing  directories  will be automatically removed if
538                     the next character typed inserts one  of  the  characters
539                     given  in  the  remove-chars.  This string is parsed as a
540                     characters class and understands the backslash  sequences
541                     used  by  the  print  command.  For example, `-r "a-z\t"'
542                     removes the suffix if the next character typed inserts  a
543                     lower  case  character  or a TAB, and `-r "^0-9"' removes
544                     the suffix if the next character typed  inserts  anything
545                     but  a  digit. One extra backslash sequence is understood
546                     in this string:  `\-'  stands  for  all  characters  that
547                     insert  nothing.  Thus `-S "=" -q' is the same as `-S "="
548                     -r "= \t\n\-"'.
549
550                     This option may also be used without the -S option;  then
551                     any automatically added space will be removed when one of
552                     the characters in the list is typed.
553
554              -R remove-func
555                     This is another form of the -r option. When a suffix  has
556                     been  inserted  and the completion accepted, the function
557                     remove-func will  be  called  after  the  next  character
558                     typed.  It is passed the length of the suffix as an argu‐
559                     ment and can use  the  special  parameters  available  in
560                     ordinary  (non-completion) zle widgets (see zshzle(1)) to
561                     analyse and modify the command line.
562
563              -f     If this flag is given, all  of  the  matches  built  from
564                     words  are  marked as being the names of files.  They are
565                     not required to be actual filenames, but if they are, and
566                     the  option  LIST_TYPES is set, the characters describing
567                     the types of the files in the completion  lists  will  be
568                     shown. This also forces a slash to be added when the name
569                     of a directory is completed.
570
571              -e     This flag can be used to tell the  completion  code  that
572                     the  matches  added  are  parameter names for a parameter
573                     expansion.  This  will  make  the  AUTO_PARAM_SLASH   and
574                     AUTO_PARAM_KEYS options be used for the matches.
575
576              -W file-prefix
577                     This  string is a pathname that will be prepended to each
578                     of the matches formed by the given  words  together  with
579                     any  prefix specified by the -p option to form a complete
580                     filename for testing.  Hence it is only  useful  if  com‐
581                     bined  with  the -f flag, as the tests will not otherwise
582                     be performed.
583
584              -F array
585                     Specifies an array containing  patterns.  Words  matching
586                     one of these patterns are ignored, i.e. not considered to
587                     be possible matches.
588
589                     The array may be the name of an array parameter or a list
590                     of  literal  patterns enclosed in parentheses and quoted,
591                     as in `-F "(*?.o *?.h)"'. If the  name  of  an  array  is
592                     given,  the  elements  of the array are taken as the pat‐
593                     terns.
594
595              -Q     This flag instructs the completion code not to quote  any
596                     metacharacters  in the words when inserting them into the
597                     command line.
598
599              -M match-spec
600                     This gives local match specifications as described  below
601                     in the section `Completion Matching Control'. This option
602                     may  be  given  more  than  once.   In  this   case   all
603                     match-specs  given  are  concatenated with spaces between
604                     them to form the specification string to use.  Note  that
605                     they will only be used if the -U option is not given.
606
607              -n     Specifies that the words added are to be used as possible
608                     matches, but are not to appear in the completion listing.
609
610              -U     If this flag is given, all words given will  be  accepted
611                     and no matching will be done by the completion code. Nor‐
612                     mally this is used in  functions  that  do  the  matching
613                     themselves.
614
615              -O array
616                     If  this  option is given, the words are not added to the
617                     set of possible completions.  Instead, matching  is  done
618                     as  usual  and  all  of the words given as arguments that
619                     match the string on the command line will  be  stored  in
620                     the array parameter whose name is given as array.
621
622              -A array
623                     As  the  -O  option,  except that instead of those of the
624                     words which match being stored in array, the strings gen‐
625                     erated  internally by the completion code are stored. For
626                     example, with a matching specification of `-M  "L:|no="',
627                     the string `nof' on the command line and the string `foo'
628                     as one of  the  words,  this  option  stores  the  string
629                     `nofoo'  in  the  array, whereas the -O option stores the
630                     `foo' originally given.
631
632              -D array
633                     As with -O, the words are not added to the set of  possi‐
634                     ble  completions.   Instead,  the  completion  code tests
635                     whether each word in turn matches what is  on  the  line.
636                     If  the  nth  word does not match, the nth element of the
637                     array is removed.  Elements for which  the  corresponding
638                     word is matched are retained.
639
640              -C     This  option  adds  a  special match which expands to all
641                     other matches when inserted into  the  line,  even  those
642                     that  are added after this option is used.  Together with
643                     the -d option it is possible to  specify  a  string  that
644                     should  be  displayed in the list for this special match.
645                     If no string is given, it will be shown as a string  con‐
646                     taining  the strings that would be inserted for the other
647                     matches, truncated to the width of the screen.
648
649              -E number
650                     This option adds number empty  matches  after  the  words
651                     have  been  added.  An empty match takes up space in com‐
652                     pletion listings but will never be inserted in  the  line
653                     and can't be selected with menu completion or menu selec‐
654                     tion.  This makes empty matches  only  useful  to  format
655                     completion  lists and to make explanatory string be shown
656                     in completion lists (since empty  matches  can  be  given
657                     display strings with the -d option).  And because all but
658                     one empty string would otherwise be removed, this  option
659                     implies  the  -V  and  -2 options (even if an explicit -J
660                     option is given).  This can be important to  note  as  it
661                     affects the name space into which matches are added.
662
663              -
664              --     This  flag  ends the list of flags and options. All argu‐
665                     ments after it will be taken  as  the  words  to  use  as
666                     matches even if they begin with hyphens.
667
668              Except for the -M flag, if any of these flags is given more than
669              once, the first one (and its argument) will be used.
670
671       compset -p number
672       compset -P [ number ] pattern
673       compset -s number
674       compset -S [ number ] pattern
675       compset -n begin [ end ]
676       compset -N beg-pat [ end-pat ]
677       compset -q
678              This command simplifies modification of the special  parameters,
679              while its return status allows tests on them to be carried out.
680
681              The options are:
682
683              -p number
684                     If  the  contents  of the PREFIX parameter is longer than
685                     number  characters,  the  first  number  characters   are
686                     removed  from  it  and  appended  to  the contents of the
687                     IPREFIX parameter.
688
689              -P [ number ] pattern
690                     If the value of the PREFIX parameter begins with anything
691                     that  matches the pattern, the matched portion is removed
692                     from PREFIX and appended to IPREFIX.
693
694                     Without the optional number, the longest match is  taken,
695                     but if number is given, anything up to the numberth match
696                     is moved.  If the number is negative, the numberth  long‐
697                     est  match  is moved. For example, if PREFIX contains the
698                     string `a=b=c', then  compset  -P  '*\='  will  move  the
699                     string  `a=b=' into the IPREFIX parameter, but compset -P
700                     1 '*\=' will move only the string `a='.
701
702              -s number
703                     As -p, but transfer the last number characters  from  the
704                     value of SUFFIX to the front of the value of ISUFFIX.
705
706              -S [ number ] pattern
707                     As  -P, but match the last portion of SUFFIX and transfer
708                     the matched portion to the front of the value of ISUFFIX.
709
710              -n begin [ end ]
711                     If the current word position as specified by the  parame‐
712                     ter  CURRENT  is greater than or equal to begin, anything
713                     up to the beginth word is removed from  the  words  array
714                     and  the value of the parameter CURRENT is decremented by
715                     begin.
716
717                     If the optional end is given, the  modification  is  done
718                     only  if  the  current word position is also less than or
719                     equal to end. In this case, the words from  position  end
720                     onwards are also removed from the words array.
721
722                     Both  begin  and  end  may be negative to count backwards
723                     from the last element of the words array.
724
725              -N beg-pat [ end-pat ]
726                     If one of the elements of the words array before the  one
727                     at  the index given by the value of the parameter CURRENT
728                     matches the pattern  beg-pat,  all  elements  up  to  and
729                     including  the  matching  one  are removed from the words
730                     array and the value of CURRENT is changed to point to the
731                     same word in the changed array.
732
733                     If  the optional pattern end-pat is also given, and there
734                     is an element in the words array matching  this  pattern,
735                     the  parameters  are  modified  only if the index of this
736                     word is higher than the one given by the CURRENT  parame‐
737                     ter  (so  that the matching word has to be after the cur‐
738                     sor). In this case,  the  words  starting  with  the  one
739                     matching  end-pat  are also removed from the words array.
740                     If words contains no word matching end-pat,  the  testing
741                     and modification is performed as if it were not given.
742
743              -q     The  word  currently  being  completed is split on spaces
744                     into separate words, respecting the usual  shell  quoting
745                     conventions.  The resulting words are stored in the words
746                     array, and CURRENT, PREFIX, SUFFIX, QIPREFIX, and  QISUF‐
747                     FIX  are  modified  to reflect the word part that is com‐
748                     pleted.
749
750              In all the above cases the return status is  zero  if  the  test
751              succeeded  and  the parameters were modified and non-zero other‐
752              wise. This allows one to use this builtin in tests such as:
753
754                     if compset -P '*\='; then ...
755
756              This forces anything up to and including the last equal sign  to
757              be ignored by the completion code.
758
759       compcall [ -TD ]
760              This  allows  the  use  of  completions defined with the compctl
761              builtin from within completion widgets.   The  list  of  matches
762              will  be  generated as if one of the non-widget completion func‐
763              tions (complete-word, etc.)  had been called, except  that  only
764              compctls given for specific commands are used. To force the code
765              to try completions defined with the -T option of compctl  and/or
766              the  default  completion  (whether  defined by compctl -D or the
767              builtin default) in the appropriate places,  the  -T  and/or  -D
768              flags can be passed to compcall.
769
770              The return status can be used to test if a matching compctl def‐
771              inition was found. It is non-zero if a  compctl  was  found  and
772              zero otherwise.
773
774              Note that this builtin is defined by the zsh/compctl module.
775

COMPLETION CONDITION CODES

777       The  following  additional condition codes for use within the [[ ... ]]
778       construct are available in completion widgets.  These work on the  spe‐
779       cial  parameters.   All  of  these  tests  can also be performed by the
780       compset builtin, but in the case of the condition codes the contents of
781       the special parameters are not modified.
782
783       -prefix [ number ] pattern
784              true if the test for the -P option of compset would succeed.
785
786       -suffix [ number ] pattern
787              true if the test for the -S option of compset would succeed.
788
789       -after beg-pat
790              true  if  the  test of the -N option with only the beg-pat given
791              would succeed.
792
793       -between beg-pat end-pat
794              true if the test for the -N option with both patterns would suc‐
795              ceed.
796

COMPLETION MATCHING CONTROL

798       It  is  possible by use of the -M option of the compadd builtin command
799       to specify how the characters in the string to be  completed  (referred
800       to  here  as  the  command line) map onto the characters in the list of
801       matches produced by the completion code (referred to here as the  trial
802       completions). Note that this is not used if the command line contains a
803       glob pattern and the GLOB_COMPLETE option is set or  the  pattern_match
804       of the compstate special association is set to a non-empty string.
805
806       The  match-spec given as the argument to the -M option (see `Completion
807       Builtin Commands' above) consists of one or more matching  descriptions
808       separated  by  whitespace.   Each description consists of a letter fol‐
809       lowed by a colon and  then  the  patterns  describing  which  character
810       sequences on the line match which character sequences in the trial com‐
811       pletion.  Any sequence of characters not handled in this  fashion  must
812       match exactly, as usual.
813
814       The  forms  of  match-spec understood are as follows. In each case, the
815       form with an upper case initial character retains  the  string  already
816       typed on the command line as the final result of completion, while with
817       a lower case initial character  the  string  on  the  command  line  is
818       changed into the corresponding part of the trial completion.
819
820       m:lpat=tpat
821       M:lpat=tpat
822              Here, lpat is a pattern that matches on the command line, corre‐
823              sponding to tpat which matches in the trial completion.
824
825       l:lanchor|lpat=tpat
826       L:lanchor|lpat=tpat
827       l:lanchor||ranchor=tpat
828       L:lanchor||ranchor=tpat
829       b:lpat=tpat
830       B:lpat=tpat
831              These letters are for patterns that are anchored by another pat‐
832              tern  on  the  left side. Matching for lpat and tpat is as for m
833              and M, but the pattern lpat matched on the command line must  be
834              preceded  by  the  pattern lanchor.  The lanchor can be blank to
835              anchor the match to the start of the command line string; other‐
836              wise  the  anchor can occur anywhere, but must match in both the
837              command line and trial completion strings.
838
839              If no lpat is given but a  ranchor  is,  this  matches  the  gap
840              between  substrings  matched by lanchor and ranchor. Unlike lan‐
841              chor, the ranchor only  needs  to  match  the  trial  completion
842              string.
843
844              The  b  and B forms are similar to l and L with an empty anchor,
845              but need to match only the beginning of the word on the  command
846              line or trial completion, respectively.
847
848       r:lpat|ranchor=tpat
849       R:lpat|ranchor=tpat
850       r:lanchor||ranchor=tpat
851       R:lanchor||ranchor=tpat
852       e:lpat=tpat
853       E:lpat=tpat
854              As  l, L, b and B, with the difference that the command line and
855              trial completion patterns are anchored on the right side.   Here
856              an  empty  ranchor  and the e and E forms force the match to the
857              end of the command line or trial completion string.
858
859       x:     This form is used to mark the end  of  matching  specifications:
860              subsequent  specifications  are  ignored. In a single standalone
861              list of specifications this has no use but where matching speci‐
862              fications  are  accumulated, such as from nested function calls,
863              it can allow one function to override another.
864
865       Each lpat, tpat or anchor is either an empty string or  consists  of  a
866       sequence  of literal characters (which may be quoted with a backslash),
867       question marks, character classes, and correspondence classes; ordinary
868       shell patterns are not used.  Literal characters match only themselves,
869       question marks match any character, and character classes are formed as
870       for globbing and match any character in the given set.
871
872       Correspondence classes are defined like character classes, but with two
873       differences: they are delimited  by  a  pair  of  braces,  and  negated
874       classes  are  not  allowed,  so  the characters ! and ^ have no special
875       meaning directly after the opening brace.  They indicate that  a  range
876       of characters on the line match a range of characters in the trial com‐
877       pletion, but (unlike ordinary character classes)  paired  according  to
878       the  corresponding  position in the sequence.  For example, to make any
879       ASCII lower case letter on the line match the corresponding upper  case
880       letter  in  the trial completion, you can use `m:{a-z}={A-Z}' (however,
881       see below for the recommended form for this).  More than  one  pair  of
882       classes  can  occur,  in which case the first class before the = corre‐
883       sponds to the first after it, and so on.  If one  side  has  more  such
884       classes than the other side, the superfluous classes behave like normal
885       character classes.  In  anchor  patterns  correspondence  classes  also
886       behave like normal character classes.
887
888       The  standard  `[:name:]'  forms  described for standard shell patterns
889       (see the section FILENAME GENERATION in zshexpn(1)) may appear in  cor‐
890       respondence classes as well as normal character classes.  The only spe‐
891       cial behaviour in correspondence classes is if the form on the left and
892       the  form  on the right are each one of [:upper:], [:lower:].  In these
893       cases the character in the word and the character on the line  must  be
894       the  same  up  to  a  difference in case.  Hence to make any lower case
895       character on the line match the corresponding upper case  character  in
896       the trial completion you can use `m:{[:lower:]}={[:upper:]}'.  Although
897       the matching system does not yet handle multibyte characters,  this  is
898       likely to be a future extension, at which point this syntax will handle
899       arbitrary alphabets; hence this form, rather than the use  of  explicit
900       ranges,  is  the recommended form.  In other cases `[:name:]' forms are
901       allowed.  If the two forms on the left and  right  are  the  same,  the
902       characters  must  match exactly.  In remaining cases, the corresponding
903       tests are applied to both characters, but they are not  otherwise  con‐
904       strained;  any  matching  character  in  one set goes with any matching
905       character in the other set:  this is equivalent  to  the  behaviour  of
906       ordinary character classes.
907
908       The  pattern tpat may also be one or two stars, `*' or `**'. This means
909       that the pattern on the command line can match any number of characters
910       in  the trial completion. In this case the pattern must be anchored (on
911       either side); in the case of a single star, the anchor then  determines
912       how  much of the trial completion is to be included -- only the charac‐
913       ters up to the next appearance of the anchor will be matched. With  two
914       stars, substrings matched by the anchor can be matched, too.
915
916       Examples:
917
918       The keys of the options association defined by the parameter module are
919       the option names in all-lower-case form, without underscores, and with‐
920       out  the  optional  no at the beginning even though the builtins setopt
921       and unsetopt understand option names with upper  case  letters,  under‐
922       scores,  and  the optional no.  The following alters the matching rules
923       so that the prefix no and any underscore are  ignored  when  trying  to
924       match  the  trial  completions  generated and upper case letters on the
925       line match the corresponding lower case letters in the words:
926
927              compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \
928                ${(k)options}
929
930       The first part says that the pattern `[nN][oO]' at the  beginning  (the
931       empty  anchor before the pipe symbol) of the string on the line matches
932       the empty string in the list of words generated by  completion,  so  it
933       will be ignored if present. The second part does the same for an under‐
934       score anywhere in the command line string, and the third part uses cor‐
935       respondence  classes  so that any upper case letter on the line matches
936       the corresponding lower case letter in the word. The use of  the  upper
937       case  forms  of  the specification characters (L and M) guarantees that
938       what has already been typed on the command line (in particular the pre‐
939       fix no) will not be deleted.
940
941       Note  that  the  use  of L in the first part means that it matches only
942       when at the beginning of both the command line  string  and  the  trial
943       completion.  I.e.,  the  string  `_NO_f'  would  not  be  completed  to
944       `_NO_foo', nor would `NONO_f' be completed to `NONO_foo' because of the
945       leading  underscore or the second `NO' on the line which makes the pat‐
946       tern fail even though they are otherwise  ignored.  To  fix  this,  one
947       would  use `B:[nN][oO]=' instead of the first part. As described above,
948       this matches at the beginning of the trial completion,  independent  of
949       other  characters  or  substrings  at the beginning of the command line
950       word which are ignored by the same or other match-specs.
951
952       The second example makes completion case insensitive.  This is just the
953       same  as in the option example, except here we wish to retain the char‐
954       acters in the list of completions:
955
956              compadd -M 'm:{[:lower:]}={[:upper:]}' ...
957
958       This makes lower case letters match their upper case counterparts.   To
959       make upper case letters match the lower case forms as well:
960
961              compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...
962
963       A  nice  example  for the use of * patterns is partial word completion.
964       Sometimes you would like to  make  strings  like  `c.s.u'  complete  to
965       strings like `comp.source.unix', i.e. the word on the command line con‐
966       sists of multiple parts, separated by a dot in this example, where each
967       part  should  be  completed  separately -- note, however, that the case
968       where each part of the word, i.e. `comp', `source' and `unix'  in  this
969       example,  is to be completed from separate sets of matches is a differ‐
970       ent problem to be solved by the implementation of the  completion  wid‐
971       get.  The example can be handled by:
972
973              compadd -M 'r:|.=* r:|=*' \
974                - comp.sources.unix comp.sources.misc ...
975
976       The  first  specification  says  that  lpat  is the empty string, while
977       anchor is a dot; tpat is *, so this can match anything except  for  the
978       `.'  from  the anchor in the trial completion word.  So in `c.s.u', the
979       matcher sees `c', followed by the empty string, followed by the  anchor
980       `.',  and  likewise  for the second dot, and replaces the empty strings
981       before the anchors, giving `c[omp].s[ources].u[nix]',  where  the  last
982       part of the completion is just as normal.
983
984       With  the  pattern shown above, the string `c.u' could not be completed
985       to `comp.sources.unix' because  the  single  star  means  that  no  dot
986       (matched  by  the  anchor)  can  be  skipped.  By using two stars as in
987       `r:|.=**', however, `c.u' could be  completed  to  `comp.sources.unix'.
988       This  also shows that in some cases, especially if the anchor is a real
989       pattern, like a character class, the form with two stars may result  in
990       more matches than one would like.
991
992       The second specification is needed to make this work when the cursor is
993       in the middle of the string on the command line  and  the  option  COM‐
994       PLETE_IN_WORD  is  set. In this case the completion code would normally
995       try to match trial completions that end with the  string  as  typed  so
996       far,  i.e.  it  will  only insert new characters at the cursor position
997       rather than at the end.  However in our example we would like the  code
998       to recognise matches which contain extra characters after the string on
999       the line (the `nix' in the example).   Hence  we  say  that  the  empty
1000       string  at  the end of the string on the line matches any characters at
1001       the end of the trial completion.
1002
1003       More generally, the specification
1004
1005              compadd -M 'r:|[.,_-]=* r:|=*' ...
1006
1007       allows one to complete words with abbreviations before any of the char‐
1008       acters  in the square brackets.  For example, to complete veryverylong‐
1009       file.c rather than veryverylongheader.h with the above in  effect,  you
1010       can just type very.c before attempting completion.
1011
1012       The  specifications  with  both a left and a right anchor are useful to
1013       complete partial words whose parts are not separated  by  some  special
1014       character.  For  example,  in  some places strings have to be completed
1015       that are formed `LikeThis' (i.e. the separate parts are determined by a
1016       leading  upper  case  letter) or maybe one has to complete strings with
1017       trailing numbers. Here one could use the  simple  form  with  only  one
1018       anchor as in:
1019
1020              compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234
1021
1022       But with this, the string `H' would neither complete to `FooHoo' nor to
1023       `LikeTHIS' because in each case there is an upper  case  letter  before
1024       the `H' and that is matched by the anchor. Likewise, a `2' would not be
1025       completed.  In  both   cases   this   could   be   changed   by   using
1026       `r:|[[:upper:]0-9]=**',  but  then `H' completes to both `LikeTHIS' and
1027       `FooHoo' and a `2' matches the other strings because characters can  be
1028       inserted  before  every  upper case letter and digit. To avoid this one
1029       would use:
1030
1031              compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \
1032                  LikeTHIS FooHoo foo123 bar234
1033
1034       By using these two anchors, a `H' matches only upper case `H's that are
1035       immediately   preceded   by   something   matching   the   left  anchor
1036       `[^[:upper:]0-9]'. The effect is, of course, that `H' matches only  the
1037       string `FooHoo', a `2' matches only `bar234' and so on.
1038
1039       When  using the completion system (see zshcompsys(1)), users can define
1040       match specifications that are to be used for specific contexts by using
1041       the  matcher and matcher-list styles. The values for the latter will be
1042       used everywhere.
1043

COMPLETION WIDGET EXAMPLE

1045       The first step is to define the widget:
1046
1047              zle -C complete complete-word complete-files
1048
1049       Then the widget can be bound to a key using the  bindkey  builtin  com‐
1050       mand:
1051
1052              bindkey '^X\t' complete
1053
1054       After that the shell function complete-files will be invoked after typ‐
1055       ing control-X and TAB. The function should then generate  the  matches,
1056       e.g.:
1057
1058              complete-files () { compadd - * }
1059
1060       This function will complete files in the current directory matching the
1061       current word.
1062
1063
1064
1065zsh 5.7.1                      February 3, 2019                  ZSHCOMPWID(1)
Impressum