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       compctl [ -CDT ] options [ command ... ]
16       compctl [ -CDT ] options [ -x pattern options - ... -- ] [ + options  [
17       -x ... -- ] ... [+] ] [ command ... ]
18       compctl -M match-specs ...
19       compctl -L [ -CDTM ] [ command ... ]
20       compctl + command ...
21
22       Control  the editor's completion behavior according to the supplied set
23       of options.  Various editing commands, notably expand-or-complete-word,
24       usually  bound  to  tab,  will  attempt to complete a word typed by the
25       user, while others, notably delete-char-or-list, usually bound to ^D in
26       EMACS editing mode, list the possibilities; compctl controls what those
27       possibilities are.  They may for example be filenames (the most  common
28       case,  and  hence  the  default),  shell  variables,  or  words  from a
29       user-specified list.
30

COMMAND FLAGS

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

OPTION FLAGS

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