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 [ -akqQfenUld12C ] [ -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     This option adds number empty  matches  after  the  words
650                     have  been  added.  An empty match takes up space in com‐
651                     pletion listings but will never be inserted in  the  line
652                     and can't be selected with menu completion or menu selec‐
653                     tion.  This makes empty matches  only  useful  to  format
654                     completion  lists and to make explanatory string be shown
655                     in completion lists (since empty  matches  can  be  given
656                     display strings with the -d option).  And because all but
657                     one empty string would otherwise be removed, this  option
658                     implies  the  -V  and  -2 options (even if an explicit -J
659                     option is given).
660
661              -
662              --     This flag ends the list of flags and options.  All  argu‐
663                     ments  after  it  will  be  taken  as the words to use as
664                     matches even if they begin with hyphens.
665
666              Except for the -M flag, if any of these flags is given more than
667              once, the first one (and its argument) will be used.
668
669       compset -p number
670       compset -P [ number ] pattern
671       compset -s number
672       compset -S [ number ] pattern
673       compset -n begin [ end ]
674       compset -N beg-pat [ end-pat ]
675       compset -q
676              This  command simplifies modification of the special parameters,
677              while its return status allows tests on them to be carried out.
678
679              The options are:
680
681              -p number
682                     If the contents of the PREFIX parameter  is  longer  than
683                     number   characters,  the  first  number  characters  are
684                     removed from it and  appended  to  the  contents  of  the
685                     IPREFIX parameter.
686
687              -P [ number ] pattern
688                     If the value of the PREFIX parameter begins with anything
689                     that matches the pattern, the matched portion is  removed
690                     from PREFIX and appended to IPREFIX.
691
692                     Without  the optional number, the longest match is taken,
693                     but if number is given, anything up to the numberth match
694                     is  moved.  If the number is negative, the numberth long‐
695                     est match is moved. For example, if PREFIX  contains  the
696                     string  `a=b=c',  then  compset  -P  '*\='  will move the
697                     string `a=b=' into the IPREFIX parameter, but compset  -P
698                     1 '*\=' will move only the string `a='.
699
700              -s number
701                     As  -p,  but transfer the last number characters from the
702                     value of SUFFIX to the front of the value of ISUFFIX.
703
704              -S [ number ] pattern
705                     As -P, but match the last portion of SUFFIX and  transfer
706                     the matched portion to the front of the value of ISUFFIX.
707
708              -n begin [ end ]
709                     If  the current word position as specified by the parame‐
710                     ter CURRENT is greater than or equal to  begin,  anything
711                     up  to  the  beginth word is removed from the words array
712                     and the value of the parameter CURRENT is decremented  by
713                     begin.
714
715                     If  the  optional  end is given, the modification is done
716                     only if the current word position is also  less  than  or
717                     equal  to  end. In this case, the words from position end
718                     onwards are also removed from the words array.
719
720                     Both begin and end may be  negative  to  count  backwards
721                     from the last element of the words array.
722
723              -N beg-pat [ end-pat ]
724                     If  one of the elements of the words array before the one
725                     at the index given by the value of the parameter  CURRENT
726                     matches  the  pattern  beg-pat,  all  elements  up to and
727                     including the matching one are  removed  from  the  words
728                     array and the value of CURRENT is changed to point to the
729                     same word in the changed array.
730
731                     If the optional pattern end-pat is also given, and  there
732                     is  an  element in the words array matching this pattern,
733                     the parameters are modified only if  the  index  of  this
734                     word  is higher than the one given by the CURRENT parame‐
735                     ter (so that the matching word has to be after  the  cur‐
736                     sor).  In  this  case,  the  words  starting with the one
737                     matching end-pat are also removed from the  words  array.
738                     If  words  contains no word matching end-pat, the testing
739                     and modification is performed as if it were not given.
740
741              -q     The word currently being completed  is  split  on  spaces
742                     into  separate  words, respecting the usual shell quoting
743                     conventions.  The resulting words are stored in the words
744                     array,  and CURRENT, PREFIX, SUFFIX, QIPREFIX, and QISUF‐
745                     FIX are modified to reflect the word part  that  is  com‐
746                     pleted.
747
748              In  all  the  above  cases the return status is zero if the test
749              succeeded and the parameters were modified and  non-zero  other‐
750              wise. This allows one to use this builtin in tests such as:
751
752                     if compset -P '*\='; then ...
753
754              This  forces anything up to and including the last equal sign to
755              be ignored by the completion code.
756
757       compcall [ -TD ]
758              This allows the use of  completions  defined  with  the  compctl
759              builtin  from  within  completion  widgets.  The list of matches
760              will be generated as if one of the non-widget  completion  func‐
761              tions  (complete-word,  etc.)  had been called, except that only
762              compctls given for specific commands are used. To force the code
763              to  try completions defined with the -T option of compctl and/or
764              the default completion (whether defined by  compctl  -D  or  the
765              builtin  default)  in  the  appropriate places, the -T and/or -D
766              flags can be passed to compcall.
767
768              The return status can be used to test if a matching compctl def‐
769              inition  was  found.  It  is non-zero if a compctl was found and
770              zero otherwise.
771
772              Note that this builtin is defined by the zsh/compctl module.
773

COMPLETION CONDITION CODES

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

COMPLETION MATCHING CONTROL

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

COMPLETION WIDGET EXAMPLE

1037       The first step is to define the widget:
1038
1039              zle -C complete complete-word complete-files
1040
1041       Then  the  widget  can be bound to a key using the bindkey builtin com‐
1042       mand:
1043
1044              bindkey '^X\t' complete
1045
1046       After that the shell function complete-files will be invoked after typ‐
1047       ing  control-X  and TAB. The function should then generate the matches,
1048       e.g.:
1049
1050              complete-files () { compadd - * }
1051
1052       This function will complete files in the current directory matching the
1053       current word.
1054
1055
1056
1057zsh 5.0.2                      December 21, 2012                 ZSHCOMPWID(1)
Impressum