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

NAME

6       zshcompctl - zsh programmable completion
7

DESCRIPTION

9       This  version  of zsh has two ways of performing completion of words on
10       the command line.  New users of the shell may prefer to use  the  newer
11       and more powerful system based on shell functions; this is described in
12       zshcompsys(1), and the basic shell mechanisms which support it are  de‐
13       scribed  in  zshcompwid(1).  This manual entry describes the older com‐
14       pctl command.
15
16       compctl [ -CDT ] options [ command ... ]
17       compctl [ -CDT ] options [ -x pattern options - ... -- ]
18               [ + options [ -x ... -- ] ... [+] ] [ command ... ]
19       compctl -M match-specs ...
20       compctl -L [ -CDTM ] [ command ... ]
21       compctl + command ...
22
23       Control the editor's completion behavior according to the supplied  set
24       of options.  Various editing commands, notably expand-or-complete-word,
25       usually bound to tab, will attempt to complete  a  word  typed  by  the
26       user, while others, notably delete-char-or-list, usually bound to ^D in
27       EMACS editing mode, list the possibilities; compctl controls what those
28       possibilities  are.  They may for example be filenames (the most common
29       case, and  hence  the  default),  shell  variables,  or  words  from  a
30       user-specified list.
31

COMMAND FLAGS

