<html>
<head>
<title>A User's Guide to the Z-Shell </title>
</head>
<body >
<hr>
<ul>
<li> <a href="zshguide07.html">Next chapter</a>
<li> <a href="zshguide05.html">Previous chapter</a>
<li> <a href="zshguide.html">Table of contents</a>
</ul>
<hr>
<a name="comp"></a><a name="l30"></a>
<h1>Chapter 6: Completion, old and new</h1>
<p>Completion of command arguments is something zsh is particularly good at.
The simplest case is that you hit <code><TAB></code>, and the shell guesses what has
to go there and fills it in for you:
<pre>
% ls
myfile theirfile yourfile
% cat t<TAB>
</pre>
expands the command line to
<pre>
% cat theirfile
</pre>
and you only had to type the initial letter, then <code>TAB</code>.
<p>In the early days when this appeared in the C shell, only filenames could
be completed; there were no clever tricks to help you if the name was
ambiguous, it simply printed the unambiguous part and beeped so that you
had to decide what to do next. Later shells added extra features, so, for
example, you could list possible completions. For some reason this became
attached to the <code>^D</code> key in tcsh, which in shells with Emacs-like
bindings also deletes the next character:
<pre>
% cat yx
^ move cursor back onto the x and hit ^D twice and you see: yourfile
</pre>
--- that doesn't work if you use vi-like bindings.
<p>Next, it became possible to complete other items such as user names,
command names or hosts. Then zsh weighed in with menu completion, so you
could keep on blindly hitting <code><TAB></code> until the right answer appeared,
and never had to type an extra character yourself.
<p>The next development was tcsh's, and then zsh's, programmable completion
system; you could give instructions to the shell that in certain contexts,
only certain items should be completed; for example, after <code>cd</code>, you
would only want directories. In tcsh, there was a command called
<code>complete</code>; each `<code>complete ...</code>' statement defined the completion for
the arguments of a particular command, such as <code>cd</code>; the equivalent in
zsh is <code>compctl</code>, which was inspired by <code>complete</code> but is different in
virtually every significant detail. There is a perl script <code>lete2ctl</code> in
the <code>Misc</code> directory of the shell distribution to help you convert from
the tcsh to the zsh formats. You put a whole series of <code>compctl</code>
commands into <code>.zshrc</code>, and everything else is done by the shell.
<p>Zsh's system has become more and more sophisticated, and in version 3.1.6 a
new completion system appeared which is supposed to do everything for you:
you simply call a function, <code>compinit</code>, after which zsh knows, for
example, that <code>gunzip</code> should be followed by files ending in <code>.gz</code>.
The new systems is based on shell functions, an added bonus since they are
extremely flexible and you already know the syntax. However, given the
complexity it's quite difficult to get started writing your own completions
now, and hard enough to know what to do to change the settings the way you
like. The rest of the chapter should help.
<p>I shall concentrate on the new completion system, which seems destined to
take over completely from the old one eventually, after the 3.1 release
series becomes a production release (probably as 4.0). The old <strong>compctl</strong>
command is still available, and old completion definitions will remain
working in future versions of zsh --- in fact, on most operating systems
which support dynamically linked libraries the old completion system is in
a different file, which the shell loads when necessary, so there's very
little overhead for this.
<p>The big difference in the new system is that, instead of everything being
set up once and for all when the shell starts, various bits of shell code
are called after you hit <code><TAB></code>, to generate the completions there and
then. There's enough new in the shell that all those unmemorable options
to <code>compctl</code> (`<code>-f</code>' for files `<code>-v</code>' for variables and so on) can be
replaced by commands that produce the list of completions directly; the key
command in this case is called `<code>compadd</code>', which is passed this list and
decides what to use to complete the word on the command line. So the
simplest possible form of new completion looks roughly like this:
<pre>
# tell the shell that the function mycompletion can do completion
# when called by the widget name my-completion-widget, and that
# it behaves like the existing widget complete-word
zle -C my-completion-widget .complete-word mycompletion
# define a key that calls the completion widget
bindkey '^x^i' my-completion-widget
# define the function that will be called
mycompletion() {
# add a list of completions
compadd alpha bravo charlie delta
}
</pre>
That's very roughly what the completion system is doing, except that the
function is called <code>_main_complete</code> and calls a lot of other functions to
do its dirty work based on the context where completion was called (all the
things that <code>compctl</code> used to do), and the widgets are just the old
completion widgets (`<code>expand-or-complete</code>' etc.) redefined and still
bound to all the original keys. But, in case you hadn't guessed, there's
more to it than that.
<p>Here's a plan for the sections of this chapter.
<ol>
<li> A broad description of completion and expansion, applying
equally to old and new completion. After this, I shall leave the
<code>compctl</code> world behind.
<li> How to start up new completion.
<li> The basics of how the new completion system works.
<li> How to configure it using shell options.
<li> How to configure it using the new `<code>zstyle</code>' builtin.
<li> Separate commands which do something other than the usual
completion system, as well as some other editing widgets that have
to do with completion.
<li> Matching control, a powerful way of deciding such things as
whether to complete case insensitively, to allow insertion of extra
parts of words before punctuation characters, or to ignore certain
characters in the word on the command line.
<li> How to write your own completion functions; you won't need to
have too solid an understanding of all the foregoing just to do simple
completions, but I will gradually introduce the full baroque
splendour of how to make tags and styles work in your own functions,
and how to make completion do the work of handling command arguments
and options.
<li> Ends the chapter gracefully, on the old `beginning, middle, end'
principle.
</ol>
<p><a name="l31"></a>
<h2>6.1: Completion and expansion</h2>
<p>More things than just completion happen when you hit tab. The first thing
that zsh tries to do is expand the line. Expansion was covered in a
previous chapter: basically all the things described there are possible
candidates for expanding in-line by the editor, the only exception being
alias expansion. In other words, history substitutions with bangs, the
various expansions using `<code>$</code>' or backquote, and filename generation
(globbing) can all take place, with the result replacing what was there on
the command line:
<pre>
% echo $PWD<TAB>
-> echo /home/pws/zsh/projects/zshguide
% echo `print $ZSH_VERSION`<TAB>
-> echo 3.1.7
% echo !!<TAB>
-> echo echo 3.1.7
% echo ~/.z*<TAB>
-> echo /home/pws/.zcompdump /home/pws/.zlogout
/home/pws/.zshenv /home/pws/.zshrc
</pre>
Note that the `<code>~</code>' also gets expanded in this case.
<p>This is often a good time to remember the `undo' key, `<code>^_</code>' or
`<code>^Xu</code>'; typing this will restore what was there before the expansion if
you don't like the result. Many keyboards have a quirk that what's
described as `<code>^_</code>' should be typed as control with slash, which you'd
write `<code>^/</code>' except unfortunately that does something else; this is not
zsh's fault. There's another half-exception, namely filename generation:
paths like `<code>~/file</code>' don't get expanded, because you usually know what
they refer to and it's usually convenient to leave them for use in
completion. However, the `<code>=cmdname</code>' form does get expanded, unless you
have <code>NO_EQUALS</code> set.
<p>In fact, deciding whether expansion or completion takes place can sometimes
be tricky, since things that would be expanded if they were complete, may
need to be completed first; for example <code>$PAT</code> should probably be
completed to <code>$PATH</code>, but it's quite possible there is a parameter
<code>$PAT</code> too. You can decide which, if you prefer. First, the commands
<code>expand-word</code>, bound to `<code>^X*</code>', and the corresponding command for
listing what would be expanded, <code>list-expand</code>, bound to `<code>^Xg</code>', do
expansion only --- all possible forms except alias expansion, including
turning `<code>~/file</code>' into a full path.
<p>From the other point of view, you can use commands other than
<code>expand-or-complete</code>, the one bound by default to <code><TAB></code>, to perform
only completion. The basic command for this is <code>complete-word</code>, which is
not bound by default. It is quite sensible to bind this to `<code>^I</code>'
(i.e. <code><TAB></code>) if you are happy to use the separate commands for
expansion, i.e.
<pre>
# Now tab does only completion, not expansion
bindkey '^i' complete-word
</pre>
Furthermore, if you do this and use the new completion system,
then as we shall see there is a way of making the completion system perform
expansion --- see the description of the <code>_expand</code> completer below. In
this case you have much more control over what forms of expansion are
tried, and at what point, but you have to make sure you use
<code>complete-word</code>, not <code>expand-or-complete</code>, else the standard expansion
system will take over.
<p>There's a close relative of <code>expand-or-complete</code>,
<code>expand-or-complete-prefix</code>, not bound by default. The only difference
is that it will ignore everything under and to the right of the cursor when
completing. It's as if there was a space where the cursor was, with
everything to be ignored shifted to the right (guess how it's
implemented). Use this if you habitually type new words in the line before
other words, and expect them to complete or expand on their own even before
you've typed the space after them. Some other shells work this way all the
time. To be more explicit:
<pre>
% ls
filename1
% ls filex
</pre>
Move the cursor to the <code>x</code> and hit tab. With <code>expand-or-complete</code> nothing
happens; it's trying to complete a file called `<code>filex</code>' --- or, with the
option <code>COMPLETE_IN_WORD</code> set, it's trying to find a file whose name
starts with `<code>file</code>' and ends with `<code>x</code>'. If you do
<pre>
bindkey '^i' expand-or-complete-prefix
</pre>
and try the same experiment, you will find the whole thing is completed to
`<code>filename1x</code>', so that the `<code>x</code>' was ignored, but not removed.
<p>One possible trap is that the listing commands, both
<code>delete-char-or-list</code>, bound by default to `<code>^D</code>' in emacs mode, and
<code>list-options</code>, bound by default to `<code>^D</code>' in vi insert mode and the
basic command for listing completions as it doesn't have the
delete-character behaviour, do not show possible expansions, so with the
default bindings you can use `<code>^D</code>' to list, then hit <code><TAB></code> and find
that the line has been completely rewritten by some expansion. Using
<code>complete-word</code> instead of <code>expand-or-complete</code> will of course fix
this. If you know how to write new editor widgets (chapter 4), you can
make up a function which tries <code>list-expand</code>, and if that fails tries
<code>list-options</code>.
<p>There are four completion commands I haven't mentioned yet: three are
<code>menu-complete</code>, <code>menu-expand-or-complete</code> and
<code>reverse-menu-complete</code>, which perform menu completion, where you can
cycle through all possible completions by hitting the same key. The first
two correspond to <code>complete-word</code> and <code>expand-or-complete</code>
respectively, while the third has no real equivalent as it takes you
backwards through a completion list. The effect of the third can't be
reached just by setting options for menu completion, so it's a useful one
to bind separately. I have it bound to `<code>\M-\C-i</code>', i.e. tab with the
Meta key pressed down, but it's not bound by default.
<p>The fourth is <code>menu-select</code>, which performs an enhanced form of menu
completion called `menu selection' which I'll describe below when I talk
about options. You have to make sure the <code>zsh/complist</code> module is loaded
to use this zle command.
<p><a name="l32"></a>
<h2>6.2: Getting started with new completion</h2>
<p>Before I go into any detail about new completion, here's how to set it up so
that you can try it out. As I said above, the basic objects that do
completions are shell functions. These are all autoloaded, so the shell
needs to know where to find them via the <code>$fpath</code> array. If the shell
was installed properly, and nothing in the initialization files has
removed the required bits from <code>$fpath</code>, this should happen
automatically. It's even possible your system sets up completion for you
(Mandrake Linux 6.1 is the first system known to do this out of the box),
in which case type `<code>which compdef</code>' and you should see a complete shell
function --- actually the one which allows you to define additional
completion functions. Then you can skip the next paragraph.
<p>If you to load completion, try this at the command line:
<pre>
autoload -U compinit
compinit
</pre>
which should work silently. If not, you need to ask your system
administrator what has happened to the completion functions or find them
yourself, and then add all the required directories to your <code>$fpath</code>.
Either they will all be in one big directory, or in a set of subdirectories
with the names <code>Base</code>, <code>Builtins</code>, <code>Commands</code>, <code>Core</code>, <code>Debian</code>,
<code>Linux</code>, <code>User</code> and <code>X</code>; in the second case, all the directories need
to be in <code>$fpath</code>. When this works, you can add the same lines,
including any modification of <code>$fpath</code> you needed, to your <code>.zshrc</code>.
<p>You can now see if it's actually working. Type `<code>cd </code>', then <code>^D</code>, and
you should be presented with a list of directories only, no regular files.
If you have <code>$cdpath</code> set, you may see directories that don't appear with
<code>ls</code>. As this suggests, the completion system is supplied with
completions for many common (and some quite abstruse) commands. Indeed,
the idea is that for most users completion just works without intervention
most of the time. If you think it should when it doesn't, it may be a bug
or an oversight, and you should report it.
<p>Indeed, the completion system knows about more than just commands and their
arguments, it also understands some of the shell syntax. For example,
there's an associative array call <code>$_comps</code> which stores the names of
commands as keys and the names of completion functions as the corresponding
values. Try typing:
<pre>
print ${_comps[
</pre>
and then <code>^D</code>. You'll probably get a message asking if you really want
to see all the possible completions, i.e. the keys for <code>$_comps</code>; if you
say `<code>y</code>' you'll see a list. If you insert any of those
keys, then close the braces so you have e.g. `<code>${_comps[mozilla]}</code>' and
hit return, you'll see the completion function which handles that command;
in this case (at the time of writing) it's <code>_webbrowser</code>. This is
one way of finding out what function is handling a particular command. If
there is no entry --- i.e. the `<code>print ${_comps[mycmd]}</code>' gives you a
blank line --- then the command is not handled specially and will simply
use whatever function is defined for the `<code>-default-</code>' context, usually
<code>_default</code>. Usually this will just try to complete file names. You can
customize <code>_default</code>, if you like.
<p>Apart from <code>-default-</code>, some other of those keys for <code>_comps</code> also look
like <code>-this-</code>: they are special contexts, places other than the arguments
of a command. We were using the context called <code>-subscript-</code>; you'll
find that the function in this case is called <code>_subscript</code>. Many
completion functions have names which are simply an underscore followed by
the command or context name, minus any hyphens. If you want a taster of
how a completion function looks, try `<code>which _subscript</code>'; you may well
find there are a lot of other commands in there that you don't know yet.
<p>It's important to remember that the function found in this way is at the
root of how a completion is performed. No amount of fiddling with options
or styles --- the stuff I'm going to be talking about for the next few
sections --- will change that; if you want to change the basic completion,
you will just have to write your own function.
<p>By the way, you may have old-style completions you want to mix-in --- or
maybe you specifically don't want to mix them in so that you can make sure
everything is working with the new format. By default, the new completion
system will first try to find a specific new-style completion, and if it
can't it will try to find a <code>compctl</code>-defined completion for the command
in question. If all that fails, it will try the usual new-style default
completion, probably just filename completion. Note that specific
new-style completions take precedence, which is fair enough, since if
you've added them you almost certainly don't want to go back and use the
old form. However, if you don't ever want to try old-style completion, you
can put the following incantation in your <code>.zshrc</code> (from version 3.1.7
onward):
<pre>
zstyle ':completion:*' use-compctl false
</pre>
For now, that's just black magic, but later I will explain the `style'
mechanism in more detail and you will see that this fits in with the normal
way of turning things off in new-style completion.
<p><a name="l33"></a>
<h2>6.3: How the shell finds the right completions</h2>
<p><a name="l34"></a>
<h3>6.3.1: Contexts</h3>
<p>The examples above show that the completion system is highly
context-sensitive, so it's important to know how these contexts are
described. This and the next section refer to a mechanism which appeared
in version 3.1.7. If you are reading this before the release of 3.1.7, it
is safe to assume that the features are already available in the latest
intermediate development version, which you will find in the
`<code>development</code>' subdirectory on the zsh archive and its mirrors. The
same is true anywhere I mention 3.1.7.
<p>The full `context' is the complete description about what
state we are at in completion, and is given as a sort of
colon-separated path, starting with the least specific part. There's an
easy way of finding out what context you are in: at the point where you
want to complete something, instead type `<code>^Xh</code>', and it will tell you.
In the case of the <code>$_comps</code> example, you will find,
<pre>
:completion::complete:-subscript-::
</pre>
plus a list of so-called `tags' and completion functions, which I'll talk
about later. The full form is:
<pre>
:completion:<func>:<completer>:<command>:<argument>:<tag>
</pre>
where the elements may be missing if they are not set, but the colons will
always be there to make pattern matching easier. Here's what the bits of
the context mean after the <code>:completion:</code> part, which is common to the
whole completion system.
<dl>
<p></p><dt><strong><code><func></code></strong><dd> is the name of a function from which completion is
called --- this is blank if it was started from the standard completion
system, and only appears in a few special cases, listed in section six
of this chapter.
<p></p><dt><strong><code><completer></code></strong><dd> is called `<code>complete</code>' in this case: this
refers to the fact the completion system can do more than just simple
completion; for example, it can do a more controlled form of expansion
(as I mentioned), spelling correction, and completing words with
spelling mistakes. I'll introduce the other completers later;
`<code>complete</code>' is the simplest one, which just does basic completion.
<p></p><dt><strong><code><command></code></strong><dd> is the name of a command or other similar context
as described above, here `<code>-subscript-</code>'.
<p></p><dt><strong><code><argument></code></strong><dd> is most useful when <code><command></code> is the name
of a real command; it describes where in the arguments to that command
we are. You'll see how it works in a moment. Many of the more simple
completions don't use this; only the ones with complicated option and
argument combinations. You just have to find out with <code>^Xh</code> if
you need to know.
<p></p><dt><strong><code><tag></code></strong><dd> describes the type of a completion, essentially a way
of discriminating between the different things which can be completed
at the same point on the command line.
</dl>
<p>Now look at the context for a more normal command-argument completion,
e.g. after <code>cd</code>; here you'll see the context
`<code>:completion::complete:cd::</code>'. Here the command-name part of the context
is a real command.
<p>For something more complicated, try after `<code>cvs add</code>' (it doesn't matter
for this if you don't have the <code>cvs</code> command). You'll see a long and
repetitive list of tags, for two possible contexts,
`<code>:completion::complete:cvs:argument-rest:</code>' and
`<code>:completion::complete:cvs-add:argument-rest:</code>'. The reason you have
both is that the `<code>add</code>' is not only an argument to <code>cvs</code>, as the first
context would suggest, it's also a subcommand in its own right, with its
own arguments, and that's what the second context is for. The first
context implies there might be more subcommands after `<code>add</code>' and its
arguments which are completely separate from them --- though in fact CVS
doesn't work that way, so that form won't give you any completions here.
<p>In both, `<code>argument-rest</code>' shows that completion is looking for another
argument, the `<code>rest</code>' indicating that it is the list of arguments at the
end of the line; if position were important (see `<code>cvs import</code>' for an
example), the context would contain `<code>argument-1</code>', or whatever. The
`<code>cvs-add</code>' shows how subcommands are handled, by separating with a
hyphen instead of a colon, so as not to confuse the different bits of the
context.
<p>Apart from arguments to commands and subcommands, arguments to options are
another frequent possibility; for an example of this, try typing <code>^Xh</code>
after `<code>dvips -o</code>' and you will see the context
`<code>:completion::complete:dvips:-o-1:</code>'; this shows you are completing the
first argument to <code>dvips</code>'s <code>-o</code> option, (it only takes one argument)
which happens to be the name of a file for output.
<p><a name="l35"></a>
<h3>6.3.2: Tags</h3>
<p>Now on to the other matter to do with contexts, tags. Let's go back and
look at the output from the <code>^Xh</code> help test after the <code>cd</code> command in
full:
<pre>
tags in context :completion::complete:cd::
directory-stack (_popd _cd)
local-directories path-directories (_alternative _cd)
</pre>
Unlike the contexts considered so far, which tell you how completion
arrived at the point it did, the tags describe the things it can complete
here. In this case, there are three: <code>directory-stack</code> refers to entries
such as `<code>+1</code>'; the directory stack is the set of directories defined by
using the <code>pushd</code> command, which you can see by using the <code>dirs</code>
command. Next, <code>local-directories</code> refers to subdirectories of the
current working directory, while <code>path-directories</code> refers to any
directories found by searching the <code>$cdpath</code> array. Each of the possible
completions which the system offers belongs to one of those classes.
<p>In parentheses, you see the names of the functions which were called to
generate the completions; these are what you need to change or replace if
you want to alter the basic completion behaviour. Calling functions
appear on the right and called functions on the left, so that in this case
the function `<code>_cd</code>' was the function first called to handle arguments
for the <code>cd</code> command, fitting the usual convention.
<p>Maybe it's already obvious that having the system treat different types of
completion in different ways is useful, but here's an example, which gives
you a preview of the `styles' mechanism, discussed later. Styles are a
sort of glorified shell parameter; they are defined with the <code>zstyle</code>
command, using a style name and possible values which may be an array; you
can always define a style as an array, but some styles may simply use it as
a string with the arguments joined with spaces. You can also use the
<code>zstyle</code> command, with different arguments, to retrieve their value,
which is what the completion system itself does; there's no actual overlap
with parameters and their values, so they don't get in the way of normal
shell programming.
<p>Where styles differ from parameters is that they can take different
values in different contexts. The first argument to the <code>zstyle</code> command
gives a context; when you're defining styles, it's actually a pattern which
will be matched against contexts to see if it applies. The rule for
finding out what applies is: exact string matches are preferred before
patterns, and longer patterns are preferred before shorter patterns.
Here's that example:
<pre>
zstyle ':completion:*:cd:*' tag-order local-directories path-directories
</pre>
From the discussion of contexts above, the pattern will match any time an
argument to the <code>cd</code> command is being completed. The style being set is
called <code>tag-order</code>, and the values are the two tags valid for directories
in <code>cd</code>.
<p>The <code>tag-order</code> style determines the order in which tags are tried. The
value given above means that first <code>local-directories</code> will be completed;
only if none can be completed will <code>path-directories</code> be tried. You can
enter the command and try this; if you don't have <code>$cdpath</code> set up you
can assign `<code>cdpath=(~)</code>', which will allow `<code>cd foo</code>' to change to a
directory `<code>~/foo</code>' and allow completion of directories accordingly. Go
to a directory other than <code>~</code>; completion for <code>cd</code> will only show
subdirectories of where you are, not those of <code>~</code>, unless you type a
string which is the prefix of a directory under <code>~</code> but not your current
directory. For example,
<pre>
% cdpath=(~)
% ls -F ~
foo/ bar/
% ls -F
rod/ stick/
# Without that tag-order zstyle command, you would get...
% cd ^D
bar/ foo/ rod/ stick/
% zstyle ':completion:*:cd:*' tag-order local-directories path-directories
# now you just get the local directories, if there are any...
% cd ^D
rod/ stick
</pre>
<p>There's more you can do with the <code>tag-order</code> style: if you put the tags
into the same word by quoting, for example <code>"local-directories
path-directories"</code>, then they would be tried at the same time, which in
this case gives you the effect of the default. In fact, since it's too
much work to know what tags are going to be available for every single
possible completion, the default when there is no appropriate <code>tag-order</code>
is simply to try all the tags available in the context at once; this was of
course what was originally happening for completion after <code>cd</code>.
<p>Even if there is a <code>tag-order</code> specification, any tags not specified will
usually be tried all together at the end, so you could actually have missed
out <code>path-directories</code> from the end of the original example and the
effect would have been the same. If you don't want that to happen, you can
specify a `<code>-</code>' somewhere in the list of tags, which is not used as a tag
but tells completion that only the tags in the list should be tried, not
any others that may be available. Also, if you don't want a particular tag
to be shown you can include `<code>!tagname</code>' in the values, and all the
others but this will be included. For example, you may have noticed that
when completing in command position you are offered parameters to set as
well as commands etc.:
<pre>
Completing external command
tex texhash texi2pdf text2sf
texconfig texi2dvi texindex textmode
texdoc texi2dvi4a2ps texlinks texutil
texexec texi2html texshow texview
Completing parameter
TEXINPUTS texinputs
</pre>
(I haven't told you how to produce those descriptions, or how to make the
completions for different tags appear separately, but I will --- see the
descriptions of the `<code>format</code>' and `<code>group-name</code>' styles below.)
If you set
<pre>
zstyle ':completion:*:-command-:*' tag-order '!parameters'
</pre>
then the last two lines will disappear from the completion. Of course,
your completion list probably looks completely different from mine anyway.
By the way, one good thing about styles is that it doesn't matter whether
they're defined before or after completion is loaded, since styles are
stored and retrieved by another part of the shell.
<p>To exclude more than one tag name, you need to include the names in the
same word. For example, to exclude both parameters and reserved words the
value would be <code>'!parameters reserved-words'</code>, and <em>not</em>
<code>'!parameters' '!reserved-words'</code>, which would try completion once with
parameters excluded, then again with reserved words excluded. See the
manual for all the tag names understood by the supplied functions.
<p>Finally, you can also ask a function to be called to sort the order of the
tags as you wish by including the name of the function with parentheses at
the end in the list of values: `<code>funcname()</code>'. There is an example
function <code>_sort_tags</code> (not actually used) to show you how such a function
should be written, and it is described in the manual.
<p>One important note about <code>tag-order</code>: <em>it doesn't change which tags are
actually valid in that completion</em>. Just putting a tag name into it
doesn't mean that tag name will be used; that's determined entirely by the
completion functions for a particular context. The <code>tag-order</code> style
simply alters the order in which the tags which <em>are</em> valid are examined.
Come back and read this paragraph again when you can't work out why
<code>tag-order</code> isn't doing what you want.
<p>Note that the rule for testing patterns means that you can always specify a
catch-all worst case by `<code>zstyle "*" style ...</code>', which will always be
tried last --- not just in completion, in fact, since other parts of the
shell use the styles mechanism, and without the `<code>:completion:</code>' at the
start of the context this style definition will be picked up there, too.
<p>Styles like <code>tag-order</code> are the most important case where tags are used
on their own. In other cases, they can be added to the end of the context;
this is useful for styles which can give different results for different
sets of completions, in particular styles that determine how the list of
completions is displayed, or how a completion is to be inserted into the
command line. The tag is the final element, so is not followed by a colon.
A full context then looks something like
`<code>:completion::complete:cd::path-directories</code>'. Later, you'll see some
styles which can usefully be different for different tag contexts.
Remember, however, that the tags part of the context, like other parts, may
be empty if the completion system hasn't figured out what it should be
yet.
<p><a name="l36"></a>
<h2>6.4: Configuring completion using shell options</h2>
<p>There are two main ways of altering the behaviour of completion without
writing or rewriting shell functions: shell options, as introduced in
chapter 2, and styles, as introduced above. I shall first discuss the
shell options, although as you will see some of these refer to the styles
mechanism. Setting shell options affects every single completion, unless
special care has been taken (using a corresponding style for the context,
or setting an option locally) to avoid that.
<p>In addition to the options which directly affect the completion system,
completion is sensitive to various other options which describe shell
behaviour. For example, if the option <code>MAGIC_EQUAL_SUBST</code> is set, so
that arguments of all commands looking like `<code>foo=~/file</code>' have the
`<code>~</code>' expanded as if it was at the start of an argument, then the default
completion for arguments of commands not specially handled will try to
complete filenames after the `<code>=</code>'.
<p>Needless to say, if you write completion functions you will need to worry
about a lot of other options which can affect shell syntax. The main
starting point for completion chosen by context (everything except the
special commands bound separately to keystrokes) is the function
<code>_main_complete</code>, which includes the following lines to make sure that at
least the basic options are set up within completion functions:
<pre>
setopt localoptions nullglob rcexpandparam extendedglob
unsetopt markdirs globsubst shwordsplit nounset ksharrays
</pre>
but that by no means exhausts the possibilities.
<p><a name="l37"></a>
<h3>6.4.1: Ambiguous completions</h3>
<p>The largest group of options deals with what happens when a completion
is ambiguous, in other words there is more than one possible completion.
The seven relevant options are as follows, as copied from the FAQ;
many different combinations are possible:
<dl>
<li > with <code>NO_BEEP</code> set, that annoying beep goes away
<li > with <code>NO_LIST_BEEP</code>, beeping is only turned off for ambiguous
completions
<li > with <code>AUTO_LIST</code> set, when the completion is ambiguous you get a
list without having to type <code>\C-D</code>
<li > with <code>BASH_AUTO_LIST</code> set, the list only happens the second
time you hit tab on an ambiguous completion
<li > with <code>LIST_AMBIGUOUS</code>, this is modified so that nothing is listed if
there is an unambiguous prefix or suffix to be inserted --- this
can be combined with <code>BASH_AUTO_LIST</code>, so that where both are
applicable you need to hit tab three times for a listing.
<li > with <code>REC_EXACT</code>, if the string on the command line exactly matches
one of the possible completions, it is accepted, even if there is
another completion (i.e. that string with something else added) that
also matches.
<li > with <code>MENU_COMPLETE</code> set, one completion is always inserted
completely, then when you hit TAB it changes to the next, and so
on until you get back to where you started
<li > with <code>AUTO_MENU</code>, you only get the menu behaviour when you hit TAB
again on the ambiguous completion.
</dl>
<p><a name="l38"></a>
<h3>6.4.2: <code>ALWAYS_LAST_PROMPT</code></h3>
<p>The option <code>ALWAYS_LAST_PROMPT</code> is set by default, and has been since an
earlier 3.1 release of zsh; after listing a completion, the cursor is taken
back to the line it was on before, instead of reprinting it underneath. The
downside of this is that the listing will be obscured when you execute the
command or produce a different listing, so you may want to unset the
option. <code>ALWAYS_LAST_PROMPT</code> behaviour is required for menu selection to
work, which is why I mention it now instead of in the ragbag below.
<p><a name="l39"></a>
<h3>6.4.3: Menu completion and menu selection</h3>
<p>The most significant matter decided by the options above is whether or not
you are using menu completion. If you are not, you will need to type the
next character explicitly when completion is ambiguous; if you are, you
just need to keep hitting tab until the completion you want appears. In
the second case, of course, this works best if there are not too many
possibilities. Use of <code>AUTO_MENU</code> or binding the <code>menu-complete</code>
widget to a separate key-stroke gives you something of both worlds.
<p>A new variant of menu completion appeared in 3.1.6; in fact, it deserves
the name menu completion rather more than the original form, but since that
name was taken it is called `menu selection'. It is implemented by a
separate module, <code>zsh/complist</code>; you can make sure this is loaded by
putting `<code>zmodload -i zsh/complist</code>' in <code>.zshrc</code>. For it to be useful,
you need two other things. The first is <code>ALWAYS_LAST_PROMPT</code> behaviour;
this is suppressed if the whole completion list won't appear on the screen,
since there's no line on the screen to go back to, hence menu selection is
also turned off in this case. The second thing is that you need to start
menu completion in any of the usual ways; menu selection is an addition to
menu completion, not a replacement.
<p>Now you should set the following style:
<pre>
zstyle ':completion:*' menu select=<NUM>
</pre>
If an ambiguous completion produces at least <code><NUM></code> possibilities, menu
selection is started. You can understand this best by trying it. One of
the completions in the list, initially the top-leftmost, is highlighted and
inserted into the line. By moving the cursors in the obvious directions
(with wraparound at the edges), you change both the value highlighted and
the value inserted into the line. When you have the value you want, hit
return, which removes the list and leaves the inserted value. The same
happens if you abort with <code>^g</code>, so you will need to use <code>undo</code> to
remove the completion if you don't want it.
<p>Internally, zsh actually uses the parameter <code>$SELECTMIN</code> to supply the
number and hence start menu selection. However, this is always initialised
from the style as defined above, so you shouldn't set <code>$SELECTMIN</code>
directly, unless you are still using version 3.1.6 of the shell. As with
other styles, you can specify different values for different contexts; the
<code>default</code> tag is checked if the current context does not produce a value
for the style with whatever the current tag is. Note that the <code>menu</code>
style also allows you to control whether menu completion is started at all,
with or without selection; in other words, it is a style corresponding to
the <code>MENU_COMPLETE</code> option.
<p>There is one other additional feature when using menu selection. The
zle command <code>accept-and-infer-next-history</code> has a different meaning here;
it accepts a completion, and then tries to complete again using menu
selection. This is very useful with directory hierarchies, and in
combination with <code>undo</code> gives you a simple file browser. You need to
bind it in the special keymap <code>menuselect</code>; for example, I use
<pre>
bindkey -M menuselect '^o' accept-and-infer-next-history
</pre>
because the behaviour reminds me of what is usually bound to <code>^O</code> in
emacs modes, namely <code>accept-line-and-down-history</code>. Binding it like this
has no effect on <code>^O</code> in the normal keymaps. Try it out by entering menu
selection on a set of files including directories, and typing <code>^O</code> on one
of the directories. You should immediately have the contents of that
directory presented for the next selection, while <code>undo</code> is smart enough
not only to remove that selection but return to completion on the parent
directory.
<p>You can choose the manner in which the currently selected value in the
completion list is highlighted using exactly the same mechanism as for
specifying colours for particular types of matches; see the description of
the <code>list-colors</code> style below.
<p><a name="l40"></a>
<h3>6.4.4: Other ways of changing completion behaviour</h3>
<p><p><strong><code>COMPLETE_ALIASES</code></strong><br><br>
<p>If you set an alias such as
<pre>
alias pu=pushd
</pre>
then the alias `<code>pu</code>' will be expanded when the completion system is
looking for the name of the command, so that it will instead find the
command name `<code>pushd</code>'. This is quite useful to avoid having to define
extra completions for all your aliases. However, it's possible you may
want to define something different for the alias than for the command it
expands to. In that case, you will need to set <code>COMPLETE_ALIASES</code>, and
to make arrangements for completing after every alias which does not
already match the name of a command. Hence `<code>alias zcat="myzcat -dc"</code>'
will work with the option set, even if you haven't told the system about
`<code>myzcat</code>', while `<code>alias myzcat="gzip -dc"</code>' will not work unless you
do define a completion for myzcat: here `<code>compdef _gzip myzcat</code>' would
probably be good enough.
<p><p><strong><code>AUTO_REMOVE_SLASH</code></strong><br><br>
<p>This option is turned on by default. If you complete a directory name and
a slash is added --- which it usually is, both to tell you that you have
completed a directory and to allow you to complete files inside it without
adding a `<code>/</code>' by hand --- and the next thing you type is <em>not</em>
something which would insert or complete part of a file in that directory,
then the slash is removed. Hence:
<pre>
% rmdir my<TAB>
-> rmdir mydir/
% rmdir mydir/<RETURN>
-> `rmdir mydir' executed
</pre>
This example shows why this behaviour was added: some versions of
`<code>rmdir</code>' baulk at having the slash after the directory name. On the
other hand, if you continued typing after the slash, or hit tab again to
complete inside <code>mydir</code>, then the slash would remain.
<p>This is at worst harmless under most circumstances. However, you can unset
the option <code>AUTO_REMOVE_SLASH</code> if you don't like that behaviour. One
thing that may cause slight confusion, although it is the same as with
other suffixes (i.e. bits which get added automatically but aren't part of
the value being completed), is that the slash is added straight away if the
value is being inserted by menu completion. This might cause you to think
wrongly that the completion is finished, and hence was unique, when it
wasn't.
<p>Note that some forms of completion have this type of behaviour built in, not
necessarily with a slash, when completing lists of arguments. For example,
enter `<code>typeset ZSH_V<TAB></code>' and you will see `<code>ZSH_VERSION=</code>' appear,
in case you want to assign something to the parameter; hitting space, which
is not a possible value, makes the `<code>=</code>' disappear. This is not
controlled by the <code>AUTO_REMOVE_SLASH</code> option, which applies only to
directories inserted by the standard filename completion system.
<p><p><strong><code>AUTO_PARAM_SLASH</code>, <code>AUTO_PARAM_KEYS</code></strong><br><br>
<p>These options come into effect when completing expressions with parameter
substitutions. If <code>AUTO_PARAM_SLASH</code> is set, then any parameter
expression whose value is the name of a directory will have a slash
appended when completed, just as if the value itself had been inserted by
the completion system.
<p>The behaviour for <code>AUTO_PARAM_KEYS</code> is a bit more complicated. Try this:
<pre>
print ${ZSH_V<TAB>
</pre>
You will find that you get the complete word `<code>${ZSH_VERSION}</code>', with the
closing brace and (assuming there are no other matching parameters) a space
afterwards. However, often after you have completed a parameter in this
fashion you want to type something immediately after it, such as a
subscript. With <code>AUTO_PARAM_KEYS</code>, if you type something at this point
which seems likely to have to go after the parameter name, it will
immediately be put there without you having to delete the intervening
characters --- try it with `<code>[</code>', for example. Note that this only
happens if the parameter name and any extra bits were added by completion;
if you type everything by hand, typing `<code>[</code>' will not have this magic
effect.
<p><p><strong><code>COMPLETE_IN_WORD</code></strong><br><br>
<p>If this is set, completion always takes place at the cursor position in the
word. For example if you typed `<code>Mafile</code>', went back over the `<code>f</code>',
and hit tab, the shell would complete `<code>Makefile</code>', instead of its usual
behaviour of going to the end of the word and trying to find a completion
there, i.e. something matching `<code>Mafile*</code>'. Some sorts of new completion
(such as filename completion) seem to implement this behaviour regardless
of the option setting; some other features (such as the `<code>_prefix</code>'
completer described below) require it, so it's a good thing to set and get
used to, unless you really need to complete only at the end of the word.
<p><p><strong>ALWAYS_TO_END</strong><br><br>
<p>If this is set, the cursor is always moved to the end of the word after it
is completed, even if completion took place in the middle. This also
happens with menu completion.
<p><a name="l41"></a>
<h3>6.4.5: Changing the way completions are displayed</h3>
<p><p><strong><code>LIST_TYPES</code></strong><br><br>
<p>This is like the <code>-F</code> option to <code>ls</code>; files which appear in the
completion listing have a trailing `<code>/</code>' for a directory, `<code>*</code>' for a
regular file executable by the current process, `<code>@</code>' for a link, `<code>|</code>'
for a named pipe, `<code>%</code>' for a character device and `<code>#</code>' for a block
device. This option is on by default.
<p>Note that the identifiers only appear if the completion system knows that
the item is supposed to be a file. This is automatic if the usual filename
completion commands are used. There is also an option <code>-f</code> to the
builtin <code>compadd</code> if you write your own completion function and want to
tell the shell that the values may be existing files to apply
<code>LIST_TYPES</code> to (though no harm is caused if no such files exist).
<p><p><strong><code>LIST_PACKED</code>, <code>LIST_ROWS_FIRST</code></strong><br><br>
<p>These affect the arrangement of the completion listing. With
<code>LIST_PACKED</code>, completion lists are made as compact as possible by
varying the widths of the columns, instead of being formatted into a
completely regular grid. With <code>LIST_ROWS_FIRST</code>, the listing order is
changed so that adjacent items appear along rows instead of down columns,
rather like <code>ls</code>'s <code>-x</code> option.
<p>It is possible to alter both these for particular contexts using the styles
<code>list-packed</code> and <code>list-rows-first</code>. The styles in such cases always
override the option; the option setting is used if no corresponding style
is found.
<p>Note also the discussion of completion groups later on: it is possible to
have different types of completion appear in separate lists, which may then
be formatted differently using these tag-sensitive styles.
<p><a name="l42"></a>
<h2>6.5: Configuring completion using styles</h2>
<p>You now know how to define a style for a particular context, using
<pre>
zstyle <context> <style> <value...>
</pre>
and some of the cases where it's useful. Before introducing other
styles, here's some more detailed information. I already said that styles
could take an array value, i.e. a set of values at the end of the
<code>zstyle</code> command corresponding to the array elements, and you've already
seen one case (<code>tag-order</code>) where that is useful. Many styles only
use one value, however. There is a particularly common case, where you
simply want to turn a value on or off, i.e. a boolean value. In this case,
you can use any of `<code>true</code>', `<code>yes</code>', `<code>on</code>' or `<code>1</code>' for on and
`<code>false</code>', `<code>no</code>', `<code>off</code>' or `<code>0</code>' for off. You define all styles
the same way; only when they're used is it decided whether they should be a
scalar, an array, or a boolean, nor is the name of a style checked to see
if it is valid, since the shell doesn't know what styles might later be
looked up. The same obviously goes for contexts.
<p>You can list existing styles (not individually, only as a complete list)
using either `<code>zstyle</code>' or `<code>zstyle -L</code>'. In the second case, they are
output as the set of <code>zstyle</code> commands which would regenerate the styles
currently defined. This is also useful with <code>grep</code>, since you can easily
check all possible contexts for a particular style.
<p>Finally, you can delete a context for a style or a list of styles by
<pre>
zstyle -d [ <context-pattern> [ <style> ] ] ...
</pre>
--- note that although the first argument is a pattern, in this case it is
treated exactly, so if you give the pattern `<code>:completion:*:cd:*</code>', only
values given with <em>exactly</em> that pattern will be deleted, not other
values whose context begins with `<code>:completion:</code>' and contains
`<code>:cd:</code>'. The pattern and the style are optional when deleting; if
omitted, all styles for the context, or all styles of any sort, are
deleted. The completion system has its own defaults, but these are
builtin, so anything you specify takes precedence.
<p>The rest of this section describes some useful styles. It's up to you to
experiment with contexts if you want the style's values to be different in
different places, or just use `<code>*</code>' if you don't care.
<p><a name="l43"></a>
<h3>6.5.1: Specifying completers and their options</h3>
<p>`Completers' are the behind-the-scenes functions that decide what sort of
completion is being done. You set what completers to use with the
`<code>completer</code>' style, which takes an array of completers to try in order.
For example,
<pre>
zstyle ':completion:*' completer _complete _correct _approximate
</pre>
specifies that first normal completion will be tried (`<code>_complete</code>'),
then spelling correction (`<code>_correct</code>'), and finally approximate
completion (`<code>_approximate</code>'), which is essentially the combined effect
of the previous two, i.e. complete the word typed but allow for spelling
mistakes. All completers set the context, so inside <code>_complete</code> you will
usually find `<code>:completion::complete:...</code>', inside correction
`<code>:completion::correct:..</code>', and so on. Here is a more detailed
description of the existing completers; they are all functions, so you can
simply copy and modify one to make your own completer.
<p><p><strong><code>_complete</code></strong><br><br>
<p>This is the basic completion behaviour, which we've been assuming up to
now. Its major use is simply to check the context --- here meaning
whether we are completing a normal command argument or one of the special
`<code>-context-</code>' places --- and call the appropriate completion function.
It's possible to trick it by setting the parameter `<code>compcontext</code>' which
will be used instead of the one generated automatically; this can be useful
if you write your own completion commands for special cases. If you do
this, you should make the parameter local to your function.
<p><p><strong><code>_approximate</code></strong><br><br>
<p>This does approximate completion: it's actually written as a wrapper for
the <code>_complete</code> completer, so it does all the things that does, but it
also sets up the system to allow completions with misspellings. Typically,
you would want to try to complete without misspellings first, so this
completer usually appears after <code>_complete</code> in the <code>completers</code>
style.
<p>The main means of control is via the <code>max-errors</code> style. You can set
this to the maximum number of errors to allow. An error is defined as
described in the manual for approximate pattern matching: a character
missing such as `<code>rhythm</code>' / `<code>rhytm</code>', an extra character such as
`<code>rhythm</code>' / `<code>rhythms</code>', an incorrect character such as `<code>rhythm</code>' /
`<code>rhxthm</code>', or a pair of characters transposed such as `<code>rhythm</code>'
`<code>rhyhtm</code>' each count as one error. Approximation will first
try to find a match or matches with one error, then two errors, and so on,
up to and including the value of <code>max-errors</code>; the set of matches with
the lowest number of errors is chosen, so that even if you set
<code>max-errors</code> large, matches with a lower number of errors will always be
preferred. The real problems with setting a large <code>max-errors</code> are that
it will be slower, and is more likely to generate matches completely unlike
what you want --- with typing errors, two or three are probably the most
you need. Otherwise, there's always Mavis Beacon. Hence:
<pre>
% zstyle ':completion:*' max-errors 2
# just for the sake of example...
% zstyle ':completion:*' completer _approximate
% ls
ashes sackcloth
% echo siccl<TAB>
-> echo sackcloth
% echo zicc<TAB>
<Beep.>
</pre>
because `<code>s[i/a]c[k]cloth</code>' is only two errors, while
`<code>[z/s][i/a]c[k]cloth</code>' would be three, so doesn't complete.
<p>There's another way to give a maximum number of errors, using the numeric
prefix specified with <code>ESC-<digit></code> in Emacs mode, directly with number
keys in vi command mode, or with <code>universal-argument</code>. To enable this,
you have to include the string <code>numeric</code> as one of the values for
<code>max-errors</code> --- hence this can actually be an array, e.g.
<code>
zstyle ':completion:*:approximate:*' max-errors 2 numeric
</code>
allows up to two errors automatically, but you can specify a higher maximum
by giving a prefix to the completion command. So to continue the example
above, enter the new <code>zstyle</code> and:
<pre>
% echo zicc<ESC-3><TAB>
-> echo sackcloth
</pre>
because we've allowed three errors. You can start to see the problems with
allowing too many errors: if you had the file `<code>zucchini</code>', that would
be only one error away, and would be found and inserted before
`<code>sackcloth</code>' was even considered.
<p>Note that the context is examined straightaway in the completer, so at this
stage it is simple `<code>:completion::approximate:::</code>'; no more detailed
contextual information is available, so it is not possible to specify
different <code>max-errors</code> for different commands or tags.
<p>The final possibility as a value for the style is `<code>not-numeric</code>': that
means if any numeric prefix is given, approximation will not be done at
all. In the last example, completion would have to find a file beginning
`<code>zicc</code>'.
<p>Other minor styles also control approximation. The style <code>original</code>, if
true means the original value is always treated as a possible completion,
even if it doesn't match anything and even if nothing else matched.
Completing the original and the corrections use different tags,
unimaginatively called <code>original</code> and <code>corrections</code>, so you can
organise this with the <code>tag-order</code> style.
<p>Because the completions in this case usually don't match what's already on
the command line, and may well not match each other, menu completion is
entered straight away for you to pick a completion. You can arrange that
this doesn't happen if there is an unambiguous piece at the start to insert
first by setting the boolean style <code>insert-unambiguous</code>.
<p>Those last two styles (<code>original</code> and <code>insert-unambiguous</code>) are
looked up quite early on, when the context for generating corrections is
being set up, so that only the context up to the completer name is
available. The completer name will be followed by a hyphen and the number
of errors currently being accepted. So for trying approximation with one
error the context is `<code>:completion::approximate-1:::</code>'; if that fails and
the system needs to look for completion with two errors, the context will
be `<code>:completion::approximate-2:::</code>', and so on; the same happens with
correction and `<code>correct-1</code>', etc., for the completer described next.
<p><p><strong><code>_correct</code></strong><br><br>
<p>This is very similar to <code>_approximate</code>, except that the context is
`<code>:completion::correct:*</code>' (or `<code>:completion::correct-<num>:*</code>' when
generating corrections, as described immediately above) and it won't
perform completion, just spelling correction, so extra characters which the
completer has to add at the end of the word on the line now count as extra
errors instead of completing in the ordinary way: <code>zicc</code> is woefully far
from <code>sackcloth</code>, seven errors, but <code>ziccloth</code> only counts three again.
The <code>_correct</code> completer is controlled in just the same way as
<code>_approximate</code>.
<p>There is a separate command which only does correction and nothing else,
usually bound to `<code>^Xc</code>', so if you are happy using that you don't need
to include <code>_correct</code> in the list of completers. If you do include it,
and you also have <code>_approximate</code>, <code>_correct</code> should come earlier;
<code>_approximate</code> is bound to generate all the matches <code>_correct</code> does,
and probably more. Like other separate completion commands, it has its own
context, here beginning `<code>:completion:correct-word:</code>', so it's easy to
make this command behave differently from the normal completers.
<p>Old-timers will remember that there is another form of spelling correction
built into the shell, called with `<code>ESC-$</code>' or `<code>ESC-s</code>'. This only
corrects filenames and doesn't understand anything about the new completion
mechanism; the only reason for using it is that it may well be faster.
However, if you use the <code>CORRECT</code> or <code>CORRECT_ALL</code> shell options, you
will be using the old filename correction mechanism; it's not yet possible
to alter this.
<p><p><strong><code>_expand</code></strong><br><br>
<p>This actually performs expansion, not completion; the difference was
explained at the start of the chapter. If you use it, you should bind tab
to <code>complete-word</code>, not <code>expand-or-complete</code>, since otherwise expansion
will be performed before the completion mechanism is started up. As
expansion should still usually be attempted before completion, this
completer should appear before <code>_complete</code> and its relatives in the
list of values for the <code>completers</code> style.
<p>The reason for using this completer instead of normal expansion is that you
can control which expansions are performed using styles in the
`<code>:completion:*:expand:*</code>' context. Here are the relevant styles: it's
important to note that they are all off by default --- you must set the
styles you need for <code>_expand</code> to have any effect at all.
<dl>
<p></p><dt><strong><code>glob</code></strong><dd> expands glob expressions, in other words does filename
generation using wildcards.
<p></p><dt><strong><code>substitute</code></strong><dd> expands expressions including and active `<code>$</code>' or
backquotes.
<p></p><dt><strong><code>completions</code></strong><dd> performs ordinary completion. The use for this is
that the completions are inserted in the same way as expansions, by
default the whole list at once, instead of picking one as with
the <code>_complete</code> completer and its relatives. So if you use the
feature in the next paragraph, you can arrange that completion with
a particular numeric prefix inserts all completions.
</dl>
<p>Each of the style values should be a numeric expression, where a value of 1
means to attempt that sort of expansion, so that an explicit `<code>0</code>' turns
that sort of expansion off and `<code>1</code>' turns it on. The reason for having a
numeric expression, not just a number or a boolean, is that you can arrange
tests for whether that expansion should be performed. For example (taken
from the manual):
<pre>
zstyle ':completion:*:expand:*' substitute '${NUMERIC:-1} != 1'
</pre>
tests whether the numeric prefix was given and was not 1; only in those
circumstances will <code>_expand</code> try to expand substitutions.
<p>You can also control how expansions are inserted. The tags for adding
expansions are <code>original</code> (presumably self-explanatory),
<code>all-expansions</code>, which refers to adding a single string containing all
the possible expansions (the default, just like the editor function
<code>expand-word</code>), and <code>expansions</code>, which refers to the results added one
by one. By changing the order in which the tags are tried, as described for
the <code>tag-order</code> style above, you can decide how this happens. For
example,
<pre>
bindkey '^i' complete-word
zstyle ':completion:*' completer _expand _complete
zstyle ':completion::expand:*' glob 1
zstyle ':completion::expand:*' tag-order expansions
</pre>
sets up for performing glob expansion via completion, with the expansions
being presented one by one (usually via menu completion, since there is no
common prefix). Altering <code>expansions</code> to <code>all-expansions</code> would insert
the list, as done by the normal expansion mechanism, while altering it to
`<code>expansions original</code>' would keep the one-at-a-time entry but also
present the original string as a possibility. You can even have all three,
i.e. the entire list as a single string becomes just one of the set of
possibilities.
<p>There is also a <code>sort</code> style, which determines whether the expansions
generated will be sorted in the way completions usually are, or left just
as the shell produced them from the expansion (for example, expansion of an
array parameter would produce the elements in order). If it is <code>true</code>,
they will always be sorted, if <code>false</code> or unset never, and if it is
<code>menu</code> they will be sorted for the <code>expansions</code> tag, but not for the
<code>all-expansions</code> tag which will be a single string of the values in the
original order.
<p>An easier way of getting this sort of control over expansion is with the
<code>_expand_word</code> function, usually bound to <code>\C-xe</code>, which does all the
things described above without getting mixed up with the other completers.
In this case the context string starts `<code>:completion:expand-word</code>', so
you can have different styles for this than for the <code>_expand</code> completer.
<p><p><strong><code>_prefix</code></strong><br><br>
<p>Strictly, this completer doesn't do completion itself, and should hence be
in the group below starting with <code>_match</code>. However, it <em>seems</em> to do
completion... Let me explain.
<p>Many shells including zsh have the facility to complete only the word before
the cursor, which zsh completion jargon refers to as the `prefix'. I
explained this above when I talked about <code>expand-or-complete-prefix</code>;
when you use that instead of the normal completion functions, the word as
it's finally completed looks like `<code><prefix><completion><suffix></code>' where
the completion has changed `<code><prefix></code>' to `<code><prefix><completion></code>',
ignoring <code><suffix></code> throughout.
<p>The <code>_prefix</code> completer lets you do this as part of normal completion.
What happens is that the completers are evaluated as normal, from left to
right, until a completion is found. If <code>_prefix</code> is reached, completion
is then attempted just on the prefix. So if your completers are
`<code>_completer _prefix</code>', the shell will first try completion on the whole
word, prefix and suffix, then just on the prefix. Only the first `real'
completer (<code>_complete</code>, <code>_approximate</code>, <code>_correct</code>, <code>_expand</code>) is
used.
<p>You can try prefix completion more than once simply by including
<code>_prefix</code> more than once in the list of completers; the second time, it
will try the second `real' completer in the list; so if they are
`<code>_complete _prefix _correct _prefix</code>', you will get first ordinary
completion, then the same for the prefix only, then ordinary correction,
then the same for the prefix only. You can move either of the <code>_prefix</code>
completers to the point in the sequence where you want the prefix-only
version to be tried.
<p>The <code>_prefix</code> completer has a special context, with the completer element
set to <code>prefix-N</code> for the <code>N</code>th call to <code>_prefix</code>; it will look up
the <code>completer</code> style in this context. The upshot is that you can use a
non-default set of completers for use just with <code>_prefix</code>. Here, as
described in the manual, is how to force <code>_prefix</code> only to be used as a
last resort, and only with normal completion:
<pre>
zstyle ':completion:::::' completer _complete <other-completers> _prefix
zstyle ':completion::prefix-1:::' completer _complete
</pre>
The full contexts are shown, just to emphasise the form; as always, you can
use wildcards if you don't care. In a case like this, you can use
<em>only</em> <code>_prefix</code> as the completer, and completion including the
suffix would never be tried; you then have to make sure you have the
<code>completer</code> style for the <code>prefix-1</code> context, however, or no completion
at all will be done.
<p>One gotcha with the <code>_prefix</code> completer: you have to make sure the option
<code>COMPLETE_IN_WORD</code> is set. That may sound counter-intuitive: after all,
<code>_prefix</code> forces completion <em>not</em> to complete inside a word. The
point is that without that option, completion is only ever tried at the end
of the word, so when you type <code><TAB></code> in the middle of
<code><prefix><suffix></code>, the cursor is moved to after the end of the suffix
before the completion system has a chance to see what's there, and hence
the whole thing is regarded as a prefix, with no suffix.
<p>There's one more style used with <code>_prefix</code>: `<code>add-space</code>'. This makes
<code>_prefix</code> add a real, live space when it completes the prefix, instead of
just pretending there was one there, hence separating the completed word
from the original suffix; otherwise it would simply leave the resulting
word all joined together, as <code>expand-or-complete-prefix</code> usually does.
<p><p><strong><code>_match</code></strong><br><br>
<p>This and the remaining completers are utilities, which affect the main
completers given above when put into the completion list rather than doing
completion themselves.
<p>The <code>_match</code> completer should appear <em>after</em> <code>_complete</code>; it is a
more flexible form of the <code>GLOB_COMPLETE</code> option. In other words, if
<code>_complete</code> didn't succeed, it will try to match the word on the line
as a pattern, not just a fixed string, against the possible completions.
To make it work like normal completion, it usually acts as if a `<code>*</code>' was
inserted at the cursor position, even if the word already contains
wildcards.
<p>You can control the addition of `<code>*</code>' with the `<code>match-original</code>'
style; the normal behaviour occurs if this is unset. If it is set to
`<code>only</code>', the `<code>*</code>' is not inserted, and if it is `<code>true</code>', or
actually any other string, it will try first without the `<code>*</code>', then
with. For example, consider typing `<code>setopt c*ect<TAB></code>' with the
<code>_match</code> completer in use. Normally this will produce two possibilities,
`<code>correct</code>' and `<code>correctall</code>'. After setting the style,
<pre>
zstyle ':completion::match:*' original only
</pre>
no `<code>*</code>' would be inserted at the place where you hit `<code>TAB</code>', so that
`<code>correct</code>' is the only possible match.
<p>The <code>_match</code> completer uses the style <code>insert-unambiguous</code> in just the
same way as does <code>_approximate</code>.
<p><p><strong><code>_list</code></strong><br><br>
<p>If you have this in the list of completers (at the beginning is as good as
anything), then the first time you try completion, you only get a list;
nothing changes, not even a common prefix is inserted. The second time,
completion continues as normal. This is like typing <code>^D</code>, then tab, but
using just the one key. This differs from the usual <code>AUTO_LIST</code>
behaviour in that is entirely irrespective of whether the completion is
ambiguous; you always get the list the first time, and it always does
completion in the usual way the second time.
<p>The <code>_list</code> completer also uses the <code>condition</code> style, which works a
bit like the styles for the <code>_expand</code> completer: it takes a numeric
expression, which has to evaluate to one for the <code>_list</code> delaying
behaviour to take effect. Again, this allows you to test for a particular
value of <code>$NUMERIC</code>. Unlike the condition styles for <code>_expand</code>, an
unset or null <code>condition</code> is assumed to be true.
<p>Finally, the boolean style <code>word</code> is also relevant. If false or unset,
<code>_list</code> examines the whole line when deciding if it has changed, and
hence completion should be delayed until the next keypress. If true, it
just examines the current word. Note that <code>_list</code> has no knowledge of
what happens between those completion calls; looking at the command line is
its only resource.
<p><p><strong><code>_menu</code></strong><br><br>
<p>This just implements menu completion in shell code; it should come before
the `real' completion generators in the <code>completers</code> style. It ignores
the <code>MENU_COMPLETION</code> option and other related options and the normal
menu-completion widgets don't work well with it. However, you can copy it
and write your own completers.
<p><p><strong><code>_oldlist</code></strong><br><br>
<p>This completer is most useful when you are in the habit of using special
completion functions, i.e. commands other than the standard completion
system. It is able to hang onto an old completion list which would otherwise
be replaced with a newly generated one. There are two aspects to this.
<p>First, listing. Suppose you try to complete something from the shell
history, using the command bound to `<code>ESC-/</code>'. For example, I typed
`<code>echo ma<ESC-/></code>' and got `<code>max-errors</code>'. At this point you might want
to list the possible completions. Unfortunately, if you type <code>^D</code>, it
will simply list all the usual contextual completions --- for the <code>echo</code>
command, which is not handled specially, these are simply files. So it
doesn't work. By putting the <code>_oldlist</code> completer into the
<code>completers</code> style <em>before</em> <code>_complete</code>, it does work, because the
old list of matches is kept for <code>^D</code> to use.
<p>In this case, you can force old-listing on or off by setting the
<code>old-list</code> style to <code>always</code> or <code>never</code>; usually it shows the listing
for the current set of completions if that isn't already displayed, and
otherwise generates the standard listing. You can even set the value of
<code>old-list</code> to a list of completers which will always have their list kept
in this way.
<p>The other place where <code>_oldlist</code> is useful is in menu completion, where
exactly the same problem occurs: if you generate a menu from a special
command, then try to cycle through by hitting tab, completion will look for
normal contextual matches instead. There's a way round this time --- use
the special command key repeatedly instead of tab. This is rather tedious
with multiple key sequences. Again, <code>_oldlist</code> cures this, and
again you can control the behaviour with a style, <code>old-menu</code>, which takes a
boolean value (it is on by default). As Orwell put it, oldlisters
unbellyfeel menucomp.
<p><p><strong>Ordering completers</strong><br><br>
<p>I've given various suggestions about the order in which completers should
come in, which might be confusing. Here, therefore, is a suggested order
(others are possible); just miss out any completers you don't want to use:
<pre>
_list _oldlist _menu _expand _complete _match _correct _approximate _prefix
</pre>
<p><a name="l44"></a>
<h3>6.5.2: Changing the format of listings: groups etc.</h3>
<p><p><strong><code>format</code></strong><br><br>
<p>You can use this style if you want to find out where the completions in a
completion listing come from. The most basic use is to set it for the
<code>descriptions</code> tag in any completion context. It takes a string value
in which `<code>%d</code>' should appear; this will be replaced by a description of
whatever is being completed. For example, I use:
<pre>
zstyle ':completion:*:descriptions' format 'Completing %d'
</pre>
and if I type <code>cd^D</code>, I see a listing like this (until I define the
<code>group-name</code> style, that is):
<pre>
Completing external command
Completing builtin command
Completing shell function
cd cddbsubmit cdp cdrecord
cdctrl cdecl cdparanoia cdswap
cdda2wav cdmatch cdparanoia-yaf
cddaslave cdmatch.newer cdplay
cddbslave cdot cdplayer_applet
</pre>
The descriptions at the top are related to the tag names --- usually
there's a unique correspondence --- but are in a more readable form; to get
the tag names, you need to use <code>^Xh</code>. You will no doubt see something
different, but the point is that the completions listed are a mixture of
external commands (e.g. <code>cdplay</code>), builtin commands (<code>cd</code>) and shell
functions (<code>cdmatch</code>, which happens to be a leftover from old-style
completion, showing you how often I clean out my function directory), and
it's often quite handy to know what you have.
<p>You can use some prompt escapes in the description, specifically those that
turn on or off standout mode (`<code>%S</code>', `<code>%s</code>'), bold text (`<code>%B</code>',
`<code>%b</code>'), and underlined text (`<code>%U</code>', `<code>%u</code>'), to make the
descriptions stand out from the completion lists.
<p>You can set this for some other tag than <code>descriptions</code> and the format
thus defined will be used only for completions of that tag.
<p><p><strong><code>group-name</code>, <code>group-order</code></strong><br><br>
<p>In the <code>format</code> example just above, you may have wondered if it is
possible to make the different types of completion appear separately,
together with the description. You can do this using <em>groups</em>. They are
also related to tags, although as you can define group names via
the <code>group-name</code> style it is possible to give different names for
completion in any context. However, to start off with it is easiest to
give the value of the style an empty string, which means that group names
are just the names of the tags. In other
words,
<pre>
zstyle ':completion:*' group-name ''
</pre>
assigns a different group name for each tag. Later, you can fine-tune this
with more specific patterns, if you decide you want various tags to have
the same group name. If no group name is defined, the group used is called
`<code>-default-</code>', so this is what was happening before you issued the
<code>zstyle</code> command above; all matches were in that group.
<p>The reason for groups is this: matches in the same group are shown
together, matches in different groups are shown separately. So the
completion list from the previous example, with both the <code>format</code> and
<code>group-name</code> styles are set, becomes:
<pre>
Completing external command
cdctrl cddbsubmit cdparanoia cdrecord
cdda2wav cdecl cdparanoia-yaf
cddaslave cdot cdplay
cddbslave cdp cdplayer_applet
Completing builtin command
cd
Completing shell function
cdmatch cdmatch.newer cdswap
</pre>
which you may find more helpful, or you may find messier, depending on deep
psychological factors outside my control.
<p>If (and only if) you are using <code>group-name</code>, you can also use
<code>group-order</code>. As its name suggests, it determines the order in which
the different completion groups are displayed. It's a little like
<code>tag-order</code>, which I described when tags were first introduced: the value
is just a set of names of groups, in the order you want to see them. The
example from the manual is relevant to the listing I just showed:
<pre>
zstyle ':completion:*:-command-' group-order builtins functions commands
</pre>
--- remember that the `<code>-command-</code>' context is used when the names of
commands, rather than their arguments, are being completed. Not
surprisingly, that listing now becomes:
<pre>
Completing builtin command
cd
Completing shell function
cdmatch cdmatch.newer cdswap
Completing external command
cdctrl cddbsubmit cdparanoia cdrecord
cdda2wav cdecl cdparanoia-yaf
cddaslave cdot cdplay
cddbslave cdp cdplayer_applet
</pre>
and if you investigate the tags available by using <code>^Xh</code>, you'll see that
there are others such as aliases whose order we haven't defined. These
appear after the ones for which you have defined the order and in some
order decided by the function which generated the matches.
<p><p><strong><code>tag-order</code></strong><br><br>
<p>As I already said, I've already described this, but it's here again for
completeness.
<p><p><strong><code>verbose</code>, <code>auto-description</code></strong><br><br>
<p>These are relatives of <code>format</code> as they add helpful messages to the
listing. If <code>verbose</code> is true, the function generating the matches may,
at its discretion, decide to show more information about them. The most
common case is when describing options; the standard function
<code>_describe</code> that handles descriptions for a whole lot of options tests
the <code>verbose</code> style and will print information about the options it is
completing.
<p>You can also set the string style <code>auto-description</code>; it too is useful
for options, in the case that they don't have a special description, but
they do have a single following argument, which completion already knows
about. Then the description of the argument for verbose printing will be
available as `<code>%d</code>' in <code>auto-describe</code>, so that something like the
manual recommendation `<code>specify: %d</code>' will document the option itself.
So if a command takes `<code>-o <output-file></code>' and the argument has the
description `<code>output file</code>', the `<code>-o</code>', when it appears as a possible
completion, will have the description `<code>specify: output file</code>' if it does
not have its own description. In fact, most options recognized by the
standard completion functions already have their own descriptions supplied,
and this is more subtlety than most people will probably need.
<p><p><strong><code>list-colors</code></strong><br><br>
<p>This is used to display lists of matches for files in different colours
depending on the file type. It is based on the syntax of the
<code>$LS_COLORS</code> environment variable, used by the GNU version of <code>ls</code>.
You will need a terminal which is capable of displaying colour such as a
colour xterm, and should make sure the <code>zsh/complist</code> library is loaded,
(it should be automatically if you are using menu selection set
up with the <code>menu</code> style), or if you use this style. But you can make sure
explicitly:
<pre>
zmodload -i zsh/complist
</pre>
The <code>-i</code> keeps it quiet if the modules was already loaded. The module
was called simply <code>complist</code> in 3.1.6, before hierarchical names for
libraries were introduced; the old name still works as an alias. To install
a standard set of default colours, you can use:
<pre>
zstyle ':completion:*' list-colors ''
</pre>
--- note the use of the `<code>default</code>' tag --- since a null string sets the
value to the default.
<p>If that's not good enough for you, here are some more detailed
instructions. The parameter <code>$ZLS_COLORS</code> is the lowest-level part of
the system used by <code>zsh/complist</code>. There is a simple builtin default,
while having the style set to the empty string is equivalent to:
<pre>
ZLS_COLORS="no=00:fi=00:di=01;34:ln=01;36:pi=40;33:so=01;35:do=01;35:\
bd=40;33;01:cd=40;33;01:or=40;31;01:ex=01;32:*.tar=01;31:*.tgz=01;31:\
*.arj=01;31:*.taz=01;31:*.lzh=01;31:*.zip=01;31:*.z=01;31:*.Z=01;31:\
*.gz=01;31:*.deb=01;31:*.jpg=01;35:*.gif=01;35:*.bmp=01;35:*.ppm=01;35:\
*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.mpg=01;37:*.avi=01;37:\
*.gl=01;37:*.dl=01;37:"
</pre>
It has essentially the same format as <code>$LS_COLORS</code>, and indeed I got the
values by using the <code>dircolors</code> command which comes with <code>ls</code>. You
should see the manual for the <code>zsh/complist</code> module for details, but note
in particular the addition of the type `<code>ma</code>', which specifies how the
current match in menu selection is displayed. The default for that is to
use standout mode --- the same effect as the sequence <code>%S</code> in a prompt,
which you can display with `<code>print -P %Sfoo</code>'.
<p>However, you need to define the style directly, since the completion always
uses that to to set <code>$ZLS_COLORS</code>; otherwise it doesn't know whether the
value it has found has come from the user or is a previous value taken from
some style. That takes this format:
<pre>
zstyle ':completion:*' list-colors "no=00" "fi=00" ...
</pre>
You can use an already defined <code>$LS_COLORS</code>:
<pre>
zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}
</pre>
(which splits the parameter to an array on colons) as <code>$LS_COLORS</code> is
still useful for <code>ls</code>, even though it's not worth setting <code>$ZLS_COLORS</code>
directly. This should mean GNU ls and zsh produce similar-looking lists.
<p>There are some special effects allowed. You can use patterns to tell how
filenames are matched: that's part of the default behaviour, in fact, for
example '*.tar=01;31' forces tar files to be coloured red. In that case,
you are limited to `<code>*</code>' followed by a string. However, there's a way of
specifying colouring for any match, not just files, and for any pattern:
use <code>=<pat>=<col></code>. Here are two ways of getting jobs coloured red in
process listings for the `<code>kill</code>' command.
<pre>
zstyle ':completion:*:*:kill:*' list-colors '=%*=01;31'
</pre>
This uses the method just described; jobs begin with `<code>%</code>'.
<pre>
zstyle ':completion:*:*:kill:*:jobs' list-colors 'no=01;31'
</pre>
This uses the tag, rather than the pattern, to match the jobs lines. It
has various advantages. Because you are using the tag, it's much easier to
alter this for all commands using jobs, not just kill --- just miss out
`<code>kill</code>' from the string. That wasn't practical with the other method
because it would have matched too many other things you didn't want.
You're not dependent on using a particular pattern, either. And finally,
if you try it with a `<code>format</code>' description you'll see that that gets the
colour, too, since it matched the correct tag. Note the use of the
`<code>no</code>' to specify that this is to apply for a normal match; the other
two-letter codes for file types aren't useful here.
<p>However, there is one even more special effect you can use with the general
pattern form. By turning on `backreferences' with `<code>(#b)</code>' inside the
pattern, parentheses are active and the bits they match can be coloured
separately. You do this by extending the list of colours, each code
preceded by an `<code>=</code>' sign, and the extra elements will be used to colour
what the parenthesis matched. Here's another example for `<code>kill</code>', which
turns the process number red, but leaves the rest alone.
<pre>
zstyle ':completion:*:*:kill:*:processes' list-colors \
'=(#b) #([0-9]#)*=0=01;31'
</pre>
The hieroglyphics are extended globbing patterns. You should note that the
<code>EXTENDED_GLOB</code> option is always on inside styles --- it's required for
the `<code>#b</code>' to take effect. In particular, `<code>#</code>' means `zero or more
repetitions of the previous bit of the pattern' with extended glob
patterns; see the globbing manual page for full details.
<p><p><strong><code>ignored-patterns</code></strong><br><br>
<p>Many shells, including zsh, have a parameter <code>$fignore</code>, which gives a
list of suffixes; filenames ending in any of these are not to be used in
completion. A typical value is:
<pre>
fignore=(.o \~ .dvi)
</pre>
so that normal file completion will not produce object files, EMACS backup
files, or TeX DVI files.
<p>The <code>ignored-patterns</code> style is an extension of this. It takes an array
value, like <code>fignore</code>, but with various differences. Firstly, these
values are patterns which should match the <em>whole</em> value to be completed,
including prefixes (such as the directory part of a filename) as well as
suffixes. Secondly, they apply to <em>all</em> completions, not just files,
since you can use the style mechanism to tune it to apply wherever you
want, down to particular tags.
<p>Hence you can replace the use of <code>$fignore</code> above with the following:
<pre>
zstyle ':completion:*:files' ignored-patterns '*?.o' '*?~' '*?.dvi'
</pre>
for completion contexts where the tag `<code>files</code>' is in use. The extra
`<code>?</code>'s are because <code>$fignore</code> was careful only to apply to real
suffixes, i.e. strings which had something in front of them, and the
`<code>?</code>' forces there to be at least one character present.
<p>Actually, this isn't quite the same as <code>$fignore</code>, since there are other
file tags than <code>files</code>; apart from those for directories, which you've
already met, there are <code>globbed-files</code> and <code>all-files</code>. The former is
for cases where a pattern is specified by the completion function, for
example `<code>*.dvi</code>' for files following the command name <code>dvips</code>. These
don't use this style, because the pattern was already sufficiently
specified. This follows the behaviour for <code>$fignore</code> in the old
completion system.
<p>The other tag, <code>all-files</code>, applies when a <code>globbed-files</code> tag failed,
and says any old file is good enough in that case; you can arrange how this
happens with the <code>tag-order</code> style. In this example,
<pre>
zstyle ':completion:*:*:dvips:argument*' tag-order globbed-files all-files
</pre>
is enough to say that you want to see all files if no files were produced
from the pattern, i.e. if there were no `<code>*.dvi</code>' files in the directory.
Finally the point of this ramble: as the <code>all-files</code> tag is separate from
the <code>files</code> tag, in this case you really would see all files (except for
those beginning with a `<code>.</code>', as usual). You might find this useful, but
you can easily make the <code>all-files</code> tag behave the same way as <code>files</code>:
<pre>
zstyle ':completion:*:(all-|)files' ignored-patterns ...
</pre>
<p>Another piece of behaviour is inherited from <code>$fignore</code>: if the only
patterns which match a completion would be ignored, they aren't. So for
example, you can say
<pre>
zstyle ':completion:*:functions' ignored-patterns '_*'
</pre>
and any time functions are completed, such as in arguments to the
`<code>functions</code>' builtin, those beginning with <code>_</code> are not shown.
However, if you type the `<code>_</code>', so that nothing else matches, all are
shown.
<p><p><strong><code>prefix-hidden</code>, <code>prefix-needed</code></strong><br><br>
<p>You will know that when the shell lists matches for files, the directory
part is removed. The boolean style <code>prefix-hidden</code> style extends this
idea to various other types of matches. The prefixes referred to are not
just any old common prefix to matches, but only some places defined in the
completion system: the <code>-</code> prefix to options, the `<code>%</code>'
prefix to jobs, the <code>-</code> or <code>+</code> prefix to directory stack entries are
the most commonly used.
<p>The <code>prefix-needed</code> applies not to listings, but instead to what the user
types on the command line. It says that matches will only be generated if
the user has typed the prefix common to them. It applies on broadly the
same occasions as <code>prefix-hidden</code>.
<p><p><strong><code>list-packed</code>, <code>list-rows-first</code>,
<code>accept-exact</code>, <code>last-prompt</code>, <code>menu</code></strong><br><br>
<p>The first two of these have already been introduced, and correspond to the
<code>LIST_PACKED</code> and <code>LIST_ROWS_FIRST</code> options. The <code>accept-exact</code> and
<code>last-prompt</code> styles correspond essentially to the <code>REC_EXACT</code> and
<code>ALWAYS_LAST_PROMPT</code> options in the same way.
<p>The style <code>menu</code> roughly corresponds to the <code>MENU_COMPLETE</code> option, but
there is also the business of deciding whether to use menu selection, as
described above. These two uses don't interfere with each other --- except
that, as I explained, menu completion must be started to use menu selection
--- so a value like `<code>true select=6</code>' is valid; it turns on menu
completion for the context, and also activates menu selection if there are
at least 6 choices.
<p><p><strong><code>hidden</code></strong><br><br>
<p>This is a little obscure for most users. Its context should be restricted
to specific tags; any corresponding matches will not be shown in completion
listings, but will be available for inserting into the command line. If
its value is `<code>true</code>', then the description for the tag may still appear;
if the value is `<code>all</code>', even that is suppressed. If you don't want the
completions even to be available for insertion, use the <code>tag-order</code>
style.
<p><a name="l45"></a>
<h3>6.5.3: Styles affecting particular completions</h3>
<p>The styles listed here are for use only with certain completions as noted.
I have not included the styles used by particular completers, which are
described with the completer in question in the subsection `<strong>Specifying
completers and their options</strong>'. I have also not described styles used only
in separate widgets that do completion; the relevant information is all
together in the next section.
<p><p><strong>Filenames (1): <code>file-patterns</code></strong><br><br>
<p>
<p>The <code>file-patterns</code> style allows you to specify a pattern to override
whatever would be completed, even in what would otherwise be a simple file
completion with no pattern. Since this can easily get out of hand, the
best way of using this style is to make sure that you specify it for a
narrowly enough defined context. In particular, you probably want to
restrict it to completions for a single command and for a particular one of
the tags usually applying to files. As always, you can use <code>^Xh</code> to find
out what the context is.
<p>It was explained above for the <code>tag-order</code> style that when a function
uses pattern matching to generate file completions, such as all <code>*.ps</code>
files or all <code>*.gz</code> files, the three tags <code>globbed-files</code>,
<code>all-files</code> and <code>directories</code> are tried. When you set something with
<code>file-patterns</code>, all three tags are automatically activated. So, for
example, after
<pre>
zstyle ':completion:*:*:foo:*:*' file-patterns '*.yo'
</pre>
the command named `<code>foo</code>' will complete files ending in `<code>.yo</code>', as
well as directories. For once, you don't have to change the completer to
do this: `<code>foo</code>' isn't specially handled, so does default completion,
and that means completing files, so that <code>file-patterns</code> is active
anyway.
<p>You can now set up your <code>tag-order</code> style to include
<code>globbed-patterns</code>, which represents the `<code>.yo</code>' files, and
<code>directories</code> and <code>all-files</code>; suppose you want to make the `<code>.yo</code>'
files and the directories appear at the same time:
<pre>
zstyle ':completion:*:*:foo:*:*' tag-order 'directories globbed-files'
</pre>
You should remember this if you are using <code>file-patterns</code>, because if
you look at the tags available in a simple file completion context with
<code>^Xh</code> you will just see <code>files</code> and <code>all-files</code>, and not the more
specific ones.
<p>Hence you can turn completion for a command that usually doesn't use a
pattern into one that does. Another example (taken from the manual):
<pre>
zstyle ':completion:*:*:rm:*:globbed-files' file-patterns '*.o'
</pre>
specifies a completion for arguments to <code>rm</code> with the tag
<code>globbed-files</code>. So if there are any <code>*.o</code> files around, completion
for <code>rm</code> will just complete those, even if arguments to <code>rm</code> are
otherwise found by default file completion (which they usually are). Then
you can decide if you want to specify a pattern for the <code>all-files</code>
context for this command too --- for example, there may be certain files
you never want <code>rm</code> to complete.
<p>Remember that using explicit patterns overrides the effect of <code>$fignore</code>;
this is obviously useful with <code>rm</code>, since the files you want to delete
are often those you usually don't want to complete.
<p><p><strong>Filenames (2): <code>cursor</code>, <code>expand</code>, <code>sort</code>, <code>special-dirs</code>,
<code>ignore-parents</code>, <code>squeeze-slashes</code></strong><br><br>
<p>Filename completion is powerful enough to complete all parts of a path at
once, for example `<code>/h/p/z</code>' will complete to `<code>/home/pws/zsh</code>'. This
can cause problems when the match is ambiguous; since several components of
the path may well be ambiguous, how much should the completion system
complete, and where should it leave the cursor? This facility is
associated with all these styles affecting filenames.
<p>With ordinary completion, the usual answer is that the completion is halted
as soon as a path component matches more than one possibility, and the
cursor is moved to that point, with the remainder of the string left
unaltered. With menu completion, you can simply cycle through the
possibilities with the cursor moved to the end as usual. If you set the
style <code>cursor</code>, then the system will leave the cursor at the point of the
first ambiguity even if menu completion is in use. Note that this is
always used with the `<code>paths</code>' tag, i.e. the context ends in
`<code>...:paths</code>'.
<p>The style <code>expand</code> is similar and is also applied with the `<code>paths</code>'
tag. It can include either or both of the strings <code>prefix</code> and
<code>suffix</code>. With the former, it tells the completion system always to
expand unambiguous prefixes in a path (such as `<code>/u/i</code>' to `<code>/usr/in</code>',
which matches both <code>/usr/include</code> and <code>/usr/info</code>) --- even if the
remainder of the string on the command line doesn't match any file. So
this expansion will now happen even if you try this on
`<code>/u/i/ALoadOfOldCodswallop</code>', which it otherwise wouldn't.
<p>Including <code>suffix</code> in the value of <code>expand</code> extends path completion in
another way: it allows extra unambiguous parts to be added even after the
first ambiguous one. So if `<code>/home/p/.pr</code>' would match
`<code>/home/pws/.procmailrc</code>' or `<code>/home/patricia/.procmailrc</code>', and
nothing else, the last word would be expanded. Set up like this, you will
always get the longest unambiguous match for all parts of the path.
<p>Using <code>expand</code> with <code>suffix</code> also affects menu completion. Normally
menu completion only cycles through the values for the first ambiguous
completion; you have to select a possibility and start completion again to
complete further down the path. With <code>suffix</code>, if you first apply this
using normal completion, then start menu completion (for example using the
<code>AUTO_MENU</code> option), the extra possibilities found as described in the
previous paragraph will be in the menu.
<p>The <code>sort</code> style allows files to be sorted in a way other than by
alphabetical order: sorting applies both to the list of files, and to the
order in which menu completion presents them. The value should include one
of the following: `<code>size</code>', `<code>links</code>', `<code>modification</code>' (same as
`<code>time</code>', `<code>date</code>'), `<code>access</code>', `<code>inode</code>' (same as `<code>change</code>').
These pick the obvious properties for sorting: file size, number of hard
links, modification time, access time, inode change time. You can also add
the string `<code>reverse</code>' to the value, which reverses the order. In this
case the tag is always `<code>files</code>'.
<p>The <code>special-dirs</code> style controls completion of the special directories
`<code>.</code>' and `<code>..</code>'. Given that you usually need to type an initial dot
to complete anything at all beginning with one, the idea of `completing'
`<code>.</code>' is a little odd; it simply means that the directory is accepted
when the completion is started on it. You can set the style to <code>true</code> to
allow completion to both of the two, or to `<code>..</code>' to complete `<code>..</code>'
but not `<code>.</code>'. Like <code>cursor</code>, this is used with the tag set to
`<code>paths</code>'.
<p>The style <code>ignore-parents</code> is used with the <code>files</code> tag, since it
applies to paths, but not necessarily completion of multiple path names at
once; it can be used when completing just the last element. There are two
main uses, which can be combined. The first case is to include the string
`<code>parent</code>' in the style. This means that when you complete after (say)
<code>foo/../</code>, the string <code>foo</code> won't appear as a choice, since it already
appeared in the string. Secondly, you can include `<code>pwd</code>' in the value;
this means don't complete the current working directory after `<code>../</code>' ---
you can see the sense in that: if you wanted to complete there, you
wouldn't have typed the `<code>..</code>' to get out if it.
<p>Actually, the function performs both those tests on the directories in
question even if the string `<code>..</code>' itself hasn't been typed. That might
be more confusing, and you make sure that the tests for <code>parent</code> and
<code>pwd</code> are only made when you typed the `<code>..</code>' by including a `<code>..</code>'
in the style's value. Finally, you can include the string `<code>directory</code>'
in the values: that means the tests will only be performed when
directories are being completed, while if some other sort of file, or any
file, can be completed, the special behaviour doesn't occur. You may have
to read that through a couple of times before deciding if you need it or
not.
<p>Lastly, there is the style <code>squeeze-slashes</code>. This is rather simpler.
You probably already know that in a UNIX filename multiple slashes are
treated just like a single slash (with a few minor exceptions on some
systems). However, path completion usually assumes that multiple slashes
mean multiple directories to be completed: `<code>//termc</code>' completes to
`<code>/etc/termcap</code>' because of this rule. If you want to stick with the
ordinary UNIX rule you can set <code>squeeze-slashes</code> to <code>true</code>. Then in
this example only files in the root directory will be completed.
<p><p><strong>Processes: <code>arguments</code>, <code>list-arguments</code></strong><br><br>
<p>Some functions, such as <code>kill</code>, take processes IDs (i.e. numbers) as
arguments. These can be completed by using the <code>ps</code> command to generate
the process numbers. The <code>arguments</code> style allows you to specify which
arguments are to be passed to <code>ps</code> to generate the numbers. For example,
if you are root and want to have all processes as possible completions, you
might use `<code>-e</code>', for many modern systems, or `<code>ax</code>', for older
BSD-like systems. The completion system assumes that the numbers it wants
will be in the first column of the resulting output. The default is not to
use any arguments; most variants of <code>ps</code> will then just show you
interactive processes from your current session. To show all your own
processes on a modern system, you can probably use `<code>-u$USER</code>'.
<p>The style <code>list-arguments</code> is similar, but applies only to the listing
shown, not the list of possible completions. Since the list is generated
separately, you will usually want to include the same restrictions as for
the <code>arguments</code> style, if any. However, you can now make the output as
fancy as you like since it doesn't need to be deciphered automatically.
<p><p><strong>Job control: <code>numbers</code></strong><br><br>
<p>Builtin functions that take process IDs usually also take job
specifications, strings beginning with `<code>%</code>' and followed either by
a small number or a string. The style <code>numbers</code> determines how these are
completed. By default, the completion system will try to complete an
unambiguous string from the name of the job. If you set <code>numbers</code> to
true, it will instead complete the job number --- though the listing will
still show the full information --- and if you set it to a number, it will
only use that many words of the job name, and switch to using numbers if
those are not unique. In other words, if you set it to `<code>1</code>' and you
have two jobs `<code>vi foo</code>' and `<code>vi bar</code>', then they will complete as
`<code>%1</code>' and `<code>%2</code>' (or maybe other numbers) since the first words are
the same.
<p>Note also that <code>prefix-needed</code> applies here; if it is set, you need to
type the `<code>%</code>' to complete jobs rather than processes.
<p><p><strong>System information: users, groups, hosts etc.</strong><br><br>
<p>There are many occasions where you complete the names of users on the
system, groups on the system (not to be confused with completion groups),
names of other hosts you connect to via the network, and ports, which are
essentially the names of internet services available on another host such
as <code>nntp</code> or <code>smtp</code>.
<p>By default, the completion system will query the usual system files to find
the names of users, groups, hosts and ports, though in the final case it
will only look in the file `<code>/etc/hosts</code>', which often includes only a
very small number of not necessarily very useful hosts. It is possible to
tell the completion system always to use a specified set by setting the
appropriate style --- <code>users</code>, <code>groups</code>, <code>hosts</code>, <code>ports</code> --- to
the set of possibilities you want. This is nearly always useful with
<code>hosts</code>, and on some systems you may find it takes an inordinate amount
of time for the system to query the database for groups and users, so you
may want to specify a subset of those you use most often.
<p>There are also three sets of combinations: <code>hosts-ports</code>,
<code>hosts-ports-users</code> and <code>users-hosts</code>. These are used for commands
which can take both or all three arguments. Currently, the command socket
uses <code>hosts-ports</code>, telnet uses <code>hosts-ports-users</code>, while the style
<code>users-hosts</code> is used by remote login commands such as <code>rsh</code> and
<code>ssh</code>, and anywhere the form `<code>user@host</code>' is valid.
<p>The last is probably the most useful, so I'll illustrate that. By setting:
<pre>
zstyle ':completion:*' users-hosts pws:foo.bar.uk peters:frond.grub.uk
</pre>
you tell <code>rsh</code> and friends the possible user/host combinations. If you
type `<code>rsh -l </code>', a username is expected and either <code>pws</code> or <code>peters</code>
will be completed. Suppose you picked <code>pws</code>; then for the next argument,
which should be a host, the system now knows that it must be
<code>foo.bar.uk</code>, since the username for the other host doesn't match.
<p>If you don't need that much control, completion for all these commands will
survive on just the basic `<code>hosts</code>', `<code>users</code>', etc. styles; it simply
won't be as clever in recognising particular combinations. In fact, even
if you set the combined styles, anything that doesn't match will be looked
up in the corresponding basic style, so you can't lose, in principle.
<p>The other combined styles work in exactly the same way; just set the values
separated by colons --- in particular, it's easy (for some of us) to forget
and use things like `<code>pws@foo.bar.uk</code>' in <code>users-hosts</code>, but that won't
work.
<p><p><strong>URLs for web browsers</strong><br><br>
<p>Completion for URLs is done by setting a parallel path somewhere on your
local machine. The <code>path</code> style specifies the top directory for this.
For example, to complete the URL <code>http://sunsite.auc.dk/zsh/</code>, you
need to make a set of subdirectories of the <code>path</code> directory
<code>http/sunsite.ac.dk/zsh</code>. You can extend this for however many levels of
directory you need; as you would expect, if the last object is a file
rather than a directory you should create it with `<code>touch</code>' rather than
`<code>mdkir</code>'. The style will always use the tag `<code>urls</code>' for this
purpose, i.e. the context always matches `<code>:completion:*:urls</code>'. This is
a neat way of using the ordinary filing system for doing the dirty work of
turning URLs into components. Arguably the system should be able to scan
your browser's bookmarks file, but currently it won't.
<p>Note that many modern browsers allow you to miss out an initial
`<code>http://</code>', and that lots of pseudo-URLs appear in newspapers and
advertisements without it. The completion system needs it, however.
<p>There is a better way when the web pages actually happen to be hosted on a
system whose directories you can access directly. Set the <code>local</code> style to
an array of three strings: a hostname to be considered local (you can only
give one per context), the directory corresponding to the root of the files,
and the directory where a user places their own web pages, relative to
their home directory. For example, if your home page is usually retrieved
as <code>http://www.footling.com/</code>, and that looks for the index file (often
called <code>index.html</code>) in the directory <code>/usr/local/WWW/files</code>, and your
own web pages live under `<code>~/www</code>', then you would set
<pre>
zstyle ':completion:*:urls' local www.footling.com /usr/local/www/files www
</pre>
and when you type `<code>lynx http://www.footling.com/</code>', all the rest will
be completed automatically.
<p><p><strong>The X files</strong><br><br>
<p>There is another use for the <code>path</code> style with the tag `<code>colors</code>': it
gives the path to a file which contains a list of colour names understood
by the X-windows system, usually in file named `<code>rgb.txt</code>'. This is used
in such contexts as `<code>xsetroot -solid </code>', which completes the name of a
colour to set your root window (wallpaper) to. It may be that the default
value works on your system without your needing to set this.
<p><a name="l46"></a>
<h2>6.6: Command widgets</h2>
<p><a name="l47"></a>
<h3>6.6.1: <code>_complete_help</code></h3>
<p>You've already met this, usually bound to `<code>^Xh</code>' unless you already had
that bound when completion started up (in which case you should pick your
own binding and use `<code>bindkey</code>'), but don't forget it, since it's by far
the easiest way of finding out what context to use for setting particular
styles.
<p><a name="l48"></a>
<h3>6.6.2: <code>_correct_word</code>, <code>_correct_filename</code>, <code>_expand_word</code></h3>
<p>The first and last of these have been mentioned in describing the related
completers: <code>_correct_word</code>, usually bound to <code>^Xc</code>, calls the
<code>_correct</code> completer directly to perform spelling correction on the
current word, and <code>_expand_word</code>, usually bound to <code>^Xe</code>, does the same
with the <code>_expand</code> completer. The contexts being
`<code>:completion:complete-word</code>' and `<code>:completion:expand-word</code>'
respectively, so that they can be distinguished in styles from the ordinary
use of the completer. If you want the same styles to be used in both
contexts, but not others, you should define them for patterns beginning
`<code>:completion:complete(|-word)...</code>'.
<p>The middle one simply corrects filenames, regardless of the completion
context. Unlike the others, it can also be called as an ordinary function:
pass it an argument, and it will print out the possible corrections.
It does this because it bypasses most of the usual completion system.
Probably you won't often need it, but it is usually bound to `<code>^XC</code>'
(note the capital `<code>C</code>').
<p><a name="l49"></a>
<h3>6.6.3: <code>_history_complete_word</code></h3>
<p>This is usually bound to `<code><ESC-/></code>' for completing back in the history,
and `<code><ESC-,></code>' for completing forward --- this is only useful if you use
menu completion to cycle through matches. It will complete words from the
history list, starting with the most recent. Hence
<pre>
touch supercalifragilisticexpialidocious
cat sup<ESC-/>
</pre>
will save you quite a bit of typing --- although in this particular case,
you can use `<code><ESC-.></code>' to insert the last word of the previous command.
<p>Various styles are available. You can switch on menu completion in the
usual ways, but you can also set the `<code>stop</code>' style which both ensures
menu completion is active and stops it cycling past the end of the history
list --- in other words, it behaves more like the commands for going up and
down history than the usual menu completion behaviour of repeatedly cycling
through the same list.
<p>You can also set the `<code>list</code>' style to force matches to be listed, the
`<code>sort</code>' style to sort matches in alphabetical order instead of by their
age in the history list, and the `<code>remove-all-dups</code>' style, which ensures
that each match only occurs once in the completion list --- normally
consecutive identical matches are removed, but the code does not bother
searching for identical matches elsewhere in the list of possibilities.
<p><a name="l50"></a>
<h3>6.6.4: <code>_most_recent_file</code></h3>
<p>This function is normally bound to `<code>^Xm</code>'. It simply completes the most
recently modified file that matches what's on the line already. Any
pattern characters in the existing string are active, so this is a cross
between expansion and completion. You can also give it a numeric prefix to
show the <code>N</code>th most recently modified file that matches the pattern.
<p><a name="l51"></a>
<h3>6.6.5: <code>_bash_completions</code></h3>
<p>This function provides compatibility with a set of completion bindings in
bash, in which escape followed by one of the following characters causes a
certain type of (non-contextual) completion: `<code>!</code>', command names;
`<code>$</code>', environment variables; `<code>@</code>', host names; `<code>/</code>', filenames,
and `<code>~</code>' user names. `<code>^X</code>' followed by the same characters causes
the possible completion to be listed. This function decides by examining
its own binding which of those it should be doing, then calls the
appropriate completion function. If you want to use it for all those
possible bindings, you need to issue the right statements in your
<code>.zshrc</code>, since only the bindings with `<code>~</code>' are set up by default to
avoid clashes. This will do it:
<pre>
for key in '!' '$' '@' '/'; do
bindkey "\e$key" _bash_complete-word
bindkey "^X$key" _bash_list-choices
done
</pre>
Unlike most widgets, which are tied to functions of the same name to
minimize confusion, the function <code>_bash_completions</code> is actually called
under the names of the two different widgets shown in that code so as to be
able to implement both completion and listing behaviour.
<p><a name="l52"></a>
<h3>6.6.6: <code>_read_comp</code></h3>
<p>This function, usually bound to `<code>^X^R</code>', does on-the-fly completion.
When you call it, it prompts for you to enter a type of completion; usually
this will be the name of a completion function with the required arguments.
Thus it's not much use unless you already have some fairly in-depth
knowledge of how the system is set up. For example, try it, then enter
`<code>_files -/</code>', which generates directories. There is a rudimentary
completion for the function names built into it.
<p>The next time you start it up, it will produce the same type of
completion. You need to give it a numeric prefix to tell it to prompt for
a different sort.
<p><a name="l53"></a>
<h3>6.6.7: <code>predict-on</code>, <code>incremental-complete-word</code></h3>
<p>These are not really complete comamds at all in the strict sense, they are
normal editing commands which happen to have the effect of completion.
This means that they are not part of the completion system, and though they
are installed with other shell functions they will not automatically be
loaded. You will therefore need an explicit `<code>autoload -U predict-on</code>',
etc. --- remember that the `<code>-U</code>' prevents the functions from expanding
any of your own aliases when they are read in --- as well as an explicit
`<code>bindkey</code>' command to bind each function, and a `<code>zle -N</code>' statement
to tell the line editor that the function is to be regarded as an editing
widget. The <code>predict-on</code> file, when loaded, actually defines two
functions, <code>predict-on</code> and <code>predict-off</code>, both of which need to be
defined and bound for them to work. So to use all of these,
<pre>
autoload -U incremental-complete-word predict-on
zle -N incremental-complete-word
zle -N predict-on
zle -N predict-off
bindkey '^Xi' incremental-complete-word
bindkey '^Xp' predict-on
bindkey '^X^P' predict-off
</pre>
<p>`Prediction' is a sort of dynamic history completion. With <code>predict-on</code>
in effect, the line editor will try to retrieve a line back in the history
which matches what you type. If it does, it will show the line, extending
past the current cursor position. You can then edit the line; characters
which do not insert anything mostly behave as normal. If you continue to
type, and what you type does not match the line which was found, the line
editor will look further back for another line; if no line matches, editing
is essentially as normal. Often this is flexible enough that you can leave
<code>predict-on</code> in effect, but you can return to basic editing with
<code>predict-off</code>.
<p>Note that, with prediction turned on, deleting characters reverses the
direction of the history search, so that you go back to previous lines,
like an ordinary incremental search; unfortunately the previous line found
could be one you've already half-edited, because they don't disappear from
the list until you finally hit `return' on an edited line to accept it.
There's another problem with moving around the line and inserting
characters somewhere else: history searching will resume as soon as you
try to insert the new characters, which means everything on the right of
the cursor is liable to disappear again. So in that case you need to turn
prediction off explicitly. A final problem: prediction is bad with
multi-line buffers.
<p>If prediction fails with <code>predict-on</code> active, completion is automatically
tried. The context for this looks like `<code>:completion:::predict::</code>'.
Various styles are useful at this point: `<code>list</code>' could be set to always,
which will show a possible completion even if there is only one, for
example. The style `<code>cursor</code>' may have the values `<code>complete</code>' to move
to the end of the word copmleted, `<code>key</code>' to move past the rightmost
occurrence of the character just typed, allowing you just to keep typing,
or anything else not to move the cursor which is the default behaviour.
<p>The <code>incremental-complete-word</code> function allows you to see a list of
possible completions as you type them character by character after the
first. The function is quite basic; it is really just an example of using
various line editor facilities, and needs some work to make a useful
system. It will understand <code>DEL</code> to delete the previous character,
return to accept, <code>^G</code> to abort, <code>TAB</code> to complete the word as normal
and <code>^D</code> to list possibilities; otherwise, keys which do not insert are
unlikely to have a useful effect. The completion is done behind the scenes
by the standard function <code>complete-word</code>.
<p><a name="l54"></a>
<h2>6.7: Matching control and controlling where things are inserted</h2>
<p>The final matter before I delve into the system for writing new completion
functions is matching control; the name refers in this case to how the
matching between characters already typed on the command line and
characters in a trial completion is performed. This can be done in two
ways: by setting the <code>matcher-list</code> style, which applies to all
completions, or by using an argument (<code>-M</code>) to the low-level completion
functions. Mostly we will be concerned with the first. All this is best
illustrated by examples, which are taken from the section `<strong>Matching
Control</strong>' in the <code>zshcompwid.1</code> manual page; in the printed manual and
the `info' pages this occurs within the section `<code>Completion Widgets</code>'.
<p>The <code>matcher-list</code> style takes an array value. The values will be tried
in order from left to right. For example,
<pre>
zstyle ':completion:*' matcher-list 'm:{a-z-}={A-Z_}' 'r:|[-_./]=* r:|=*'
</pre>
tries the first specification, which is for case-insensitive completion,
and if no matchers are generated tries the second,
which does partial word completion; I'll explain both these specifications
in detail as we go along. You can make it do both forms the second time
round simply by combining the values with a space, i.e. the last
word on the command line becomes <code>'m:{a-z-}={A-Z_} r:|[-_./]=* r:|=*'</code>.
It is also perfectly valid to have a first matcher empty, i.e. <code>''</code>; this
means that completion is tried with no matching rule the first time, and
will only go on to subsequent matchers in the list if that fails. This is
quite a good practice as it avoids surprises.
<p>There is an extra feature in the context used for the <code>matcher-list</code>, and
only for that style: the completer part of the context is set to the
completer to be called, plus a hyphen, plus the number of the call to
that completer, so that the matchers for the first use of ordinary
completion are retrieved with context `<code>:completion::complete-1:::</code>', the
ones for the second use with `<code>:completion::complete-2:::</code>', and so on
--- <em>within</em> the completer the context is back to normal. You
probably won't need that unless you can think of a pretty specialised
use for matching.
<p><a name="l55"></a>
<h3>6.7.1: Case-insensitive matching</h3>
<p>To perform case-insensitive matching for all completions, you can set:
<pre>
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}'
</pre>
The `<code>m:</code>' specifies standard matching, with the `<code>{a-z}</code>' describing
what's on the command line, and the `<code>{A-Z}</code>' what's in the trial
completion. The braces indicate `correspondence classes', which are not
lessons taken by email (that's a joke), but a relative of the more usual
character classes like `<code>[a-z]</code>', which, as you no doubt know, would
match any of the letters between <code>a</code> and <code>z</code>. In this context, with
the braces, the letters are forced to match on the left and right hand side
of the `<code>=</code>', so an `<code>a</code>' on the command line must match an `<code>A</code>' in
the trial completion, a `<code>b</code>' must match a `<code>B</code>', and so on. Since an
<code>a</code> in the command line will always match an `<code>a</code>' in the trial
completion, matcher or no matcher, this means that if you type an `<code>a</code>'
it will match either `<code>a</code>' or `<code>A</code>' --- in other words,
case-insensitively. The same goes for any other lowercase letter you
type. The difference from `<code>m:[a-z]=[A-Z]</code>' is that, because ordinary
character classes are unordered, <em>any</em> lowercase letter would have
matched <em>any</em> uppercase letter, which isn't what you want. The rest of
the shell doesn't know about correspondence classes at all.
<p>Finally, the use of a lowercase `<code>m</code>' at the start means that the
characters actually inserted onto the line are those from the trial
completion --- if you type `<code>make<TAB></code>', the completion process
generates file names, and <code>matcher-list</code> allows what you type to match
the file `<code>Makefile</code>', then you need the latter to be inserted on the
command line. Use of `<code>M:</code>' at the start of the matcher would keep
whatever was on the line to begin with there.
<p>If you want completely case-insensitive matching, so that typing
`<code>MAKE<TAB></code>' would also potentially complete to `<code>Makefile</code>' or
`<code>makefile</code>' (and so on), the extension is fairly obvious:
<pre>
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
</pre>
because now as well as `<code>a</code>' matching `<code>A</code>', `<code>A</code>' will match `<code>a</code>'
--- and, of course, `<code>a</code>' and `<code>A</code>' each still match themselves.
<p>More detail on the patterns: they do not, in fact, allow all the possible
patterns you can use elsewhere in the shell, since that would be too
complicated to implement with little extra use. Apart from character
classes and correspondence classes, you can use `<code>?</code>' which has its usual
meaning of matching one character, or literal characters, which match
themselves; or the pattern for the trial completion only can be a single
`<code>*</code>'. which matches anything. That's it, however; you can't do other
things with the `<code>*</code>' since it's too difficult for the system to guess
what characters should be covered by it.
<p>For the same reason, the `<code>*</code>' must be in an <em>anchored</em> pattern, the
idea behind which is shown in the next example.
<p><a name="l56"></a>
<h3>6.7.2: Matching option names</h3>
<p>I explained back in chapter one that zsh didn't care too much how you
specified options: `<code>noglob</code>' and `<code>NOGLOB</code>' and `<code>No_Glob</code>' and
`<code>__NO_GLOB_</code>' are all treated the same way. Also, this is the negation
of the option `<code>glob</code>'. Having learnt how to match case-insensitively,
we have two further challenges: how to ignore a `<code>_</code>' anywhere in the
word, and how to ignore the <code>NO</code> at the beginning so that we can complete
an unnegated option name after it.
<p>Well, here's how. Since you don't want this for all completions, just for
option names, I shall show it as an argument for the `<code>compadd</code>' command,
which gives the system the list of possible completions. The option names
should then appear as the remaining arguments to the command, and the
easiest way of doing that is to have the <code>zsh/parameter</code> module loaded,
which it always is for new completion, and use the keys of the special
associative array <code>$options</code>:
<pre>
compadd -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - ${(k)options}
</pre>
Here, we're interested in the thing in quotes --- it means exactly the same
here as it would as an element of the matcher list, except that it only
applies to the trial completions given after the `<code>-</code>'. It's in three
bits, separated by spaces; as they're in the same word, all are applied
one after the other regardless of any previous ones having matched.
<p>Starting from the right, you can see that the last part matches letters
case-insensitively; the capital `<code>M</code>' means that, this time, the letters
on the command line, not those in the trial completion are kept; this is
safe because of the way options are parsed, and reduces unexpected changes.
<p>Moving left, you can now guess `<code>M:_=</code>': it means that the `<code>_</code>'
matches nothing at all in the trial completion --- in other words, it is
simply ignored. The rule for matching across the `<code>=</code>' is that you move from
left to right, pairing off characters or elements of character classes as I
already described, and when you run out, you treat any missing characters
as, well, missing.
<p>The first part has an `anchor', indicated by what lies between the `<code>:</code>'
and the `<code>|</code>'; the <code>L</code> indicates that it is anchored on the left. A
left anchor must be present on the command line just to the left of the
pattern, but is not matched against anything in the trial completion.
Since there is nothing between the `<code>:</code>' and the `<code>|</code>', the anchor is
the beginning of the string. This is a special case; if you gave a pattern
here it would look along the word on the command line for the anchor, then
try to match the command line pattern, i.e. `<code>[nN][oO]</code>'. In this case,
it simply matches <code>no</code>, <code>NO</code>, <code>No</code> or <code>nO</code> at the start of the
string, and, just like the `<code>M:_=</code>' part, it ignores it, since there's
nothing on the right. Note again the capital `<code>L</code>' at the start, which
says keep what's on the command line: that's important in this case, since
if you lost the `<code>no</code>', the meaning would change completely.
<p>So consider the combined effect when trying to complete <code>NO_GL</code>. The
first specification allows it to match against <code>_GL</code>; the second allows
it to match against <code>GL</code>; the third, against <code>gl</code>; and finally the
usual effect of completion means that any option beginning <code>gl</code> may be
completed. Try `<code>setopt NO_GL^D</code>' and you should see something like:
<pre>
NO_GLob NO_GLobassign NO_GLobdots
NO_GLobalrcs NO_GLobcomplete NO_GLobsubst
</pre>
--- after the bit you've typed, the form of the words reverts to whatever's
in the trial completion, i.e. lowercase letters with no `<code>_</code>'s.
<p><a name="l57"></a>
<h3>6.7.3: Partial word completion</h3>
<p>This example shows the other sort of anchoring, on the right, and also how
to use a `<code>*</code>' in the right hand part of a pattern. Consider:
<pre>
zstyle ':completion:*' matcher-list 'r:|.=* r:|=*'
</pre>
The `<code>r:</code>' specifies a right-anchored match, using the characters from the
trial completion rather than what's already on the command line. As the
anchor is on the right this time, the pattern (between `<code>:</code>' and `<code>|</code>')
is empty, and its anchor (between `<code>|</code>' and `<code>=</code>') is `<code>.</code>'. So this
specifies that nothing --- a zero length string, or a gap between
characters if you want to think of it like that --- when followed by a
`<code>.</code>', matches anything at all in the trial completion.
<p>Consequently, the second part says that nothing anchored on the right by
nothing --- in other words, the right hand end of the command line string
--- matches anything. This is what completion normally does, add anything
at all at the end of the string; we've added this part to the matcher in
case the cursor is in the middle of the word. It means that the right hand
end will always be completed, too.
<p>Let's see that in action. Here are the actual contents of my actual
<code>tmp</code> directory, never mind why:
<pre>
regframe.rpm t.c testpage.dvi testpage.log testpage.ps
</pre>
Now I set the <code>matcher-list</code> style as above and type:
<pre>
echo t.p<TAB>
</pre>
and get
<pre>
echo testpage.ps
</pre>
So, apart from the normal completion at the end (<code>p</code> to <code>ps</code>), the
empty string followed by a <code>.</code> was allowed to match anything, too, and I
got the effect of completing both bits of the word.
<p>Other shells have a facility for completing inside words like this, where
it goes by such names as `enhanced' completion, although it is usually not
so flexible. In the case of tcsh, not just `<code>.</code>' but also `<code>-</code>' and
`<code>_</code>' have this effect. You can force this with
<pre>
zstyle ':completion:*' matcher-list 'r:|[.,_-]=* r:|=*'
</pre>
<p><a name="l58"></a>
<h3>6.7.4: Substring completion</h3>
<p>As one final example, I've already told you that `<code>r:|=*</code>' completes
anything at the end of the word. From this, you might guess correctly that
`<code>l:|=*</code>' completes anything at the start of the word. By combining
these two, you can make the completion system work when what is on the
command line matches only a substring of a trial completion. Since this
can potentially generate a lot of matches, it might by an idea to try it
after any other matcher specifications you have. So the following tries
case-insensitive completion, than partial-word completion
(case-sensitively), then substring completion:
<pre>
zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}' 'r:|[._-]=* r:|=*' \
'l:|=* r:|=*'
</pre>
<p><a name="l59"></a>
<h3>6.7.5: Final notes</h3>
<p>To put everything together, the possible specifications are
`<code>m:...=...</code>', `<code>l:...|...=...</code>' and `<code>r:...|...=...</code>', which cause
the command line to be altered to the match found, and their counterparts
with an uppercase letter, which cause what's already on the command line to
be left alone and the remaining characters to be inserted directly from the
completion found. The `<code>...</code>' are patterns, which all use the same
format. They can include literal characters, a `<code>?</code>', and character or
correspondence classes, while the rightmost pattern in each type may also
consist of a `<code>*</code>' on its own. Characters are matched from left to
right; a missing character matches an empty string, `<code>*</code>' matches any
number of characters. Specifications may be joined in a single string, in
which case all parts will be applied in turn. When using
the <code>matcher-list</code> style, a list of different specifications can be
given; in this case, they will be tried in turn until one of them generates
matches, and the rest will not be used.
<p>There's another style apart from <code>matcher-list</code>, called <code>matcher</code>.
This can be set for a particular context, possibly with specific tags, and
will add the given matcher specifications using exactly the same syntax as
<code>matcher-list</code> for that context, except that here all specifications are
used at once, even if they are given as different elements of an array.
This is possibly useful because <code>matcher-list</code> is only aware of the
completer, not of any more specific part of the context.
<p>Although I won't talk about matching control again, there may be cases
where you want to include `<code>compadd -M ...</code>' in a completion function of
your own to help the user. Many of the existing completion functions
provide partial word completion where it seems useful; for example,
completion of zle functions allows <code>i-c-w</code> to be completed to
<code>incremental-complete-word</code> in this way.
<p><a name="l60"></a>
<h2>6.8: Writing new completion functions and widgets</h2>
<p>Now down to the nitty gritty. When I first talked about new completion, I
explained that the functions beginning `<code>_</code>' were the core of the system.
For the remainder of the chapter, I'll explain what goes in them. However,
I'll try to do it in such a way that you don't need to know all the
details. The trade off is that if you just use the simplest way of
writing functions, many of the mechanisms I told you about above,
particularly those involving styles and tags, won't work. For example,
much of the code that helps with smart formatting of completion listings is
buried in the the function `<code>_description</code>'; if you don't know how to
call that --- which is often done indirectly --- then your own
completions won't appear in the same format as the pre-defined ones.
<p>The easiest way of getting round that is to take a dual approach: read the
following as far as you need, but also try to find the existing completion
that comes nearest to meeting your needs, then copy that and change it.
For example, here's the function that completes files ending in <code>.gz</code>,
which are files compressed by the <code>gzip</code> program, for use by the
corresponding program that does decompression, <code>gunzip</code> --- hence the
file and function are called <code>_gunzip</code>:
<pre>
#compdef gunzip zcat
local expl
_description files expl 'compressed file'
_files "$expl[@]" -g '*.[gG][zZ]'
</pre>
You can probably see straight away that if you want to design your own
completion function for a command which takes, say, files ending in
<code>.exe</code>, you need to change three things: the line at the top, which
gives the names of programmes whose arguments are to be completed here,
the description `<code>compressed file</code>' to some appropriate string,
and the argument following the <code>-g</code> to something like <code>'*.exe'</code> --- any
globbing pattern should work, just remember to quote it, since it shouldn't
be expanded until the inside of the function <code>_files</code>. Once you've
installed that somewhere in your <code>$fpath</code> and restarted the shell,
everything should work, probably following a longer pause than usual as
the completion system has to rescan every completion function when it finds
there is a new one.
<p>What you might miss is that the first argument to <code>_description</code>,
`<code>files</code>', is the all-important mystical tag for the type of completion.
In this case, you would probably want to keep it. Indeed, the <code>_files</code>
function is used for all file completions of any type, and knows all about
the other tags --- <code>globbed-files</code>, <code>directories</code>, <code>all-files</code> --- so
virtually all your work's done for you here.
<p>If you're adding your own functions, you will need your own functions
directory. This was described earlier in this guide, but just to remind
you: all you need to is create a directory and add it to <code>$fpath</code> in
either <code>.zshenv</code> (which a lot of people use) or <code>.zshrc</code> (which some
sticklers insist on, since it doesn't affect non-interactive shells):
<pre>
fpath=(~/funcs $fpath)
</pre>
It's best to put it before the standard completion directories, since then
you can override a standard completion function simply by copying it into
your own directory; that copy will then be found first and used. This is a
perfectly reasonable thing to do with any completion function --- although
if you find you need to tweak one of the larger standard functions, that's
probably better done with styles, and you should suggest this to us.
<p><a name="l61"></a>
<h3>6.8.1: Loading completion functions: <code>compdef</code></h3>
<p>The first thing to understand is that top line of <code>_gunzip</code>. The
`<code>#compdef</code>' tag is what tells the system when it checks through all
files beginning with `<code>_</code>' that this is a function implementing a
completion. Files which don't directly implement completions, but are
needed by the system, instead have the single word `<code>#autoload</code>' at that
point. All files are only loaded when needed, using the usual autoloading
system, to keep memory usage down.
<p>You can supply various options to the `<code>#compdef</code>' tag; these are listed
in the `<code>Initialization</code>' section of the <code>zshcompsys(1)</code> manual page or
`<strong>Completion System</strong>' info node. The most useful are <code>-k</code> and <code>-K</code>,
which allow you to define a completion command and binding rather than a
function used in a particular context. There are also <code>-p</code> and <code>-P</code>
which tell the system that what follows is a pattern rather than a literal
command name; any command matching the pattern will use that completion
function, unless you used <code>-P</code> and a normal (non-pattern) completion
function for the name was found first.
<p>For normal <code>#compdef</code> entries, however, what comes next is a list of
command names --- or rather a list of contexts, since the form
`<code>-context-</code>' can be used here. For example, the function <code>_default</code>
has the line `<code>#compdef -default-</code>'. You can give as many words as you
like and that completion will be used for each. Note that contexts in the
colon-separated form can't appear here, just command names or the special
contexts named with hyphens.
<p>The system does its work by using a function <code>compdef</code>; it gets as
arguments more or less what you see, except that the function name is
passed as the first argument. Thus the <code>_gunzip</code> completion is loaded by
`<code>compdef _gunzip gunzip zcat</code>', <code>_default</code> by `<code>compdef _default
-default-</code>', and so on. This simply records the name of the function
handling the context in the <code>$_comps</code> associative array which you've
already met. You can make extra commands/contexts be handled by an
existing completion function in this way, too; this is generally more
convenient than copying and modifying the function. Just add `<code>compdef
<_function> <command-to-handle></code>' to <code>.zshrc</code> after the call to
<code>compinit</code>.
<p><a name="l62"></a>
<h3>6.8.2: Adding a set of completions: <code>compadd</code></h3>
<p>Once you know how to make a new completion function, there is only one
other basic command you need to know before you can create your own
completions yourself. This is the builtin <code>compadd</code>. It is at the heart
of the completions system; all its arguments, after the options, are taken
as possible completions. This is the list from which the system selects
the possibilities that match what you have already typed. Here's a very
basic example which you can type or paste at the command line:
<pre>
_foo() { compadd Yan Tan Tethera; }
compdef _foo foo
</pre>
Now type `<code>foo </code>' and experiment with completions after it. If only it
were all that simple.
<p>There are a whole list of options to <code>compadd</code>, and you will have to look
in the <code>zshcompwid(1)</code> manual page or the `<code>Completion Widgets</code>' info
node for all of them. I've already mentioned <code>-M</code> and (long ago) <code>-f</code>.
Here are other interesting ones. <code>-X <description></code> provides a
description --- this is used by the <code>format</code> style to pass descriptions,
and if you use the normal tags system you shouldn't pass it directly; I'll
explain this later.
<p><code>-P <prefix></code> and <code>-S <suffix></code> allow you to specify bits which are not
treated as part of the completion, but appear on the line none the less.
In fact, they do two different things: if the prefix or suffix is already
there, it is ignored, and if it isn't, it is inserted. There are also
corresponding hidden and ignored prefixes, necessary for the full power of
the completion system, but you will need to read the manual for the full
story. The <code>-q</code> option is useful with <code>-S</code>; it enables auto-remove
behaviour for the suffix you gave, just like <code>/</code> with the
<code>AUTO_REMOVE_SLASH</code> option when completing filenames.
<p><code>-J <group></code> is the way group names are specified, used by the
<code>group-name</code> tag; there is also <code>-V <group></code>, but the group here is not
sorted (and is distinct from any group of the same name passed to <code>-J</code>).
<code>-Q</code> tells the completion code not to quote the words --- this is
essentially useful in those few cases where you need to have unquoted
metacharacters in the final completion.
<p><code>-U</code> tells <code>compadd</code> to use the list of completions even if they don't
match what's on the command line; you will need this if your completion
function modifies the prefix or suffix so that they no longer fit what's
already there. If you use this, you might consider turning on menu
completion (using <code>compstate[insert]=menu</code>), since it might otherwise be
difficult to select the appropriate completion.
<p>Finally, note the <code>-F</code> and <code>-W</code> options which I describe below for
<code>_files</code> actually are options to <code>compadd</code> too.
<p><a name="l63"></a>
<h3>6.8.3: Functions for generating filenames, etc.</h3>
<p>However, for most types of completion the possibilites will not be a simple
list of things you already know, so that you need to have some way of
generating the required values. In this section, I will describe some of
the existing functions you can call to do the hard work. In the next
section I will show how to retrieve information from some special
parameters made available by the <code>zsh/parameter</code> module.
<p><p><strong>Files etc.: the function <code>_files</code></strong><br><br>
<p>You have already seen <code>_files</code> in action. Calling this with no arguments
simply adds all possible files as completions, taking account of the word
on the command line to establish directories and so on.
<p>For more specific use, you can give it various options: `<code>-/</code>' means
complete directories, and, as you saw, `<code>-g "<pattern>"</code>' gives a
filename generation pattern to produce matching files.
<p>A couple of other options, which can be combined with the ones above, are
worthy of mention. If you use `<code>-W <dir></code>', then completion takes place
under directory <code><dir</code>> rather than in the current directory --- it has
no effect if you are using an absolute path. Here, `<code><dir></code>' can also be
a set of directories separated by spaces or, most usefully since it avoids
any problems with quoting, the name of an array variable which contains the
list of possible directories. This is essentially how completion for
<code>cd</code> with the <code>$cdpath</code> array works. So if you have a program that
looks for files with the suffix `<code>.mph</code>', first in the current directory,
then in a standard directory, say, <code>/usr/local/oomph/files</code>', you can do
this:
<pre>
local oomph_dirs
oomph_dirs=(. /usr/local/oomph)
_files -W oomph_dirs -g '*.mph'
</pre>
--- note there is no `<code>$</code>' before the variable <code>$oomph_dirs</code> here,
since it should only be expanded deep inside <code>_files</code>.
<p>The system that implements <code>$fignore</code> and the <code>ignored-suffixes</code> style
can be intercepted, if you need to, with the option `<code>-F "<pat>"</code>';
`<code><pat></code>' is an array of patterns to ignore, in the usual completion
format, in other words the name of a real shell array, or a list of values
inside parentheses. If you make sure all the tags stuff is handled
properly, <code>ignored-suffixes</code> will work automatically, however, and in
addition extended globbing allows you to specify patterns with exclusion
directly, so you probably won't use this feature directly unless you're in
one of your superhero moods.
<p>In addition, <code>_files</code> also takes many of the standard completion options
which apply to <code>compadd</code>, for convenience.
<p>Actually, the function <code>_path_files</code> is the real engine room of the
system. The advantage of using <code>_files</code> is that it prepares all the tags
for you, deciding whether you want directories to be completed as well as
the globbed files, and so on. If you have particularly specific needs you
can use <code>_path_files</code> directly, but you won't get the automatic
fallback one <code>directories</code> and <code>all-files</code>.
<p><p><strong>Parameters and options</strong><br><br>
<p>These can be completed by calls to the <code>_parameters</code> and <code>_options</code>
functions, respectively. Both set up their own tags, and <code>_options</code> uses
the matching control mechanism described above to allow options to be given
in all the available forms. As with <code>_files</code>, they will also pass
standard <code>compadd</code> options down to that function.
<p>For more detailed control with options, the functions <code>_set_options</code> and
<code>_unset_options</code> behave like <code>_options</code>, but the possible completions
are limited to options which are set or unset, respectively. However, it's
not that simple: the completion system itself alters the options, and you
need to enable some code near the top of <code>_main_complete</code> (it's clearly
marked) to remember the options which were set or unset when completion
started. A straw poll based on a sample of two zsh developers revealed
that in any case many people don't like the completion system to second
guess the options they want to set or unset in this way, so it's probably
better just to stick to <code>_options</code>.
<p><p><strong>Miscellaneous</strong><br><br>
<p>There are also many other completion functions adding matches of a certain
type. These can be used in the same way as <code>_parameters</code> and
<code>_options</code>; in other words they do all the work needed for tags
themselves and can be given options for <code>compadd</code> as arguments.
Normally, these functions are named directly after the type of matches they
generate, like <code>_users</code>, <code>_groups</code>, <code>_hosts</code>, <code>_pids</code>, <code>_jobs</code>,
etc.
<p><a name="l64"></a>
<h3>6.8.4: The <code>zsh/parameter</code> module</h3>
<p>From version 3.1.7, the new completion system automatically makes the
<code>zsh/parameter</code> module available for use. This provides an easy way of
generating arguments for <code>compadd</code>; in version 3.1.6, there was a
different command, <code>compgen</code>, which generated completions in a similar
way to <code>compctl</code>, i.e. with lots of horribly unmemorable single-letter
options. To get the maximum use out of this, you should be familiar with
zsh's rather self-willed syntax for extracting bits out of associative
arrays. In particular, note <code>${(k)assoc}</code>, which expands to a list of
the keys of the associative array <code>$assoc</code>, <code>${(v)assoc}</code>, which
expands to just its values (actually, so does <code>$assoc</code> on its own), and
<code>${(kv)assoc}</code> which produces key/value pairs. For all intents and
purposes, the keys and values, or the pairs of them, are in a random order,
but as the completion system does it's own sorting that shouldn't be a
problem. Mostly, the important parts for completion are in the keys,
i.e. to add all aliases as possible completions, you need
`<code>compadd ${(k)aliases}</code>'.
<p>Here's a list of associative and ordinary arrays provided; for more
information on the values of the associative arrays, which could be useful
in some cases, consult the section <strong>The zsh/parameter Module</strong> in the
<code>zshmodules(1)</code> manual page or the corresponding info node. First, the
associative arrays.
<p><dl>
<p></p><dt><strong><code>$aliases</code>, <code>$dis_aliases</code>, <code>$galiases</code></strong><dd>
The keys of these arrays give ordinary aliases, disabled ordinary
aliases for those where you have done <code>disable -a <alias></code> to turn
them off temporarily, and global aliases as defined with <code>alias -g</code>.
<p></p><dt><strong><code>$builtins</code>, <code>$dis_builtins</code></strong><dd>
The keys give active and disabled shell builtin commands.
<p></p><dt><strong><code>$commands</code></strong><dd>
The keys are all external commands stored in the shells internal
tables; it does this both for the purposes of fast completion, and to
avoid having to search each time a command is executed. It's possible
that a command is missing or incorrectly stored if the contents of
your <code>$path</code> directories has changed since the shell last updated
its tables; the <code>rehash</code> command fixes it.
<p></p><dt><strong><code>$functions</code>, <code>$dis_functions</code></strong><dd>
The keys are active and disabled shell functions.
<p></p><dt><strong><code>$history</code></strong><dd>
Here, the <em>values</em> are complete lines stored in the internal
history. The keys are the numbers of the history line; it's an
associative, rather than an ordinary, array because they don't
necessarily start at line 1. However, see the <code>historywords</code>
ordinary array below.
<p></p><dt><strong><code>$jobtexts</code>, <code>$jobdirs</code>, <code>$jobstates</code></strong><dd>
These give you information about jobs; the keys are the job numbers,
as presented by the <code>jobs</code> command, and the values give you the other
information from jobs: <code>$jobtexts</code> tells you what the job is
executing, <code>$jobdirs</code> its working directory, and <code>$jobstates</code>
its state, where the bit before the colon is the most useful as it
refers to the whole job. The remainder describes the state of
individual processes in the job.
<p></p><dt><strong><code>$modules</code></strong><dd>
The keys give the names of modules which are currently available
to the shell, i.e. loaded or to be autoloaded, essentially the same
principle as with functions.
<p></p><dt><strong><code>$nameddirs</code></strong><dd>
If you have named directories, either explicitly (e.g. assigning
`<code>foo=/mydir</code>' and using `<code>~foo</code>') or via the <code>AUTO_NAME_DIRS</code>
option, the keys of this associative array give the names and the
values the expanded directories.
<p></p><dt><strong><code>$options</code>, <code>$parameters</code></strong><dd>
The keys give shell options and parameters, and are used by the
functions <code>_options</code> and <code>_paramaters</code> for completion, so you
will mostly not need to refer to them directly.
<p></p><dt><strong><code>$userdirs</code></strong><dd>
The keys give all the users on the system. The values give the
corresponding home directory, so `<code>${userdirs[juser]}</code>' is equivalent
to having <code>~juser</code> expanded and is thus not all that interesting,
except that by doing it this way you can test whether the expansion
exists without causing an error.
</dl>
<p>Now here are the ordinary arrays, which you would therefore refer to simply
as <code>${reswords}</code> etc.
<p><dl>
<p></p><dt><strong><code>$dirstack</code></strong><dd>
This contains your directory stack, what you see with `<code>dirs -v</code>'.
Note, however that the current directory, which appears as number 0
with that command, doesn't appear in <code>dirstack</code>. Of course it's
easy to add it to a completion if you want.
<p></p><dt><strong><code>$funcstack</code></strong><dd>
This is the call stack of functions, i.e. all the functions which
are active at the time the array was referenced. <code>^Xh</code> uses this
to display which functions have been called for completion.
<p></p><dt><strong><code>$historywords</code></strong><dd>
Unlike <code>$history</code>, this contains just the individual words of the
shell's command line history, and is therefore likely to be more useful
for completion purposes.
<p></p><dt><strong><code>$reswords</code>, <code>$dis_reswords</code></strong><dd>
The active and disabled reserved words (effectively syntactically
special commands) understood by the shell.
</dl>
<p><p><strong>Other ways of getting at information</strong><br><br>
<p>Since the arguments to <code>compadd</code> undergo all the usual shell expansions,
it's easy to get words from other sources for completion, and you can look
in the existing completion functions for many examples. A good
understanding of zsh's parameter and command expansion mechanisms and a
strong stomach will be useful here.
<p>For example, here is the expansion used by the <code>_limits</code> function to
retrieve the names of resource limits from the <code>limit</code> command itself:
<pre>
print ${${(f)"$(limit)"}%% *}
</pre>
which you can test does the right thing. Here's a translation:
<code>"$(limit)"</code> calls the command in a quoted context, which means you get
the output as if it were a single file (just type `<code>limit</code>' to see what
that is). <code>${(f)...}</code> splits this into an array (it is now outside
quotes, so splitting will generate an array) with one element per line.
Finally, <code>${...%% *}</code> removes the trailing end of each array element from
the first piece of whitespace on, so that `<code>cputime unlimited</code>'
is reduced to `<code>cputime</code>', and so on. Type `<code>limit ^D</code>', and you will
see the practical upshot of this.
<p>That's by no means the most complicated example. The nested expansion
facility is used throughout the completion functions, which adds to brevity
but subtracts considerably from readability. It will repay further study,
however.
<p><a name="l65"></a>
<h3>6.8.5: Special completion parameters and <code>compset</code></h3>
<p>Up to now, I've assumed that at the start of your completion function you
already know what to complete. In more complicated cases that won't be the
case: different things may need completing in different arguments of a
command, or even some part of a word may need to be handled differently
from another part, or you need to look for a word following a particular
option. I will first describe some of the lower level facilities which
allow you to manipulate this; see the manual page <code>zshcompwid(1)</code> or the
info node <strong>Completion Widgets</strong> for the details of these. Later, I will
show how you can actually skip a lot of this for ordinary commands with
options and arguments by using such functions as <code>_arguments</code>, where you
simply specify what arguments and options the function takes and what sort
of completion they need.
<p>The heart of this is the special parameters made available in completion
for testing what has already been typed. It doesn't matter if there are
parameters of that name outside the completion system; they will be safely
hidden, the special values used, and the original values restored when
completion is over.
<p><code>$words</code> is an array corresponding to the words on the command
line --- where by a `word' I mean as always a single argument to the
command, which may include quoted whitespace. <code>$CURRENT</code> is the index
into that array of the current word. Note that to avoid confusion the
ksh-like array behaviour is explicitly turned off in <code>_main_complete</code>, so
the command itself is <code>$words[1]</code>, and so on.
<p>The word being completed is treated specially. The reason is that you may
only want to complete some of it. An obvious example is a file with a
path: if you are completing at `<code>foo/bar</code>', you don't want to have to
check the entire file system; you want the directory <code>foo</code> to be fixed,
and completion just for files in that. There are actually two parts to
this. First, when completion is entered, <code>$PREFIX</code> and <code>$SUFFIX</code> give
you the part of the current word before the cursor, and the remainder,
respectively. It's done like this to make it possible to write functions
for completing inside a word, not just at the end. The simplest possible
way of completing a file is then to find everything that matches
<code>$PREFIX*$SUFFX</code>.
<p>But there's more to it than that: you need to separate off the directory,
hence the second part. The parameters <code>$IPREFIX</code> and <code>$ISUFFIX</code>
contain a part of the string which will be ignored for completion. It's up
to you to decide what that is, then to move the bit you want to be ignored
from <code>$PREFIX</code> to <code>$IPREFIX</code> (that's the usual case) or from
<code>$SUFFIX</code> to <code>$ISUFFIX</code>, making sure that the word so far typed is
still given by <code>$IPREFIX$PREFIX$SUFFIX$ISUFFIX</code>. Thus in completing
<code>foo/bar</code>, you would strip <code>foo/</code> from the start of <code>$PREFIX</code> and
tack it onto the end of <code>$IPREFIX</code> --- after recording the fact that you
need to move to directory <code>foo</code>, of course. Then you generate files in
<code>foo</code>, and the completion system will happily accept <code>barrack</code> or
<code>barbarous</code> as completions because it doesn't care about the <code>foo</code> any
more.
<p>Actually, this is already done by the the <code>_files</code> and <code>_path_files</code>
functions for filename completion. Also, you can get some help using the
<code>compset</code> builtin command. In this case, the incantation is
<pre>
if compset -P "*/"; then
# do whatever you need to with the leading string up to / stripped off
else
# no prefix stripped, do whatever's necessary in this case
fi
</pre>
In other words, any initial match of the pattern `<code>*/</code>' in <code>$PREFIX</code> is
removed and transferred to the end of <code>$IPREFIX</code>; the command status
tells you whether this was done. Note that it is the longest possible such
match, so if there were multiple slashes, all will be moved into
<code>$IPREFIX</code>. You can control this by putting a number <code><N></code> between the
<code>-P</code> and the pattern, which says to move only up to the <code><N></code>th such
match; here, that would be a pattern with exactly <code><N></code> slashes. Note
that <code>-P</code> stands for prefix, not pattern; there is a corresponding <code>-S</code>
option for the suffix. See the manual for other uses of <code>compset</code>; these
are probably the most frequent.
<p>If you want to make the test made by <code>compset</code>, but without the side
effect of changing the prefixes and suffixes, there are tests like this:
<pre>
if [[ -prefix */ ]]; then
# same as with `compset -P "*/"', except prefixes were left alone.
fi
</pre>
These have the advantage of looking like all the standard tests understood
by the shell.
<p>There are three other parameters special to completion. The <code>$QIPREFIX</code>
and <code>$QISUFFIX</code> are a special prefix and suffix used when you are
dividing up a quoted word --- for example, in `<code>zsh -c "echo hi"</code>', the
word <code>"echo hi"</code> is going to be used as a command line in its own right,
so if you want to do completion there, you need to have it split up. You
can use `<code>compset -q</code>' to split a word in this fashion.
<p>There is also an associative array <code>$compstate</code>, which allows you to
inspect and change the state of many internal aspects of completion, such as
use of menus, context, number of matches, and so on. Again, consult the
manual for more detail. Many of the standard styles work by altering
elements of <code>$compstate</code>.
<p>Finally, in addition to the parameters special to completion, you can
examine (but not alter) any of the parameters which appear in all editing
widgets: <code>$BUFFER</code>, the contents of the current editing line;
<code>$LBUFFER</code>, the part of that before the cursor; <code>$RBUFFER</code>, the rest;
<code>$CURSOR</code>, the index of the cursor into <code>$BUFFER</code> (with the first
character at zero, in this case --- or you can think of the zero as being
the point before the first character, which is where insertion would take
place with the cursor on the first character); <code>$WIDGET</code> and
<code>$LASTWIDGET</code>, the names of the current and last editing or completion
widget; <code>$KEYS</code>, the keys typed to invoke the current widget;
<code>$NUMERIC</code>, any numeric prefix given, unset if there is none, and a few
other probably less useful values. These are described in the
<code>zshzle(1)</code> manual page and the <code>Zsh Line Editor</code> info node. In
particular, I already mentioned <code>$NUMERIC</code> as of possible use in various
styles, and it is used by the completers which understand a `<code>numeric</code>'
value in their relevant styles; the <code>$WIDGET</code> and <code>$KEYS</code> parameters
are useful for deciding between different behaviours based on what the
widget is called (as in <code>_history_complete_word</code>), or which keys are used
to invoke it (as in <code>_bash_completions</code>).
<p>Here are a few examples of using special parameters and <code>compset</code>.
<p>One of the shortest standard completions is this, <code>_precommand</code>:
<pre>
#compdef - nohup nice eval time rusage noglob nocorrect exec
shift words
(( CURRENT-- ))
_normal
</pre>
It applies for all the standard commands which do nothing but evaluate
their remaining arguments as a command, with some change of state,
e.g. ignoring a certain signal (<code>nohup</code>) or altering the priority (<code>nice</code>).
All the completion system does here is shift the first word off the end of
the <code>$words</code> array, decrement the index of the current word into
<code>$words</code>, and call <code>_normal</code>. This is the function called when
completion occurs not in one of the special <code>-context-</code>s, in other words
when an argument to an ordinary command is being completed. It will look
at the new command word <code>$words[1]</code>, which was previously the first
argument to <code>nohup</code> or whatever, and start completion again based on that,
or even complete that word itself as a command if necessary. The net
effect is that the first word is ignored completely, as required.
<p>Here's just an edited chunk of the file <code>_user_at_host</code>; as its name
suggests, it completes words of the form <code><user>@<host></code>, and it's used
anywhere the <code>user-hosts</code> style, described above, is appropriate:
<pre>
if [[ -prefix 1 *@ ]]; then
local user=${PREFIX%%@*}
compset -P 1 '*@'
# complete the host for which we want the user
else
# no @, so complete the user
fi
</pre>
We test to see if there is already a `<code><user>@</code>' part. If there is, we
extract the user with an ordinary parameter substitution (so ordinary even
other shells could do it). Then we strip off that from the bit to be
completed with <code>compset</code>; we already know it matches the prefix, so we
don't need to test the return value. Then we just do normal hostname
completion on what remains --- except that the <code>user-hosts</code> style might be
able to give us a clue as to which hosts have such a user. If the original
test failed, then we simply complete what's there as a user.
<p>Finally, here is essentially what the function <code>_most_recent_file</code> uses
to extract the <code>$NUMERIC</code>th (default first) most recently modified file.
<pre>
local file
file=($~PREFIX*$~SUFFIX(om[${NUMERIC:-1}]N))
(( $#file )) && compadd -U -i "$IPREFIX" -I "$ISUFFIX" -f -Q - $file
</pre>
Instead of doing it with mirrors, this uses globbing qualifiers to extract
the required file; <code>om</code> specifies ordering by modification time, and the
expression in square brackets selects the single match we're after. The
<code>N</code> turns on <code>NULL_GLOB</code>, so <code>$file</code> is empty if there are no
matches, and the parameter expansions with `<code>$~</code>' force patterns in
<code>$PREFIX</code> and <code>$SUFFIX</code> to be available for expansion (a little extra
feature I use, although ordinary completion would work without).
<p>Most of the <code>compadd</code> command is bookkeeping to make sure the parts of
the prefix and suffix we've already removed, if there are any, get passed
on, but the reason for that deserves a mention, since normally this is
handled automatically. The difference here is that <code>-U</code> usually replaces
absolutely everything that was in the word before, if you need to keep it
you have to pass it back to <code>compadd</code>. So for example suppose you were
in a context where you were completing at `<code>file=...</code> and you had told
the completion system that everything up to `<code>file=</code>' was not to count
and not to be shown as part of the completion. You would want to keep that
when the word was put back on the command line. However, `<code>-U</code>' would
delete that too. Hence the `<code>-i "$IPREFIX"</code>' to make sure it's
retained. The same argument goes for the ignored suffix.
<p><a name="l66"></a>
<h3>6.8.6: Fancier completion: using the tags and styles mechanism</h3>
<p>At this point, you should be in a position to construct, although maybe not
in the best possible way, pretty much any completion list you want. Now I
need to explain how you make sure it all fits in with the usual tags and
styles system. You will need to pick appropriate tags for your
completions. Although there is no real restriction, it's probably best to
pick one of the standard tags, some of which are suitably general to cover
just about anything: <code>files</code>, <code>options</code>, <code>values</code>, etc. There is a
list in the completion system manual entry. Remember that the main use for
tags is to choose what happens when more than one tag can be completed in
the same place. Finding such things that can't be separated using the
standard tag names is a good reason for inventing some new ones; you don't
have to do anything special if the tag names are new, just make sure
they're documented for anyone using the completion function.
<p><p><strong>How to call functions so that `It Just Works'</strong><br><br>
<p>For a simple completion, without multiple tags, you can do one of two
things. First, you can use the <code>_description</code> function, which is usually
called with three arguments: the name of the tag you're completing for,
the name of a variable which will become an array containing arguments to
pass to <code>compadd</code>, and the full description. Then you have to make sure
that array gets passed down to <code>compadd</code>, or to any of the higher-level
completion functions which will pass the arguments on to <code>compadd</code>.
For example,
<pre>
local expl
_description files expl 'my special files'
_files "$expl[@]"
</pre>
This sets the files tag; <code>_description</code> sets <code>$expl</code> to pass on the
description, and maybe other things such as a group name for the tag, in
the appropriate format; we pass this down to <code>_files</code> which will use it
for calling <code>compadd</code>. Generally, you will call <code>_description</code> for
each time you call <code>compadd</code> or something that in turn calls <code>compadd</code>.
<p>The <code>_description</code> function calls another function <code>_setup</code> to do much
of the setting up of styles for the particular tag. Mostly, <code>_setup</code> is
buried deeply enough that you don't need to worry about it yourself.
Sometimes you can't do completion, and just want to print a message
unconditionaly to say so, irrespective of tags etc.; the function
<code>_message</code> does this, taking the message as its sole argument.
<p>Secondly, and more typically, you can use the function <code>_wanted</code>, which
is called in the same way as <code>_description</code>, but does some extra work to
find out if completion with the tag passed to it is really wanted. It's
down here that all the stuff with <code>tag-order</code> is worked out. As it
returns a status, you use it like this:
<pre>
_wanted values expl 'values for my special things' &&
compadd "$expl[@]" alpha bravo charlie delta echo foxtrot
</pre>
<p>However, if your function handles multiple tags, you need to loop over the
different tags to find out which sort the tag order wants next. For this,
you first need to tell the system which tags are coming up, using the
<code>_tags</code> function with a list. Then you need to to test whether each tag
in turn actually needs to be completed, and go on doing this until you run
out of tags which need completions performing. The end result looks like
this:
<pre>
local expl ret=1
_tags foo bar rod
while _tags; do
if _requested foo expl "This is the description for tag foo"
compadd "$expl[@]" - all foos completions && ret=0
fi
if _requested bar expl "This is the description for tag bar"
compadd "$expl[@]" - all bars completions && ret=0
fi
if _requested rod expl "This is the description for tag rod"
compadd "$expl[@]" - all rods completions && ret=0
fi
(( ret )) || return 0 # leave if matches were generated
done
</pre>
You can miss out the second and third arguments for <code>_requested</code> if you
like. As you might guess from the way I've used it, <code>_requested</code> is
rather like <code>_wanted</code> but is designed for more complicated cases, where
different sets of tags may be want..., er, requested: specifically, you
call the <code>_tags</code> function yourself, whereas <code>_wanted</code> assumes the only
valid tag is its argument and acts accordingly.
<p>All three of <code>_description</code>, <code>_wanted</code> and <code>_requested</code> take the
options <code>-J</code> and <code>-V</code> for to specify sorted or unsorted listings and
menus, and the options <code>-1</code> and <code>-2</code> for removing consecutive
duplicates or all duplicates. These are also options to <code>compadd</code>; the
reason for handling them here is that they can be different for each tag,
and the function called will set <code>expl</code> appropriately.
<p>If your requirements are simple enough, you can replace that
<code>_tags</code>/<code>_requested</code> loop above with a single function,
<code>_alternative</code>. This takes a series of arguments each in the form
`<tag>:<description>:<action>', with the first two in the form you now
know, and the third an action. These are essentially the same as actions
for the <code>_arguments</code> function, described below, except that the form
`<code>->state</code>', which says that the calling function will handle the action
itself by using the value of the parameter <code>$state</code>, is not available.
The most common forms of action here will be a call to another completion
function, maybe with arguments (e.g. `<code>_files -/</code>'), or a simple list in
parentheses (e.g. `<code>(see saw margery daw)</code>'). Here, for example, is how
the <code>_cd</code> function handles the two cases of local directories (under the
current directory) and directories reached via the <code>$cdpath</code> parameter:
<pre>
local tmpcdpath
tmpcdpath=(${(@)cdpath:#.})
_alternative 'local-directories:local directories:_path_files -/' \
'path-directories:directories in cdpath:_path_files -W tmpcdpath -/'
</pre>
The only tricky bit is that <code>$tmpcdpath</code>: it removes the `<code>.</code>' from
<code>$cdpath</code>, if it's present, so that the current directory is always
searched for with the tag `<code>local-directories</code>', never with
`<code>path-directories</code>'. Actually, you could argue that it should be
treated as being in `<code>path-directories</code>' when it's present; but that
confuses the issue over what `<code>local-directories</code>' really means, and it
is useful to have the distinction.
<p>It's now an easy exercise to replace the example function I gave for
<code>_requested</code> by a call to <code>_alternative</code> with the arguments to
<code>compadd</code> turned into a list in parentheses as the <code><action></code> part of
the arguments to <code>_alternative</code>.
<p><p><strong>How to look up styles</strong><br><br>
<p>If your completion function gets really sophisticated, you may want it
to look up styles to decide what its behaviour should be. The same advice
goes as for tags: only invent a new style if the old ones don't seem to
cover the use you want to make, since by using contexts you can always
restrict the scope of the style. Retrieving values of styles is no harder
than defining them, but you will need to know about the parameter
<code>$curcontext</code>, which is what stores the middle part of the context,
sans `<code>:completion:</code>' and sans tag. When you need to look something up,
you pass this context to <code>zstyle</code> with `<code>:completion:</code>' stuck in front:
<pre>
zstyle -b ":completion:${curcontext}:tag" style-name parameter
</pre>
If the tag is irrelevant, you can leave it empty, but you still need the
final colon. In some cases where multiple tags apply it's useful to have a
<code>:default</code> tag context as a fall back if none of the actual tags yield
styles for that context; hence you should test the style first for the
specific tag, then with the <code>default</code>.
<p>Style lookups all have the form just shown; the result for looking up
<code>style-name</code> in the given context will be saved in the <code>parameter</code>
(which you should make local, obviously). In addition, <code>zstyle</code> returns
a zero status if the lookup succeeded and non-zero if it failed. The
<code>-t</code> lookup is different from the rest as it only returns a status for a
boolean, i.e. returns status 0 if the value is <code>true</code>, <code>yes</code>, <code>1</code> or
<code>on</code>, and doesn't require a parameter name. There is also a <code>-T</code>,
which is identical except that it returns status 0 if the style doesn't
exist, i.e. the style is taken to default to true.
<p>The other lookup options return the style as a particular type in the
parameter with exit status zero if the lookup succeeded, i.e. a value was
found, and non-zero otherwise; <code>-b</code>, <code>-s</code>, <code>-a</code> and <code>-h</code> specify
boolean (<code>parameter</code> is either <code>yes</code> or <code>no</code>), scalar (<code>parameter</code>
is a scalar), array (<code>parameter</code> is an array, which may still be a single
word, of course), and associative array (alternative elements of the style
giving key and value), respectively. There's also a convenience option for
matching <code>-m</code>; instead of a <code>parameter</code> this takes a <code>pattern</code> as the
final argument, and returns status zero if and only if the <code>pattern</code>
matches one of the values stored in the style for the given context.
<p>Typical usages are thus:
<pre>
if zstyle -t ":completion:${curcontext}:" foo; then
# do things in a fooish way
else
# do things in an unfooish way
fi
</pre>
or to use the value:
<pre>
local val
if zstyle -s ":completion:${curcontext}:" foo val; then
# use $val to establish how fooish to be
else
# be defaultly fooish
fi
</pre>
<p><a name="l67"></a>
<h3>6.8.7: Getting the work done for you: handling arguments etc.</h3>
<p>The last piece of unfinished completion business is to explain the higher
level functions which can save you time writing completions for commands
which behave in a standard way, with arguments and options.
<p><p><strong>Handling ordinary arguments</strong><br><br>
<p>The most useful function is <code>_arguments</code>. There are many examples of
this in the completion functions for external commands, since so many
external commands take the standard format of a command with options, some
taking their own arguments, plus command arguments.
<p>The basic usage is to call it with a series of arguments (which I'll call
`specifications') like:
<pre>
<where I am>:<description>:<what action to take>
</pre>
although there are a whole series of more complicated possibilities.
<p>The initial `<code><where I am></code>' part tells the function whether the
specification applies to an argument in a particular position, or to an
option and possibly any arguments for that option. Let's start with
ordinary arguments, since these are simpler. In this case `<code><where I
am></code>' will be either a number, giving the number of the argument, or a
`<code>*</code>', saying that this applies to all remaining arguments (or all
arguments, if you haven't used any of the other form). You can simplify
the first form, by just missing out the number; then the function will
assume it applies to the first argument not yet specified. Hence the
standard way of handling arguments is with a series of specifications just
beginning `<code>:</code>' for arguments that need to be handled their own way, if
any, then one beginning `<code>*:</code> for all remaining arguments, if any.
<p>The message that follows is a description to be passed on down to
<code>_description</code>. You don't specify the tags at this point; that comes
with the action.
<p>The action can have various forms, chosen to be easily disinguishable from
one another.
<ol>
<li> A list of strings in parentheses, such as `<code>(red blue
green)</code>'. These are the possible completions, passed straight down
to <code>compadd</code>.
<li> The same, but with double parentheses; the list in this case
consists of the completion, a backslashed colon, and a description.
So an extended version of the previous action is `<code>((red\:The\
colour\ red blue\:The\ colour\ blue))</code>' and so on. You can escape
other colons inside the specifications in this way, too.
<li> A completion function to call, with any arguments, such as
`<code>_files -/</code>' to complete directories.
<li> A word preceded by `<code>-></code>' for example `<code>->state</code>'. This
specifies that <code>_arguments</code> should return and allow the calling
function to process the argument. To signal back to the calling
function, the parameter <code>$state</code> will be set to what follows the
`<code>-></code>'. It's up to the calling function to make <code>$state</code> a local
parameter --- <code>_arguments</code> can't do that, since then it couldn't
return a value.
<p>You should also make the parameters <code>$context</code>
and <code>$line</code> local; the former is set to the new part to be
added to <code>$curcontext</code>, which, as you can find out from <code>^Xh</code>,
is <code>-<option>-<arg></code>, for example <code>-file-1</code> for the first argument
of the <code>-file</code> option, or <code>-argument-N</code>, for example
<code>argument-2</code> for the second argumument of the command.
<p>In simple cases, you will just test the parameter <code>$state</code>
after <code>_arguments</code> has returned to see what to do: the return
value is 300 to distinguish it from other returns where <code>_arguments</code>
itself performed the completion.
<li> A chunk of code to evaluate, given in braces, which removes the
need for a special function or processing states. Obviously this
is best used for the simplest cases.
</ol>
These are all the main possibilities, but I have not described every
variation. As always, you should see the manual for all the detail.
<p>Here's a concocted example for that `<code>->state</code>' action specifier, in case
it's confusing you. It's for a command that takes arguments `<code>alpha</code>',
`<code>beta</code>' and `<code>gamma</code>', and takes a single option `<code>-type</code>' which
takes one argument, either `<code>normal</code>' or `<code>unusual</code>'.
<pre>
local context state line
typeset -A opt_args
_arguments '-type[specify type]:type:->type' \
'*:greek letter:->gklet' && return 0
case $state in
(type) compadd normal unusual && return 0
;;
(gklet) compadd alpha beta gamma && return 0
;;
esac
return 1
</pre>
In fact the possibilities here are so simple that you don't need to use
<code>$state</code>; you can just use the form with the values in parentheses as the
action passed to `<code>_arguments</code>'. Anyway, if you put this into a function
`<code>_foo</code>', type `<code>compdef _foo foo</code>', and attempt completion for the
fictitious command `<code>foo</code>', you will see <code>_arguments</code> in action.
<p>A note about the form: that `<code>&& return 0</code>' makes the completion function
return if <code>_arguments</code> was satisfied that it found a completion on its
own. It's useful in more complex cases. Remember that most completion
functions return status zero if and only if matches were added; this
function is written to follow that convention.
<p>Note all the things you had to make local: <code>$context</code>, <code>$state</code>,
<code>$line</code> and the associative array <code>$opt_args</code>. The last named allows
you to retrieve the values for a particular option; for example
`<code>$opt_args[-o]</code>' contains any value already on the command line for the
option <code>-o</code>. For functions that take multiple arguments, these appear
separated by colons, so if the line contains `<code>-P prefix 3</code>',
<code>$opt_args[-P]</code> will contain `<code>prefix:3</code>'.
<p><p><strong>Handling options</strong><br><br>
<p>Option handling is broadly similar, with the `<code><where I am></code>' part just
giving the option name. In this case, the option will just be completed to
itself, the first part of the specification, and the rest says how to
complete its arguments. Since options can take any number of
arguments, including zero, the <code>:description:action</code> pair can be
repeated, or omitted entirely. Otherwise, it behaves similarly to the way
described for ordinary command arguments, with all the same possible
actions. So a simple option specification could be
<pre>
_arguments '-turnmeon'
</pre>
for an option with no arguments,
<pre>
_arguments '-file:input file:_files'
</pre>
for an option with one argument, or
<pre>
_arguments '-iofiles:input file:_files:output file:_files'
</pre>
for an option with two arguments, both files but with different
descriptions.
<p>The first part of the specification for an option can be more complicated,
to reflect the fact that options can be used in all sorts of different
ways. You can specify a description for the option itself --- as I tried
to explain, the decriptions in the rest of the specification are instead
for the arguments to the option. To specify an option description, just
put that after the option, before any colons, in square brackets:
<pre>
_arguments '-on[turn me on, why not]'
</pre>
<p>Next, some options to a command are mutually exclusive. As <code>_arguments</code>
has to read its way along the command line to parse it, it can record what
options have already appeared, and can ensure that an option incompatible
with one there already will not be completed. To do this, you need to
include the excluded option in parentheses before the option itself:
<pre>
_arguments '(-off)-on[turn me on, why not]' \
'(-on)-off[turn me off, pleas]'
</pre>
This completes either of the options `<code>-on</code>' or `<code>-off</code>', but if you've
already given one, it won't complete the other on the same command line.
If you need to give multiple excluded options, just list them separated by
spaces, like `<code>(-off -noton)</code>'.
<p>Some options can themselves be repeated; <code>_arguments</code> usually won't do
that (in a sense, they are mutually exclusive with themselves), but you can
allow it to happen by putting a `<code>*</code>' in front of the option
specification:
<pre>
_arguments '*-o[specify extra options]:option string:->option'
</pre>
allows you to complete any number of `<code>-o <option></code>' sets using the
<code>$state</code> mechanism. The <code>*</code> appears after any list of excluded options.
<p>There are also ways of allowing different methods of option handling. If
the option is followed by <code>-</code>, that means the value must be in the same
word as the option, instead of in the next word; if that is allowed, but
the argument could be in the next word instead, the option should be
followed by a `<code>+</code>'. The latter behaviour is very common for commands
which take single letter options. Some commands, particularly many recent
GNU commands, allow you to have the argument in the next word or in the
current word after an `<code>=</code>' sign; you get this by putting an `<code>=</code>'
after the option name. For example,
<pre>
_arguments '-file=:input file:_files'
</pre>
allows you to complete `<code>-file <filename></code>' or `<code>-file=<filename></code>'.
<p>You can handle optional and repeated arguments to options, too. This
illustrates some possibilities:
<pre>
_arguments '-option:first arg:->first::optional arg:->second'
</pre>
The doubled colon indicates that the second argument is optional. In other
words, at that point on the command line <code>_arguments</code> will either try to
complete via the state <code>second</code>, or will try to start another
specification entirely.
<pre>
_arguments '-option:first arg:->first:*:other args:->other'
</pre>
Here, all arguments after the first --- everything else on the command line
--- is taken as an argument to the option, to be completed using the state
<code>other</code>.
<pre>
_arguments '-option:first arg:->first:*-:other args till -:->other'
</pre>
This is similar, but less drastic: there is a pattern after the `<code>*</code>',
here a `<code>-</code>', and when that is encountered, processing of arguments to
`<code>-option</code>' stops. A command using this might be called as follows:
<pre>
cmdname -option <first> <other1> <other2> .... - <remainder>
</pre>
where of course completion for <code><remainder></code> might be handled by other
specifications.
<p>There are yet more possible ways of handling options. I've assumed that
option names can have multiple letters and hence must occur in separate
words. You can specify single-letter options as well, of course, but many
commands allow you to combine these into one word. To tell <code>_arguments</code>
that's OK you should give it the option <code>-s</code>; it needs to come before any
specifications, to avoid getting mixed up with them. After you specify
this, a command argument beginning with a single `<code>-</code>' will be treated by
<code>_arguments</code> as a list of single options, so `<code>-lt</code>' is treated the
same as `<code>-l -t</code>'. However, options beginning with `<code>--</code>' are still
treated as single options, so a `<code>-</code><code>-prefix</code>' on the command line is
still handled as a single long option by <code>_arguments</code>.
<p>One nice feature which can save a lot of trouble when using certain
commands, notably those written by the GNU project and hence installed on
most Linux-based systems, which take an option `<code>-</code><code>-help</code>' that prints out
a list of all options. This is in a human-readable form, but
<code>_arguments</code> is usually able to extract a list of available options which
use the `<code>-</code><code>-...</code>' form, and even in many cases whether they take an
argument, and if so what type that is. It knows because `<code><command>
-</code><code>-help</code>' often prints out a message like `<code>-</code><code>-file=FILE</code>' which would
tell <code>_arguments</code> (1) that `<code>-</code><code>-file</code>' is a possible option (2) that it
takes an argument because of the `<code>=</code>' (3) that that argument should be a
file because of the message `<code>FILE</code>' at the end.
<p>You specify that the command in question works in this way by using the
(fairly memorable) option `<code>-</code><code>-</code>' to `<code>_arguments</code>'. You can then help
it out with completion of option arguments by including a pattern to be
matched in the help test after the `<code>-</code><code>-</code>'; the format is otherwise
similar to a normal specification. For example `<code>*=FILE*:file:_files</code>'
says that any option with `<code>=FILE</code>' in it has the description `<code>file</code>'
and uses the standard <code>_files</code> function for completion, while
`<code>*=DIR*:directory:_files =/</code>' does the same for directories. These two
examples are so common that they are assumed by `<code>_arguments -</code><code>-</code>'.
<p>So for example, here is the completion for <code>gdb</code>, the GNU debugger, which
not surprisingly understands the GNU option format:
<pre>
_arguments -- '*=(CORE|SYM)FILE:core file:_files' \
'*=EXECFILE:executable:_files -g \*\(\*\)' \
'*=TTY:terminal device:compadd /dev/tty\*' && return 0
</pre>
If you run `<code>gdb --help</code>', you'll see where these come from:
`<code>--core=COREFILE</code>', `<code>--exec=EXECFILE</code>' and `<code>--tty=TTY</code>' are all
listed as possible option/argument pairs. Doing it this way neatly
allows the argument completions to work whatever the names of the options
--- though of course it's possible for the rest of the pattern to change,
too, and the commands, being written by lots of different people, are not
necessarily completely consistent in the way their help text is presented.
<p><a name="l68"></a>
<h3>6.8.8: More completion utility functions</h3>
<p>This is now just a ragbag of other functions which might prove useful in
your own completion functions, and which haven't been mentioned before,
with some examples; once again, consult the manual for more detail.
Note that many of these functions can take the most useful arguments to
<code>compadd</code> and pass them on, even where I haven't explicitly said so.
<p><p><strong><code>_funcall</code></strong><br><br>
<p>This is a simple front end to calling a function which may not be defined
and hanging onto the return status of the function. One good use for this
is to call a possibly non-existent function which might have been defined
by the user, before doing some default stuff the user might want to skip.
That would look like this:
<pre>
local ret # returned status from called function, if it was called
_funcall ret _hook_function arg1 arg2 && return ret
# if we get here, _hook_function wasn't called, so do the default stuff.
</pre>
As you can work out, <code>_funcall</code> itself returns status zero if the
function in the second argument got called, and in that case the first
argument is the name of a parameter with the return status from the
function itself. The whole point is that this is safe if
<code>_hook_function</code> doesn't exist.
<p>This function is too low level to know about the tags mechanism; use
<code>_wanted</code> or similar to handle tags properly.
<p><p><strong><code>_compalso</code></strong><br><br>
<p>This is another shorthand: the arguments it takes are a set of short
contexts, in other words either names of commands or special contexts like
`<code>-math-</code>'. The completion for each of these contexts is tried in turn;
<code>_compalso</code> simply handles all the boring looking up of functions and
testing the return values. The definition, if you want to look, is
reassuringly simple. It only has one use at the moment: <code>_subscript</code>,
which handles the <code>-subscript-</code> context we met early in the chapter,
calls `<code>_compalso -math-</code>' to try mathematical completion, since ordinary
array subscripts can contain mathematical expressions.
<p>This is also too low level to handle tags.
<p><p><strong><code>_describe</code></strong><br><br>
<p>Don't confuse this with <code>_description</code> which was explained above and is
the basic function for adding a description to a set of completions of a
certain type. I mentioned in the description of the <code>verbose</code> style that
this function was responsible for showing, or not showing, the descriptions
for a whole lot of options at once. It allows you to do that with several
different sets of completions that may require different options to
<code>compadd</code>. The general form looks something like this:
<pre>
_describe "description of set 1" descs1 compls1 <compadd-opts-1> -- \
"description of set 2" ...
</pre>
where you can have any number of sets separated by the `<code>-</code><code>-</code>'. The
<code>descs1</code> and <code>compls1</code> are arrays of the same length, giving a list of
descriptions and a list of completions, respectively. Alternatively, you
need only give one array name and each element of that will contain a
completion and a description separated by the now-traditional colon. The
`<code><compadd-opts-1></code>' are a set of any old options recognised by
<code>compadd</code>, such as <code>-q</code>, or <code>-S=/</code>, or what have you. I won't give
an example for this, since to find something requiring it would almost need
me to rewrite the completion system from scratch.
<p>Again, you will need to handle tags yourself if you are calling this.
<p><p><strong><code>_combination</code></strong><br><br>
<p>This is the function at the heart of the completions such as
<code>users-hosts</code> described above, where combinations of elements need to be
completed at the same time. It's easiest to describe with an example;
let's pick the <code>users-hosts</code> example, and I'll assume you remember how
that works from the user's point of view, including the format of the
<code>users-hosts</code> style itself. The completion for the username part is
performed as:
<pre>
_combination my-accounts users-hosts users
</pre>
where <code>my-accounts</code> is the tag to be used for the completion, then comes
the style, and then the part of the style to be extracted.
<p>Now suppose we come back into the completion function again to complete the
host later on the command line, so that the username is already there. We
can find that by searching the command line; suppose we store what we find
in <code>$userarg</code>. Then we can complete the hostname as follows:
<pre>
_combination my-accounts users-hosts users=$userarg hosts
</pre>
and the magic part, the fact that we can limit the hostnames to be
completed to only those with a user <code>$userarg</code>, is handled by
<code>_combination</code>. This extends to <code>hosts-ports-users</code> and any larger
combined set in the obvious way: the first field not to contain an `<code>=</code>'
is the one being completed. You don't need to supply other fields if they
are not known; in other words, the field to be completed doesn't need to be
the first one in sequence not known, it can be any, just as long as it
matches part of the style given in the second argument, so you could have
omitted the `<code>users=$userarg</code>' in the last example if you couldn't
extract the right username.
<p>There are various bells and whistles: after the field to be completed you
can add any options to be passed down to <code>compadd</code>; you can give
<code>_combination</code> itself the option `<code>-s <sep></code>' to specify a character
other than colon to separate the parts of the style values; if the style
lookup fails, but there is a corresponding function, which would be called
`<code>_users</code>' or `<code>_hosts</code>' in this example, it is called to generate the matches,
and gets the options at the end which are otherwise destined for
<code>compadd</code>.
<p>As you'll see, this function is at a high enough level to handle the tags
mechanism itself.
<p><p><strong><code>_multi_parts</code></strong><br><br>
<p>This takes two arguments, a separator and a list of matches. The list of
matches is normal, except that each element is likely to contain the
separator. In the most obvious usage, the separator is `<code>/</code>' and the
list of matches is a lot of files with path components. Here's another
reasonable usage:
<pre>
local groups expl
groups=($(awk -F: '{ print $1 }' ~/.newsrc))
_wanted groups expl 'newsgroup' &&
_multi_parts "$expl[@]" . groups
</pre>
The generated array contains names of Usenet newsgroups,
i.e. names with components separated by a `<code>.</code>', and <code>_multi_parts</code>
allows you to complete these piece by piece instead of in one go. This is
a good deal better for use with menu completion, and the list which appears
is smaller too. The <code>_wanted</code> part handles the tags mechanism, which
<code>_multi_parts</code> doesn't.
<p><p><strong><code>_sep_parts</code></strong><br><br>
<p>This also completes a word piece by piece, but unlike <code>_multi_parts</code> the
trial completions are also only supplied for each piece. The arguments are
alternating arrays and separators; arrays are in the usual form, in other
words either the name of an array parameter, or a literal array in
parentheses, quoted to protect it from immediate shell expansion. The
separators are simply strings. For example
<pre>
local expl
array1=(apple banana cucumber)
_wanted breakfast expl 'breakfast' &&
_sep_parts array1 + '(bread toast croissant)' @ '(bowl plate saucer)';
</pre>
completes strings like `<code>apple+toast@plate</code>', piece by piece. This is
currently not used by the distributed completion code.
<p><p><strong><code>_values</code></strong><br><br>
<p>This works a little like <code>_arguments</code>, but is designed for completing the
values of a single argument in a form like `<code>key=val,flag,key=other</code>',
in which you can specify the list separator, here `<code>,</code>' by using the
option <code>-s</code>, e.g. `<code>-s ,</code>'. The first argument to <code>_values</code> is the
overall description of the set of arguments. The other arguments are very
much like those to <code>_arguments</code> except that, as you would expect from the
form given, no pluses or minus signs are involved and each value can only
have one argument, which must follow an `<code>=</code>'. Virtually everything else
is identical, with the exception that the associative array where the
arguments are stored for each value is called <code>$val_args</code>.
<p>I won't bother giving the instructions for <code>_arguments</code> again; instead,
here is an example based on the values used by the <code>-o</code> option to the
<code>mount</code> command:
<pre>
local context state line
typeset -A val_args
_values -s , 'file system options' \
'(rw)ro[mount file system read-only]' \
'(ro)rw[mount file system read-write]' \
'uid[set owner of root]:user ID:' \
'gid[set group of root]:group ID:' \
'bs[specify block size]:block size:(512 1024 2048 4192)'
</pre>
<p>I've just picked out a few of the umpteen possibilities for illustration;
see the function <code>_mount</code> if you want more. Remember that the
`<code>(rw)</code>' before the `<code>ro</code>' means that the options are mutually
exclusive, and the one in parentheses won't be offered if the other appears
on the command line; the strings in square brackets are descriptions of the
particular options; and if there is a colon after the name of the value,
the value takes an argument whose own description comes next. The second
colon is followed by possible completions for that argument, using
the usual convention for actions in <code>_arguments</code>; as you'll see from
the <code>local</code> statement, the <code>$state</code> mechanism can be used here. Only
the `<code>bs</code>' argument here is given possible completions; for <code>uid</code> and
<code>gid</code> you'll have to type in the number without completion; <code>ro</code> and
<code>rw</code> don't take arguments.
<p>Hence a typical(?) list to be completed by this would be
`<code>rw,uid=123,bs=2048</code>'.
<p>Remember also that you can use a `<code>*</code>' before the option name to say that
it can appear more than once in the value list. The <code>_values</code> function
handles the context and tags in a similar way to <code>_arguments</code>.
<p><p><strong><code>_regex_arguments</code></strong><br><br>
<p>This function is for use when the behaviour of a set of command arguments
is so complicated that even <code>_arguments</code> can't help. It allows you to
describe the arguments as a regular expression (i.e. a pattern). I won't
explain it because I haven't yet figured out how it works. If you think
you need to use it, look at the manual entry and then at the <code>_apt</code>
function which is currently its main application.
<p><a name="l69"></a>
<h2>6.9: Finally</h2>
<p>Completion is big and complex: this means that there are probably lots of
bugs around, and things that I haven't described simply enough or which may
be implemented in too complicated a way. Please send the <code>zsh-workers</code>
mailing list any reports or constructive criticism on the subject.
<p>Last of all, remember that the new completion system is ideally just
supposed to work without you needing to worry exactly how. That's a bold
hope, but at least much of the time you should be able to get away with
using just the tab key and ordinary characters.
<p>
<hr>
<ul>
<li> <a href="zshguide07.html">Next chapter</a>
<li> <a href="zshguide05.html">Previous chapter</a>
<li> <a href="zshguide.html">Table of contents</a>
</ul>
<hr>
</body>
</html>
