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
13       described 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
52              beginning  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
105       options 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
117       insensitive 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,
165              reserved 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  `*(/)'
217              instead  of `*/' for directories.  The fignore special parameter
218              is not applied to the resulting files.  More  than  one  pattern
219              may  be given separated by blanks. (Note that brace expansion is
220              not part of globbing.  Use the  syntax  `(either|or)'  to  match
221              alternatives.)
222
223       -s subststring
224              The  subststring  is  split  into words and these words are than
225              expanded 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
287              inserted 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
314              extended completion patterns  `p[...]',  `r[...]',  or  `R[...]'
315              (see  the  section  `Extended  Completion'  below)  the range is
316              restricted to the range of arguments specified in the  brackets.
317              Completion is then performed as if these had been given as argu‐
318              ments to the cmd supplied with the option. If the cmd string  is
319              empty  the  first word in the range is instead taken as the com‐
320              mand name, and command name completion performed  on  the  first
321              word in the 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
330              option, 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
383              explanation string.
384
385              The  sequences  %B,  %b,  %S,  %s,  %U,  and  %u  specify output
386              attributes (bold, standout, and underline), %F, %f, %K, %k spec‐
387              ify  foreground  and background colours, and %{...%} can be used
388              to include literal escape sequences as in prompts.
389
390       -Y explanation
391              Identical to -X, except that  the  explanation  first  undergoes
392              expansion  following  the  usual  rules  for  strings  in double
393              quotes.  The expansion will be carried out after  any  functions
394              are  called for the -K or -y options, allowing them to set vari‐
395              ables.
396
397       -t continue
398              The continue-string contains a character  that  specifies  which
399              set of completion flags should be used next.  It is useful:
400
401              (i)  With -T, or when trying a list of pattern completions, when
402              compctl would usually continue with  ordinary  processing  after
403              finding matches; this can be suppressed with `-tn'.
404
405              (ii)  With  a  list of alternatives separated by +, when compctl
406              would normally stop  when  one  of  the  alternatives  generates
407              matches.   It  can be forced to consider the next set of comple‐
408              tions by adding `-t+' to the flags of the alternative before the
409              `+'.
410
411              (iii)  In  an extended completion list (see below), when compctl
412              would normally continue until a  set  of  conditions  succeeded,
413              then use only the immediately following flags.  With `-t-', com‐
414              pctl will continue trying extended completions  after  the  next
415              `-';  with  `-tx'  it  will  attempt completion with the default
416              flags, in other words those before the `-x'.
417
418       -J name
419              This gives the name of the group the matches  should  be  placed
420              in. Groups are listed and sorted separately; likewise, menu com‐
421              pletion will offer the matches in the groups  in  the  order  in
422              which  the  groups  were defined. If no group name is explicitly
423              given, the matches are stored in  a  group  named  default.  The
424              first  time  a group name is encountered, a group with that name
425              is created. After that all matches with the same group name  are
426              stored in that group.
427
428              This  can  be useful with non-exclusive alternative completions.
429              For example, in
430
431                     compctl -f -J files -t+ + -v -J variables foo
432
433              both files and variables are possible completions,  as  the  -t+
434              forces  both  sets  of alternatives before and after the + to be
435              considered at once.  Because of the  -J  options,  however,  all
436              files are listed before all variables.
437
438       -V name
439              Like  -J,  but  matches  within  the group will not be sorted in
440              listings nor in menu completion. These unsorted groups are in  a
441              different  name space from the sorted ones, so groups defined as
442              -J files and -V files are distinct.
443
444       -1     If given together with the -V  option,  makes  only  consecutive
445              duplicates  in  the  group be removed. Note that groups with and
446              without this flag are in different name spaces.
447
448       -2     If given together with the -J or -V option, makes all duplicates
449              be kept. Again, groups with and without this flag are in differ‐
450              ent name spaces.
451
452       -M match-spec
453              This defines additional  matching  control  specifications  that
454              should  be  used  only  when testing words for the list of flags
455              this flag appears in. The format of  the  match-spec  string  is
456              described in zshcompwid.
457

ALTERNATIVE COMPLETION

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

EXTENDED COMPLETION

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

EXAMPLE

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