33       Completion of the arguments of a command may be different for each com‐
34       mand or may use the default.  The behavior when completing the  command
35       word  itself may also be separately specified.  These correspond to the
36       following flags and arguments, all of which (except for -L) may be com‐
37       bined with any combination of the options described subsequently in the
38       section `Option Flags':
39
40       command ...
41              controls completion for the named commands, which must be listed
42              last on the command line.  If completion is attempted for a com‐
43              mand with a pathname containing slashes and no completion  defi‐
44              nition  is  found,  the search is retried with the last pathname
45              component. If the command starts with a =, completion  is  tried
46              with the pathname of the command.
47
48              Any  of the command strings may be patterns of the form normally
49              used for filename generation.  These should be quoted to protect
50              them  from  immediate  expansion; for example the command string
51              'foo*' arranges for completion of the words of any  command  be‐
52              ginning  with  foo.   When  completion is attempted, all pattern
53              completions are tried in the reverse order of  their  definition
54              until one matches.  By default, completion then proceeds as nor‐
55              mal, i.e. the shell will try to generate more  matches  for  the
56              specific  command on the command line; this can be overridden by
57              including -tn in the flags for the pattern completion.
58
59              Note that aliases are expanded before the command name is deter‐
60              mined  unless  the COMPLETE_ALIASES option is set.  Commands may
61              not be combined with the -C, -D or -T flags.
62
63       -C     controls completion when the command word itself is  being  com‐
64              pleted.  If no compctl -C command has been issued,  the names of
65              any executable command (whether in the path or specific  to  the
66              shell, such as aliases or functions) are completed.
67
68       -D     controls  default  completion behavior for the arguments of com‐
69              mands not assigned any special behavior.  If no compctl -D  com‐
70              mand has been issued, filenames are completed.
71
72       -T     supplies completion flags to be used before any other processing
73              is done, even before processing for compctls  defined  for  spe‐
74              cific  commands.   This  is especially useful when combined with
75              extended completion (the -x flag, see the section `Extended Com‐
76              pletion'  below).  Using this flag you can define default behav‐
77              ior which will apply to all commands without exception,  or  you
78              can  alter the standard behavior for all commands.  For example,
79              if your access to the user database is too slow and/or  it  con‐
80              tains  too  many users (so that completion after `~' is too slow
81              to be usable), you can use
82
83                     compctl -T -x 's[~] C[0,[^/]#]' -k friends -S/ -tn
84
85              to complete the strings in the array friends after a  `~'.   The
86              C[...]  argument  is necessary so that this form of ~-completion
87              is not tried after the directory name is finished.
88
89       -L     lists the existing completion behavior in a manner suitable  for
90              putting  into  a  start-up  script; the existing behavior is not
91              changed.  Any combination of the above forms,  or  the  -M  flag
92              (which must follow the -L flag), may be specified, otherwise all
93              defined completions are listed.  Any other  flags  supplied  are
94              ignored.
95
96       no argument
97              If  no  argument is given, compctl lists all defined completions
98              in an abbreviated form;  with a list of options, all completions
99              with  those  flags  set  (not  counting extended completion) are
100              listed.
101
102       If the + flag is alone and followed immediately by  the  command  list,
103       the  completion  behavior  for all the commands in the list is reset to
104       the default.  In other words, completion will subsequently use the  op‐
105       tions specified by the -D flag.
106
107       The  form  with -M as the first and only option defines global matching
108       specifications (see zshcompwid). The match specifications given will be
109       used  for  every  completion attempt (only when using compctl, not with
110       the new completion system) and are tried in the order in which they are
111       defined until one generates at least one match. E.g.:
112
113              compctl -M '' 'm:{a-zA-Z}={A-Za-z}'
114
115       This  will first try completion without any global match specifications
116       (the empty string) and, if that generates no matches, will try case in‐
117       sensitive completion.
118

OPTION FLAGS

120       [ -fcFBdeaRGovNAIOPZEnbjrzu/12 ]
121       [ -k array ] [ -g globstring ] [ -s subststring ]
122       [ -K function ]
123       [ -Q ] [ -P prefix ] [ -S suffix ]
124       [ -W file-prefix ] [ -H num pattern ]
125       [ -q ] [ -X explanation ] [ -Y explanation ]
126       [ -y func-or-var ] [ -l cmd ] [ -h cmd ] [ -U ]
127       [ -t continue ] [ -J name ] [ -V name ]
128       [ -M match-spec ]
129
130       The remaining options specify the type of command arguments to look for
131       during completion.  Any combination of these flags  may  be  specified;
132       the  result is a sorted list of all the possibilities.  The options are
133       as follows.
134
135   Simple Flags
136       These produce completion lists made up by the shell itself:
137
138       -f     Filenames and file system paths.
139
140       -/     Just file system paths.
141
142       -c     Command names, including aliases, shell functions, builtins  and
143              reserved words.
144
145       -F     Function names.
146
147       -B     Names of builtin commands.
148
149       -m     Names of external commands.
150
151       -w     Reserved words.
152
153       -a     Alias names.
154
155       -R     Names of regular (non-global) aliases.
156
157       -G     Names of global aliases.
158
159       -d     This can be combined with -F, -B, -w, -a, -R and -G to get names
160              of disabled functions, builtins, reserved words or aliases.
161
162       -e     This option (to show enabled commands) is in effect by  default,
163              but may be combined with -d; -de in combination with -F, -B, -w,
164              -a, -R and -G will complete names of  functions,  builtins,  re‐
165              served words or aliases whether or not they are disabled.
166
167       -o     Names of shell options (see zshoptions(1)).
168
169       -v     Names of any variable defined in the shell.
170
171       -N     Names of scalar (non-array) parameters.
172
173       -A     Array names.
174
175       -I     Names of integer variables.
176
177       -O     Names of read-only variables.
178
179       -p     Names of parameters used by the shell (including special parame‐
180              ters).
181
182       -Z     Names of shell special parameters.
183
184       -E     Names of environment variables.
185
186       -n     Named directories.
187
188       -b     Key binding names.
189
190       -j     Job names:  the first word of the  job  leader's  command  line.
191              This is useful with the kill builtin.
192
193       -r     Names of running jobs.
194
195       -z     Names of suspended jobs.
196
197       -u     User names.
198
199   Flags with Arguments
200       These have user supplied arguments to determine how the list of comple‐
201       tions is to be made up:
202
203       -k array
204              Names taken from the elements of $array (note that the `$'  does
205              not  appear  on  the command line).  Alternatively, the argument
206              array itself may be a set of space- or comma-separated values in
207              parentheses,  in which any delimiter may be escaped with a back‐
208              slash; in this case the argument should be quoted.  For example,
209
210                     compctl -k "(cputime filesize datasize stacksize
211                                 coredumpsize resident descriptors)" limit
212
213       -g globstring
214              The globstring is expanded using filename globbing; it should be
215              quoted  to  protect  it  from immediate expansion. The resulting
216              filenames are taken as the possible completions.  Use `*(/)' in‐
217              stead of `*/' for directories.  The fignore special parameter is
218              not applied to the resulting files.  More than one  pattern  may
219              be  given separated by blanks. (Note that brace expansion is not
220              part of globbing.  Use the syntax `(either|or)' to match  alter‐
221              natives.)
222
223       -s subststring
224              The subststring is split into words and these words are than ex‐
225              panded using all shell expansion  mechanisms  (see  zshexpn(1)).
226              The resulting words are taken as possible completions.  The fig‐
227              nore special parameter is not applied to  the  resulting  files.
228              Note that -g is faster for filenames.
229
230       -K function
231              Call the given function to get the completions.  Unless the name
232              starts with an underscore, the function is passed two arguments:
233              the  prefix and the suffix of the word on which completion is to
234              be attempted, in other words those characters before the  cursor
235              position, and those from the cursor position onwards.  The whole
236              command line can be accessed with the -c and  -l  flags  of  the
237              read  builtin.  The function should set the variable reply to an
238              array containing the completions (one completion  per  element);
239              note  that reply should not be made local to the function.  From
240              such a function the command line can be accessed with the -c and
241              -l flags to the read builtin.  For example,
242
243                     function whoson { reply=(`users`); }
244                     compctl -K whoson talk
245
246              completes only logged-on users after `talk'.  Note that `whoson'
247              must return an array, so `reply=`users`' would be incorrect.
248
249       -H num pattern
250              The possible completions are taken from  the  last  num  history
251              lines.   Only  words matching pattern are taken.  If num is zero
252              or negative the whole history is searched and if pattern is  the
253              empty  string  all words are taken (as with `*').  A typical use
254              is
255
256                     compctl -D -f + -H 0 ''
257
258              which forces completion to look back in the history list  for  a
259              word if no filename matches.
260
261   Control Flags
262       These do not directly specify types of name to be completed, but manip‐
263       ulate the options that do:
264
265       -Q     This instructs the shell not to quote any metacharacters in  the
266              possible  completions.  Normally the results of a completion are
267              inserted into the command line with any metacharacters quoted so
268              that  they are interpreted as normal characters.  This is appro‐
269              priate for filenames and ordinary strings.  However, for special
270              effects,  such  as inserting a backquoted expression from a com‐
271              pletion array (-k) so that the expression will not be  evaluated
272              until the complete line is executed, this option must be used.
273
274       -P prefix
275              The  prefix  is  inserted  just before the completed string; any
276              initial part already typed will be completed and the whole  pre‐
277              fix ignored for completion purposes.  For example,
278
279                     compctl -j -P "%" kill
280
281              inserts  a  `%'  after  the  kill command and then completes job
282              names.
283
284       -S suffix
285              When a completion is found the suffix is inserted after the com‐
286              pleted string.  In the case of menu completion the suffix is in‐
287              serted immediately, but it is still possible  to  cycle  through
288              the list of completions by repeatedly hitting the same key.
289
290       -W file-prefix
291              With  directory  file-prefix:   for command, file, directory and
292              globbing completion (options -c, -f, -/, -g), the file prefix is
293              implicitly added in front of the completion.  For example,
294
295                     compctl -/ -W ~/Mail maildirs
296
297              completes  any subdirectories to any depth beneath the directory
298              ~/Mail, although that prefix does  not  appear  on  the  command
299              line.   The  file-prefix may also be of the form accepted by the
300              -k flag, i.e. the name of an array or a literal list  in  paren‐
301              thesis.  In  this  case  all the directories in the list will be
302              searched for possible completions.
303
304       -q     If used with a suffix as specified by the -S option, this causes
305              the  suffix to be removed if the next character typed is a blank
306              or does not insert anything or if the suffix  consists  of  only
307              one  character  and the next character typed is the same charac‐
308              ter; this the same rule used for the  AUTO_REMOVE_SLASH  option.
309              The  option  is  most  useful for list separators (comma, colon,
310              etc.).
311
312       -l cmd This option restricts the range of command line words  that  are
313              considered  to  be  arguments.   If combined with one of the ex‐
314              tended completion patterns `p[...]', `r[...]', or `R[...]'  (see
315              the section `Extended Completion' below) the range is restricted
316              to the range of arguments specified in the brackets.  Completion
317              is then performed as if these had been given as arguments to the
318              cmd supplied with the option. If the cmd  string  is  empty  the
319              first  word  in  the range is instead taken as the command name,
320              and command name completion performed on the first word  in  the
321              range.  For example,
322
323                     compctl -x 'r[-exec,;]' -l '' -- find
324
325              completes  arguments  between  `-exec' and the following `;' (or
326              the end of the command line if there is no such  string)  as  if
327              they were a separate command line.
328
329       -h cmd Normally  zsh completes quoted strings as a whole. With this op‐
330              tion, completion can be done separately on  different  parts  of
331              such  strings. It works like the -l option but makes the comple‐
332              tion code work on the parts of the current word that  are  sepa‐
333              rated by spaces. These parts are completed as if they were argu‐
334              ments to the given cmd. If cmd is the empty  string,  the  first
335              part is completed as a command name, as with -l.
336
337       -U     Use  the whole list of possible completions, whether or not they
338              actually match the word on the command line.  The word typed  so
339              far will be deleted.  This is most useful with a function (given
340              by the -K option) which can examine the word  components  passed
341              to  it  (or  via the read builtin's -c and -l flags) and use its
342              own criteria to decide what matches.  If there is no completion,
343              the original word is retained.  Since the produced possible com‐
344              pletions seldom have interesting common prefixes  and  suffixes,
345              menu  completion  is started immediately if AUTO_MENU is set and
346              this flag is used.
347
348       -y func-or-var
349              The list provided by func-or-var is  displayed  instead  of  the
350              list  of  completions whenever a listing is required; the actual
351              completions to be inserted are not affected.  It can be provided
352              in  two ways. Firstly, if func-or-var begins with a $ it defines
353              a variable, or if it begins with a left  parenthesis  a  literal
354              array, which contains the list.  A variable may have been set by
355              a call to a function using the -K option.  Otherwise it contains
356              the  name  of  a  function  which will be executed to create the
357              list.  The function will be  passed  as  an  argument  list  all
358              matching  completions,  including prefixes and suffixes expanded
359              in full, and should set the array reply to the result.  In  both
360              cases,  the display list will only be retrieved after a complete
361              list of matches has been created.
362
363              Note that the returned list does not have to correspond, even in
364              length,  to  the original set of matches, and may be passed as a
365              scalar instead of an array.  No special formatting of characters
366              is performed on the output in this case; in particular, newlines
367              are printed literally and if they appear output  in  columns  is
368              suppressed.
369
370       -X explanation
371              Print  explanation  when trying completion on the current set of
372              options. A `%n' in this string is  replaced  by  the  number  of
373              matches that were added for this explanation string.  The expla‐
374              nation only appears if completion was tried  and  there  was  no
375              unique  match,  or when listing completions. Explanation strings
376              will be listed together with the matches of the group  specified
377              together  with the -X option (using the -J or -V option). If the
378              same explanation string is given to  multiple  -X  options,  the
379              string  appears  only  once  (for  each group) and the number of
380              matches shown for the `%n' is the total number  of  all  matches
381              for each of these uses. In any case, the explanation string will
382              only be shown if there was at least one match added for the  ex‐
383              planation string.
384
385              The  sequences  %B,  %b,  %S,  %s, %U, and %u specify output at‐
386              tributes (bold, standout, and underline), %F, %f, %K, %k specify
387              foreground  and  background  colours, and %{...%} can be used to
388              include literal escape sequences as in prompts.
389
390       -Y explanation
391              Identical to -X, except that the explanation first undergoes ex‐
392              pansion  following the usual rules for strings in double quotes.
393              The expansion will be carried out after any functions are called
394              for the -K or -y options, allowing them to set variables.
395
396       -t continue
397              The  continue-string  contains  a character that specifies which
398              set of completion flags should be used next.  It is useful:
399
400              (i) With -T, or when trying a list of pattern completions,  when
401              compctl  would  usually  continue with ordinary processing after
402              finding matches; this can be suppressed with `-tn'.
403
404              (ii) With a list of alternatives separated by  +,  when  compctl
405              would  normally  stop  when  one  of  the alternatives generates
406              matches.  It can be forced to consider the next set  of  comple‐
407              tions by adding `-t+' to the flags of the alternative before the
408              `+'.
409
410              (iii) In an extended completion list (see below),  when  compctl
411              would  normally  continue  until  a set of conditions succeeded,
412              then use only the immediately following flags.  With `-t-', com‐
413              pctl  will  continue  trying extended completions after the next
414              `-'; with `-tx' it will  attempt  completion  with  the  default
415              flags, in other words those before the `-x'.
416
417       -J name
418              This  gives  the  name of the group the matches should be placed
419              in. Groups are listed and sorted separately; likewise, menu com‐
420              pletion  will  offer  the  matches in the groups in the order in
421              which the groups were defined. If no group  name  is  explicitly
422              given,  the  matches  are  stored  in a group named default. The
423              first time a group name is encountered, a group with  that  name
424              is  created. After that all matches with the same group name are
425              stored in that group.
426
427              This can be useful with non-exclusive  alternative  completions.
428              For example, in
429
430                     compctl -f -J files -t+ + -v -J variables foo
431
432              both  files  and  variables are possible completions, as the -t+
433              forces both sets of alternatives before and after the  +  to  be
434              considered  at  once.   Because  of the -J options, however, all
435              files are listed before all variables.
436
437       -V name
438              Like -J, but matches within the group  will  not  be  sorted  in
439              listings  nor in menu completion. These unsorted groups are in a
440              different name space from the sorted ones, so groups defined  as
441              -J files and -V files are distinct.
442
443       -1     If given together with the -V option, makes only consecutive du‐
444              plicates in the group be removed.  Note  that  groups  with  and
445              without this flag are in different name spaces.
446
447       -2     If given together with the -J or -V option, makes all duplicates
448              be kept. Again, groups with and without this flag are in differ‐
449              ent name spaces.
450
451       -M match-spec
452              This  defines  additional  matching  control specifications that
453              should be used only when testing words for  the  list  of  flags
454              this flag appears in. The format of the match-spec string is de‐
455              scribed in zshcompwid.
456

ALTERNATIVE COMPLETION

458       compctl [ -CDT ] options + options [ + ... ] [ + ] command ...
459
460       The form with `+' specifies alternative options.  Completion  is  tried
461       with the options before the first `+'. If this produces no matches com‐
462       pletion is tried with the flags after the `+' and so on. If  there  are
463       no  flags  after the last `+' and a match has not been found up to that
464       point, default completion is tried.  If the list of flags contains a -t
465       with  a + character, the next list of flags is used even if the current
466       list produced matches.
467
468       Additional options are available that restrict completion to some  part
469       of the command line; this is referred to as `extended completion'.
470

EXTENDED COMPLETION

472       compctl [ -CDT ] options -x pattern options - ... --
473               [ command ... ]
474       compctl [ -CDT ] options [ -x pattern options - ... -- ]
475               [ + options [ -x ... -- ] ... [+] ] [ command ... ]
476
477       The  form  with  `-x'  specifies  extended  completion for the commands
478       given; as shown, it may be combined with alternative  completion  using
479       `+'.  Each pattern is examined in turn; when a match is found, the cor‐
480       responding options, as described in the section `Option  Flags'  above,
481       are  used to generate possible completions.  If no pattern matches, the
482       options given before the -x are used.
483
484       Note that each pattern should be supplied  as  a  single  argument  and
485       should be quoted to prevent expansion of metacharacters by the shell.
486
487       A  pattern  is built of sub-patterns separated by commas; it matches if
488       at least one of these sub-patterns matches  (they  are  `or'ed).  These
489       sub-patterns  are  in  turn composed of other sub-patterns separated by
490       white spaces which match if all of the  sub-patterns  match  (they  are
491       `and'ed).  An element of the sub-patterns is of the form `c[...][...]',
492       where the pairs of brackets may be repeated as often as necessary,  and
493       matches  if  any  of the sets of brackets match (an `or').  The example
494       below makes this clearer.
495
496       The elements may be any of the following:
497
498       s[string]...
499              Matches if the current word on the command line starts with  one
500              of the strings given in brackets.  The string is not removed and
501              is not part of the completion.
502
503       S[string]...
504              Like s[string] except that the string is part of the completion.
505
506       p[from,to]...
507              Matches if the number of the current word is between one of  the
508              from  and  to pairs inclusive. The comma and to are optional; to
509              defaults to the same value as from.  The numbers  may  be  nega‐
510              tive: -n refers to the n'th last word on the line.
511
512       c[offset,string]...
513              Matches if the string matches the word offset by offset from the
514              current word position.  Usually offset will be negative.
515
516       C[offset,pattern]...
517              Like c but using pattern matching instead.
518
519       w[index,string]...
520              Matches if the word in position index is  equal  to  the  corre‐
521              sponding  string.   Note  that  the word count is made after any
522              alias expansion.
523
524       W[index,pattern]...
525              Like w but using pattern matching instead.
526
527       n[index,string]...
528              Matches if the current word contains string.  Anything up to and
529              including the indexth occurrence of this string will not be con‐
530              sidered part of the completion, but the rest will.  index may be
531              negative  to  count from the end: in most cases, index will be 1
532              or -1.  For example,
533
534                     compctl -s '`users`' -x 'n[1,@]' -k hosts -- talk
535
536              will usually complete usernames, but if you insert  an  @  after
537              the  name,  names from the array hosts (assumed to contain host‐
538              names, though you must make the array  yourself)  will  be  com‐
539              pleted.  Other commands such as rcp can be handled similarly.
540
541       N[index,string]...
542              Like  n  except  that  the  string  will be taken as a character
543              class.  Anything up to and including the indexth  occurrence  of
544              any  of  the characters in string will not be considered part of
545              the completion.
546
547       m[min,max]...
548              Matches if the total number of words lies between  min  and  max
549              inclusive.
550
551       r[str1,str2]...
552              Matches  if  the  cursor  is  after a word with prefix str1.  If
553              there is also a word with prefix str2 on the command line  after
554              the  one matched by str1 it matches only if the cursor is before
555              this word. If the comma and str2 are omitted, it matches if  the
556              cursor is after a word with prefix str1.
557
558       R[str1,str2]...
559              Like r but using pattern matching instead.
560
561       q[str]...
562              Matches  the  word currently being completed is in single quotes
563              and the str begins with the letter `s', or if completion is done
564              in  double quotes and str starts with the letter `d', or if com‐
565              pletion is done in backticks and str starts with a `b'.
566

EXAMPLE

568              compctl -u -x 's[+] c[-1,-f],s[-f+]' \
569                -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail
570
571       This is to be interpreted as follows:
572
573       If the current command is mail, then
574
575              if ((the current word begins with + and the previous word is -f)
576              or (the current word begins with -f+)), then complete the
577              non-directory part (the `:t' glob modifier) of files in the directory
578              ~/Mail; else
579
580              if the current word begins with -f or the previous word was -f, then
581              complete any file; else
582
583              complete user names.
584
585
586
587
588zsh 5.9                          May 14, 2022                    ZSHCOMPCTL(1)
Impressum