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 ${.
134
135                     assign_parameter
136                            when  completing  the  name  of  a  parameter in a
137                            parameter assignment.
138
139                     command
140                            when completing for a normal  command  (either  in
141                            command  position  or  for an argument of the com‐
142                            mand).
143
144                     condition
145                            when completing  inside  a  `[[...]]'  conditional
146                            expression;  in this case the words array contains
147                            only the words inside the conditional expression.
148
149                     math   when completing in a mathematical environment such
150                            as a `((...))' construct.
151
152                     parameter
153                            when  completing  the  name  of  a  parameter in a
154                            parameter expansion beginning with $ but not ${.
155
156                     redirect
157                            when completing after a redirection operator.
158
159                     subscript
160                            when completing inside a parameter subscript.
161
162                     value  when completing the value of a  parameter  assign‐
163                            ment.
164
165              exact  Controls  the behaviour when the REC_EXACT option is set.
166                     It will be set to accept  if  an  exact  match  would  be
167                     accepted, and will be unset otherwise.
168
169                     If it was set when at least one match equal to the string
170                     on the line was generated, the match is accepted.
171
172              exact_string
173                     The string of an exact match if one was found,  otherwise
174                     unset.
175
176              ignored
177                     The  number  of  words  that  were  ignored  because they
178                     matched one of the patterns given with the -F  option  to
179                     the compadd builtin command.
180
181              insert This  controls  the  manner  in which a match is inserted
182                     into the command line.  On entry to the widget  function,
183                     if  it is unset the command line is not to be changed; if
184                     set to unambiguous, any prefix common to all  matches  is
185                     to  be inserted; if set to automenu-unambiguous, the com‐
186                     mon prefix is to be inserted and the next  invocation  of
187                     the completion code may start menu completion (due to the
188                     AUTO_MENU option being set); if set to menu  or  automenu
189                     menu completion will be started for the matches currently
190                     generated (in the latter case this  will  happen  because
191                     the  AUTO_MENU  is  set).  The value may also contain the
192                     string `tab' when the completion code would normally  not
193                     really do completion, but only insert the TAB character.
194
195                     On  exit  it may be set to any of the values above (where
196                     setting it to the empty string is the same  as  unsetting
197                     it), or to a number, in which case the match whose number
198                     is given will be inserted into the command  line.   Nega‐
199                     tive  numbers  count  backward  from the last match (with
200                     `-1' selecting the last match)  and  out-of-range  values
201                     are  wrapped  around, so that a value of zero selects the
202                     last match and a value one more than the maximum  selects
203                     the  first. Unless the value of this key ends in a space,
204                     the match is inserted as in a menu completion, i.e. with‐
205                     out automatically appending a space.
206
207                     Both menu and automenu may also specify the the number of
208                     the match to insert, given after a colon.   For  example,
209                     `menu:2'  says  to  start menu completion, beginning with
210                     the second match.
211
212                     Note that a value containing the  substring  `tab'  makes
213                     the  matches  generated  be  ignored  and only the TAB be
214                     inserted.
215
216                     Finally, it may also be  set  to  all,  which  makes  all
217                     matches generated be inserted into the line.
218
219              insert_positions
220                     When  the completion system inserts an unambiguous string
221                     into the line, there may be multiple places where charac‐
222                     ters  are missing or where the character inserted differs
223                     from at least one match.  The value of this key  contains
224                     a colon separated list of all these positions, as indexes
225                     into the command line.
226
227              last_prompt
228                     If this is set to a  non-empty  string  for  every  match
229                     added,  the  completion code will move the cursor back to
230                     the previous prompt after the  list  of  completions  has
231                     been displayed.  Initially this is set or unset according
232                     to the ALWAYS_LAST_PROMPT option.
233
234              list   This controls whether or how the list of matches will  be
235                     displayed.   If  it  is unset or empty they will never be
236                     listed; if its value begins with list, they  will  always
237                     be  listed; if it begins with autolist or ambiguous, they
238                     will be  listed  when  the  AUTO_LIST  or  LIST_AMBIGUOUS
239                     options respectively would normally cause them to be.
240
241                     If  the  substring force appears in the value, this makes
242                     the list be shown even if there is only one  match.  Nor‐
243                     mally, the list would be shown only if there are at least
244                     two matches.
245
246                     The  value  contains  the   substring   packed   if   the
247                     LIST_PACKED option is set. If this substring is given for
248                     all matches added to a group, this group  will  show  the
249                     LIST_PACKED   behavior.   The   same   is  done  for  the
250                     LIST_ROWS_FIRST option with the substring rows.
251
252                     Finally, if the value contains the  string  explanations,
253                     only  the explanation strings, if any, will be listed and
254                     if it contains messages, only the  messages  (added  with
255                     the -x option of compadd) will be listed.  If it contains
256                     both explanations and messages both kinds of  explanation
257                     strings  will be listed.  It will be set appropriately on
258                     entry to a completion widget and may be changed there.
259
260              list_lines
261                     This gives the number of lines that are needed to display
262                     the full list of completions.  Note that to calculate the
263                     total number of lines to display you need to add the num‐
264                     ber  of  lines needed for the command line to this value,
265                     this is available as the value of the BUFFERLINES special
266                     parameter.
267
268              list_max
269                     Initially this is set to the value of the LISTMAX parame‐
270                     ter.  It may be set to any other value; when  the  widget
271                     exits  this  value  will  be  used in the same way as the
272                     value of LISTMAX.
273
274              nmatches
275                     The number of matches generated and accepted by the  com‐
276                     pletion code so far.
277
278              old_insert
279                     On  entry to the widget this will be set to the number of
280                     the match of an old list of completions that is currently
281                     inserted  into  the  command  line.  If no match has been
282                     inserted, this is unset.
283
284                     As with old_list, the value of this key will only be used
285                     if  it is the string keep. If it was set to this value by
286                     the widget and there was an old match inserted  into  the
287                     command line, this match will be kept and if the value of
288                     the insert key specifies that  another  match  should  be
289                     inserted, this will be inserted after the old one.
290
291              old_list
292                     This is set to yes if there is still a valid list of com‐
293                     pletions from a previous completion at the time the  wid‐
294                     get  is  invoked.   This  will usually be the case if and
295                     only if the previous editing operation was  a  completion
296                     widget  or  one  of the builtin completion functions.  If
297                     there is a valid list and it is also currently  shown  on
298                     the screen, the value of this key is shown.
299
300                     After the widget has exited the value of this key is only
301                     used if it was set to keep.  In this case the  completion
302                     code  will  continue to use this old list.  If the widget
303                     generated new matches, they will not be used.
304
305              parameter
306                     The name of the parameter when completing in a  subscript
307                     or in the value of a parameter assignment.
308
309              pattern_insert
310                     Normally  this  is set to menu, which specifies that menu
311                     completion will be used whenever a  set  of  matches  was
312                     generated  using  pattern  matching.  If it is set to any
313                     other non-empty string by the user and menu completion is
314                     not  selected  by  other  option  settings, the code will
315                     instead  insert  any  common  prefix  for  the  generated
316                     matches as with normal completion.
317
318              pattern_match
319                     Locally controls the behaviour given by the GLOB_COMPLETE
320                     option.  Initially it is set to `*' if and  only  if  the
321                     option  is set.  The completion widget may set it to this
322                     value, to an empty string (which has the same  effect  as
323                     unsetting  it),  or to any other non-empty string.  If it
324                     is non-empty, unquoted metacharacters on the command line
325                     will be treated as patterns; if it is `*', then addition‐
326                     ally a wildcard `*' is assumed at the cursor position; if
327                     it is empty or unset, metacharacters will be treated lit‐
328                     erally.
329
330                     Note that the matcher specifications given to the compadd
331                     builtin  command  are  not  used  if  this  is  set  to a
332                     non-empty string.
333
334              quote  When completing inside quotes, this contains  the  quota‐
335                     tion  character  (i.e.  either  a  single quote, a double
336                     quote, or a backtick).  Otherwise it is unset.
337
338              quoting
339                     When completing inside single quotes, this is set to  the
340                     string  single;  inside double quotes, the string double;
341                     inside backticks, the string backtick.  Otherwise  it  is
342                     unset.
343
344              redirect
345                     The redirection operator when completing in a redirection
346                     position, i.e. one of <, >, etc.
347
348              restore
349                     This is set to auto before a function is  entered,  which
350                     forces  the  special  parameters  mentioned above (words,
351                     CURRENT, PREFIX, IPREFIX,  SUFFIX,  and  ISUFFIX)  to  be
352                     restored  to  their  previous  values  when  the function
353                     exits.   If a function unsets it or sets it to any  other
354                     string, they will not be restored.
355
356              to_end Specifies  the  occasions on which the cursor is moved to
357                     the end of a string when a match is inserted.   On  entry
358                     to  a widget function, it may be single if this will hap‐
359                     pen when a single unambiguous match was inserted or match
360                     if it will happen any time a match is inserted (for exam‐
361                     ple, by menu completion; this is likely to be the  effect
362                     of the ALWAYS_TO_END option).
363
364                     On  exit,  it may be set to single as above.  It may also
365                     be set to always, or to the empty  string  or  unset;  in
366                     those  cases  the  cursor will be moved to the end of the
367                     string always or never respectively.  Any other string is
368                     treated as match.
369
370              unambiguous
371                     This  key is read-only and will always be set to the com‐
372                     mon (unambiguous) prefix the completion code  has  gener‐
373                     ated for all matches added so far.
374
375              unambiguous_cursor
376                     This  gives the position the cursor would be placed at if
377                     the common prefix in the unambiguous key  were  inserted,
378                     relative  to  the  value of that key. The cursor would be
379                     placed before the character whose index is given by  this
380                     key.
381
382              unambiguous_positions
383                     This contains all positions where characters in the unam‐
384                     biguous  string  are  missing  or  where  the   character
385                     inserted  differs  from at least one of the matches.  The
386                     positions are given as indexes into the string  given  by
387                     the value of the unambiguous key.
388
389              vared  If  completion  is  called while editing a line using the
390                     vared builtin, the value of this key is set to  the  name
391                     of the parameter given as an argument to vared.  This key
392                     is only set while a vared command is active.
393
394       words  This array contains the words present on the command  line  cur‐
395              rently being edited.
396

COMPLETION BUILTIN COMMANDS

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

COMPLETION CONDITION CODES

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

COMPLETION MATCHING CONTROL

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

COMPLETION WIDGET EXAMPLE

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