hyperreal/zsh-manual-mdbook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
18be5de345
zsh-manual-mdbook/zsh_guide/book/zshguide06.html

5009 lines
317 KiB
HTML
Raw Normal View History

Add User Guide
2021-05-17 17:00:52 +02:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Completion, old and new - Zsh User&#x27;s Guide</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<ol class="chapter"><li class="chapter-item expanded affix "><a href="zshguide.html">A User's Guide to the Z-Shell</a></li><li class="chapter-item expanded "><a href="zshguide01.html"><strong aria-hidden="true">1.</strong> A short introduction</a></li><li class="chapter-item expanded "><a href="zshguide02.html"><strong aria-hidden="true">2.</strong> What to put in your startup files</a></li><li class="chapter-item expanded "><a href="zshguide03.html"><strong aria-hidden="true">3.</strong> Dealing with basic shell syntax</a></li><li class="chapter-item expanded "><a href="zshguide04.html"><strong aria-hidden="true">4.</strong> The Z-Shell Line Editor</a></li><li class="chapter-item expanded "><a href="zshguide05.html"><strong aria-hidden="true">5.</strong> Substitutions</a></li><li class="chapter-item expanded "><a href="zshguide06.html" class="active"><strong aria-hidden="true">6.</strong> Completion, old and new</a></li><li class="chapter-item expanded "><a href="zshguide07.html"><strong aria-hidden="true">7.</strong> Modules and other bits and pieces Not written</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Zsh User&#x27;s Guide</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<p><strong>Table of Contents</strong> <em>generated with <a href="https://github.com/thlorenz/doctoc">DocToc</a></em></p>
<ul>
<li><a href="#chapter-6-completion-old-and-new">Chapter 6: Completion, old and new</a>
<ul>
<li><a href="#61-completion-and-expansion">6.1: Completion and expansion</a></li>
<li><a href="#62-configuring-completion-using-shell-options">6.2: Configuring completion using shell options</a>
<ul>
<li><a href="#621-ambiguous-completions">6.2.1: Ambiguous completions</a></li>
<li><a href="#622-always_last_prompt">6.2.2: <code>ALWAYS_LAST_PROMPT</code></a></li>
<li><a href="#623-menu-completion-and-menu-selection">6.2.3: Menu completion and menu selection</a></li>
<li><a href="#624-other-ways-of-changing-completion-behaviour">6.2.4: Other ways of changing completion behaviour</a></li>
<li><a href="#625-changing-the-way-completions-are-displayed">6.2.5: Changing the way completions are displayed</a></li>
</ul>
</li>
<li><a href="#63-getting-started-with-new-completion">6.3: Getting started with new completion</a></li>
<li><a href="#64-how-the-shell-finds-the-right-completions">6.4: How the shell finds the right completions</a>
<ul>
<li><a href="#641-contexts">6.4.1: Contexts</a></li>
<li><a href="#642-tags">6.4.2: Tags</a></li>
</ul>
</li>
<li><a href="#65-configuring-completion-using-styles">6.5: Configuring completion using styles</a>
<ul>
<li><a href="#651-specifying-completers-and-their-options">6.5.1: Specifying completers and their options</a></li>
<li><a href="#652-changing-the-format-of-listings-groups-etc">6.5.2: Changing the format of listings: groups etc.</a></li>
<li><a href="#653-styles-affecting-particular-completions">6.5.3: Styles affecting particular completions</a></li>
</ul>
</li>
<li><a href="#66-command-widgets">6.6: Command widgets</a>
<ul>
<li><a href="#661-_complete_help">6.6.1: <code>_complete_help</code></a></li>
<li><a href="#662-_correct_word-_correct_filename-_expand_word">6.6.2: <code>_correct_word</code>, <code>_correct_filename</code>, <code>_expand_word</code></a></li>
<li><a href="#663-_history_complete_word">6.6.3: <code>_history_complete_word</code></a></li>
<li><a href="#664-_most_recent_file">6.6.4: <code>_most_recent_file</code></a></li>
<li><a href="#665-_next_tags">6.6.5: <code>_next_tags</code></a></li>
<li><a href="#666-_bash_completions">6.6.6: <code>_bash_completions</code></a></li>
<li><a href="#667-_read_comp">6.6.7: <code>_read_comp</code></a></li>
<li><a href="#668-_generic">6.6.8: <code>_generic</code></a></li>
<li><a href="#669-predict-on-incremental-complete-word">6.6.9: <code>predict-on</code>, <code>incremental-complete-word</code></a></li>
</ul>
</li>
<li><a href="#67-matching-control-and-controlling-where-things-are-inserted">6.7: Matching control and controlling where things are inserted</a>
<ul>
<li><a href="#671-case-insensitive-matching">6.7.1: Case-insensitive matching</a></li>
<li><a href="#672-matching-option-names">6.7.2: Matching option names</a></li>
<li><a href="#673-partial-word-completion">6.7.3: Partial word completion</a></li>
<li><a href="#674-substring-completion">6.7.4: Substring completion</a></li>
<li><a href="#675-partial-words-with-capitals">6.7.5: Partial words with capitals</a></li>
<li><a href="#676-final-notes">6.7.6: Final notes</a></li>
</ul>
</li>
<li><a href="#68-tutorial">6.8: Tutorial</a>
<ul>
<li><a href="#681-the-dispatcher">6.8.1: The dispatcher</a></li>
<li><a href="#682-subcommand-completion-_arguments">6.8.2: Subcommand completion: <code>_arguments</code></a></li>
<li><a href="#683-completing-particular-argument-types">6.8.3: Completing particular argument types</a></li>
<li><a href="#684-the-rest">6.8.4: The rest</a></li>
</ul>
</li>
<li><a href="#69-writing-new-completion-functions-and-widgets">6.9: Writing new completion functions and widgets</a>
<ul>
<li><a href="#691-loading-completion-functions-compdef">6.9.1: Loading completion functions: <code>compdef</code></a></li>
<li><a href="#692-adding-a-set-of-completions-compadd">6.9.2: Adding a set of completions: <code>compadd</code></a></li>
<li><a href="#693-functions-for-generating-filenames-etc">6.9.3: Functions for generating filenames, etc.</a></li>
<li><a href="#694-the-zshparameter-module">6.9.4: The <code>zsh/parameter</code> module</a></li>
<li><a href="#695-special-completion-parameters-and-compset">6.9.5: Special completion parameters and <code>compset</code></a></li>
<li><a href="#696-fancier-completion-using-the-tags-and-styles-mechanism">6.9.6: Fancier completion: using the tags and styles mechanism</a></li>
<li><a href="#697-getting-the-work-done-for-you-handling-arguments-etc">6.9.7: Getting the work done for you: handling arguments etc.</a></li>
<li><a href="#698-more-completion-utility-functions">6.9.8: More completion utility functions</a></li>
</ul>
</li>
<li><a href="#610-finally">6.10: Finally</a></li>
</ul>
</li>
</ul>
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<p><span id="comp"></span><span id="l144"></span></p>
<h1 id="chapter-6-completion-old-and-new"><a class="header" href="#chapter-6-completion-old-and-new">Chapter 6: Completion, old and new</a></h1>
<p>Completion of command arguments is something zsh is particularly good
at. The simplest case is that you hit <code>&lt;TAB&gt;</code>, and the shell guesses
what has to go there and fills it in for you:</p>
<pre><code> % ls
myfile theirfile yourfile
% cat t&lt;TAB&gt;
</code></pre>
<p>expands the command line to</p>
<pre><code> % cat theirfile
</code></pre>
<p>and you only had to type the initial letter, then <code>TAB</code>.</p>
<p>In the early days when this feature 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. You could also list
possible completions; for some reason this became attached to the <code>^D</code>
key in csh, which in later shells with Emacs-like bindings also deletes
the next character, so that history has endowed zsh, like other shells,
with the slightly odd combined behaviour:</p>
<pre><code> % cat yx
</code></pre>
<p>Now move the cursor back one character onto the x and hit ^D twice and
you see: <code>yourfile</code>. That doesn't work if you use vi-like bindings, or,
obviously, if you've rebound <code>^D</code>.</p>
<p>Next, it became possible to complete other items such as names of users,
commands or hosts. Then zsh weighed in with menu completion, so you
could keep on blindly hitting <code>&lt;TAB&gt;</code> until the right answer appeared,
and never had to type an extra character yourself.</p>
<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>
<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>, from an
initialization file, after which zsh knows, for example, that <code>gunzip</code>
should be followed by files ending in <code>.gz</code>. The new system 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>
<p>I shall concentrate on the new completion system, which seems destined
to take over completely from the old one eventually, now that the 3.1
release series has become the 4.0 production release. 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>
<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>&lt;TAB&gt;</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:</p>
<pre><code> # 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
}
</code></pre>
<p>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>
<p>Here's a plan for the sections of this chapter.</p>
<ol>
<li>A broad description of completion and expansion, applying equally to
old and new completion.</li>
<li>How to configure completion using shell options. Most of this
section applies to old completion, too, although I won't explicitly
flag up any differences. After this, I shall leave the <code>compctl</code>
world behind.</li>
<li>How to start up new completion.</li>
<li>The basics of how the new completion system works.</li>
<li>How to configure it using the new `<code>zstyle</code>' builtin.</li>
<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>
<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>
<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>
<li>Ends the chapter gracefully, on the old `beginning, middle, end'
principle.</li>
</ol>
<p><span id="l145"></span></p>
<h2 id="61-completion-and-expansion"><a class="header" href="#61-completion-and-expansion">6.1: Completion and expansion</a></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. 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:</p>
<pre><code> % echo $PWD&lt;TAB&gt;
-&gt; echo /home/pws/zsh/projects/zshguide
% echo `print $ZSH_VERSION`&lt;TAB&gt;
-&gt; echo 3.1.7
% echo !!&lt;TAB&gt;
-&gt; echo echo 3.1.7
% echo ~/.z*&lt;TAB&gt;
-&gt; echo /home/pws/.zcompdump /home/pws/.zlogout
/home/pws/.zshenv /home/pws/.zshrc
</code></pre>
<p>Note that the `<code>~</code>' also gets expanded in this case.</p>
<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>
<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>
<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>&lt;TAB&gt;</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>&lt;TAB&gt;</code>) if you are happy to use the separate commands for expansion,
i.e.</p>
<pre><code> # Now tab does only completion, not expansion
bindkey '^i' complete-word
</code></pre>
<p>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>
<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:</p>
<pre><code> % ls
filename1
% ls filex
</code></pre>
<p>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</p>
<pre><code> bindkey '^i' expand-or-complete-prefix
</code></pre>
<p>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>
<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>&lt;TAB&gt;</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 (<a href="zshguide04.html#zle">chapter
4</a>), you can make up a function which tries
<code>list-expand</code>, and if that fails tries <code>list-options</code>.</p>
<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>
<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. If you use the style, zsh should be able
to load this automatically when needed, as long as you have dynamic
loading, which you probably do these days. <span id="l146"></span></p>
<h2 id="62-configuring-completion-using-shell-options"><a class="header" href="#62-configuring-completion-using-shell-options">6.2: Configuring completion using shell options</a></h2>
<p>There are two main ways of altering the behaviour of completion without
writing or rewriting shell functions: shell options, as introduced in
<a href="zshguide02.html#init">chapter 2</a>, 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>
<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>
<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 commands for particular completions bound separately to keystrokes)
is the function <code>_main_complete</code>, which includes the effect of the
following lines to make sure that at least the basic options are set up
within completion functions:</p>
<pre><code> setopt glob bareglobqual nullglob rcexpandparam extendedglob unset
unsetopt markdirs globsubst shwordsplit shglob ksharrays cshnullglob
unsetopt allexport aliases errexit octalzeroes
</code></pre>
<p>but that by no means exhausts the possibilities. Actually, it doesn't
include those lines: the options to set are stored in the array
<code>$_comp_options</code>, with <code>NO_</code> in front if they are to be turned off. You
can modify this if you find you need to (and maybe tell the maintainers,
too).</p>
<p>By the way, if you are wondering whether you can re-use the function
<code>_main_complete</code>, by binding it to a different key with slightly
different completion definitions, look instead at the description of the
<code>_generic</code> command widget below. It's just a front-end to
<code>_main_complete</code> which allows you to have a different set of styles in
effect.</p>
<p><span id="l147"></span></p>
<h3 id="621-ambiguous-completions"><a class="header" href="#621-ambiguous-completions">6.2.1: Ambiguous completions</a></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:</p>
<ul>
<li>with <code>NO_BEEP</code> set, that annoying beep goes away,</li>
<li>with <code>NO_LIST_BEEP</code>, beeping is only turned off for ambiguous
completions,</li>
<li>with <code>AUTO_LIST</code> set, when the completion is ambiguous you get a
list without having to type <code>^D</code>,</li>
<li>with <code>BASH_AUTO_LIST</code> set, the list only happens the second time you
hit tab on an ambiguous completion,</li>
<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>
<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>
<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>
<li>with <code>AUTO_MENU</code>, you only get the menu behaviour when you hit TAB
again on the ambiguous completion.</li>
</ul>
<p><span id="l148"></span></p>
<h3 id="622-always_last_prompt"><a class="header" href="#622-always_last_prompt">6.2.2: <code>ALWAYS_LAST_PROMPT</code></a></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>
<p>When you're writing your own editor functions which invoke completion,
you can actually cancel the effect of this with the widget
<code>end-of-list</code>, which you would call as <code>zle end-of-list</code> (it's a normal
editing function, not a completion function). You can also bind it to a
key to use to preserve the existing completion list. On the other hand,
if you want to control the behaviour within a completion function, i.e.
to decide whether completion will try to return to the prompt above the
list, you can manipulate it with the <code>last_prompt</code> element of the
<code>$compstate</code> associative array, so for example:</p>
<pre><code> compstate[last_prompt]=''
</code></pre>
<p>will turn off the behaviour for the completion in progress. <code>$compstate</code>
is the place to turn if you find yourself wanting to control completion
behaviour in this much detail; see the <code>zshcompwid</code> manual page.</p>
<p><span id="l149"></span></p>
<h3 id="623-menu-completion-and-menu-selection"><a class="header" href="#623-menu-completion-and-menu-selection">6.2.3: Menu completion and menu selection</a></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>
<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'. This allows you to
move the cursor around the list of completions to select one. 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>, although
it should be loaded automatically when the style <code>menu</code> is set as below.
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. However, menu selection does still work, by
allowing you to scroll the list up and down. 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>
<p>Now you should set the following style:</p>
<pre><code> zstyle ':completion:*' menu select=&lt;NUM&gt;
</code></pre>
<p>If an ambiguous completion produces at least <code>&lt;NUM&gt;</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 cursor 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. Hitting <code>^G</code> (the editor function <code>send-break</code>) aborts
menu selection, removes the list and restores the command line.</p>
<p>Internally, zsh actually uses the parameter <code>$MENUSELECT</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>$MENUSELECT</code> directly (unless you are using <code>compctl</code>, which will
happily use menu selection). 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>
<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</p>
<pre><code> bindkey -M menuselect '^o' accept-and-infer-next-history
</code></pre>
<p>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>
<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>
<p><span id="l150"></span></p>
<h3 id="624-other-ways-of-changing-completion-behaviour"><a class="header" href="#624-other-ways-of-changing-completion-behaviour">6.2.4: Other ways of changing completion behaviour</a></h3>
<p><strong><code>COMPLETE_ALIASES</code></strong></p>
<p>If you set an alias such as</p>
<pre><code> alias pu=pushd
</code></pre>
<p>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=&quot;myzcat -dc&quot;</code>'
will work with the option set, even if you haven't told the system about
`<code>myzcat</code>', while `<code>alias myzcat=&quot;gzip -dc&quot;</code>' will not work unless you
do define a completion for myzcat: here `<code>compdef _gzip myzcat</code>' would
probably be good enough. Without the option set, it would be the other
way around: the first alias would not work without the extra <code>compdef</code>,
but the second would.</p>
<p><strong><code>AUTO_REMOVE_SLASH</code></strong></p>
<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:</p>
<pre><code> % rmdir my&lt;TAB&gt;
-&gt; rmdir mydir/
% rmdir mydir/&lt;RETURN&gt;
-&gt; `rmdir mydir' executed
</code></pre>
<p>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>
<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 is
unique when in fact it isn't.</p>
<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&lt;TAB&gt;</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></p>
<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>
<p>The behaviour for <code>AUTO_PARAM_KEYS</code> is a bit more complicated. Try this:</p>
<pre><code> print ${ZSH_V&lt;TAB&gt;
</code></pre>
<p>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></p>
<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><code>ALWAYS_TO_END</code></strong></p>
<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>
<p><span id="l151"></span></p>
<h3 id="625-changing-the-way-completions-are-displayed"><a class="header" href="#625-changing-the-way-completions-are-displayed">6.2.5: Changing the way completions are displayed</a></h3>
<p><strong><code>LIST_TYPES</code></strong></p>
<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>
<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></p>
<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 formatting them 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>
<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>
<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>
<p><span id="l152"></span></p>
<h2 id="63-getting-started-with-new-completion"><a class="header" href="#63-getting-started-with-new-completion">6.3: Getting started with new completion</a></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>
<p>If you want to load completion, try this at the command line:</p>
<pre><code> autoload -U compinit
compinit
</code></pre>
<p>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>AIX</code>, <code>BSD</code>, <code>Base</code>, <code>Debian</code>, <code>Redhat</code>,
<code>Unix</code>, <code>X</code> and <code>Zsh</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>
<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>
<p>Another example on the theme of `it just works':</p>
<pre><code> tar xzf archive.tar.gz ^D
</code></pre>
<p>will look inside the gzipped tar archive --- assuming the GNU version of
<code>tar</code>, for which the `<code>z</code>' in the first set of arguments reports that
the archive has been compressed with gzip --- and give you a list of
files or directories you can extract. This is done in a very similar way
to normal file completion; although there are differences, you can do
completion down to any directory depth within the archive. (At this
point, you're supposed to be impressed.)</p>
<p>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 called <code>$_comps</code> which stores the names of
commands as keys and the names of completion functions as the
corresponding values. Try typing:</p>
<pre><code> print ${_comps[
</code></pre>
<p>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>
<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>
<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>
<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>:</p>
<pre><code> zstyle ':completion:*' use-compctl false
</code></pre>
<p>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>
<p><span id="l153"></span></p>
<h2 id="64-how-the-shell-finds-the-right-completions"><a class="header" href="#64-how-the-shell-finds-the-right-completions">6.4: How the shell finds the right completions</a></h2>
<p><span id="l154"></span></p>
<h3 id="641-contexts"><a class="header" href="#641-contexts">6.4.1: Contexts</a></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 system evolved gradually, but everything I say applies
to all versions of zsh with the major version 4.</p>
<p>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,</p>
<pre><code> :completion::complete:-subscript-::
</code></pre>
<p>plus a list of so-called `tags' and completion functions, which I'll
talk about later. The full form is:</p>
<pre><code> :completion:&lt;func&gt;:&lt;completer&gt;:&lt;command&gt;:&lt;argument&gt;:&lt;tag&gt;
</code></pre>
<p>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.</p>
<ul>
<li><em><strong>&lt;func&gt;</strong></em><br />
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.</li>
<li><em><strong>&lt;completer&gt;</strong></em><br />
is called `<code>complete</code>' in this case: this refers to the fact that
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.</li>
<li><em><strong>&lt;command&gt;</strong></em><br />
is the name of a command or other similar context as described
above, here `<code>-subscript-</code>'.</li>
<li><em><strong>&lt;argument&gt;</strong></em><br />
is most useful when <code>&lt;command&gt;</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 simpler 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.</li>
<li><em><strong>&lt;tag&gt;</strong></em><br />
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.</li>
</ul>
<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>
<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,</p>
<pre><code> :completion::complete:cvs:argument-rest:
:completion::complete:cvs-add:argument-rest:
</code></pre>
<p>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>
<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>
<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:option-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>
<p><span id="l155"></span></p>
<h3 id="642-tags"><a class="header" href="#642-tags">6.4.2: Tags</a></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:</p>
<pre><code> tags in context :completion::complete:cd::
local-directories path-directories (_alternative _cd)
</code></pre>
<p>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>
<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. Some
standard completion functions have been filtered out of this list --- it
wouldn't help you to know it had been through <code>_main_complete</code> and
<code>_complete</code>, for example.</p>
<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, joining together the arguments you gave it
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>
<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 define a style, this argument is actually a
pattern which will be matched against the current context to see if the
style 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:</p>
<pre><code> zstyle ':completion:*:cd:*' tag-order local-directories \
path-directories
</code></pre>
<p>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>
<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,</p>
<pre><code> % 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/
</code></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>&quot;local-directories path-directories&quot;</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>
<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.:</p>
<pre><code> Completing external command
tex texhash texi2pdf text2sf
texconfig texi2dvi texindex textmode
texdoc texi2dvi4a2ps texlinks texutil
texexec texi2html texshow texview
Completing parameter
TEXINPUTS texinputs
</code></pre>
<p>(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</p>
<pre><code> zstyle ':completion:*:-command-:*' tag-order '!parameters'
</code></pre>
<p>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>
<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.
Furthermore, tags can actually be patterns, or more precisely any word
in one of the arguments to <code>tag-order</code> may contain a pattern, which will
then be tried against all the valid tags to see if it matches. It's
sometimes even useful to use `<code>*</code>' to match all tags, if you are
specifying a special form of one of the tags --- maybe using a label, as
described next --- in the same word. See the manual for all the tag
names understood by the supplied functions.</p>
<p>The <code>tag-order</code> style allows you to give tags `labels', which are a
sort of alias, instructing the completion system to use a tag under a
different name. You arrange this by giving the tag followed by a colon,
followed by the label. The label can also have a hyphen in front, which
means that the original tag name should be put in front when the label
is looked up; this is really just a way of making the names look neater.
The upshot is that by using contexts with the label name in, rather than
the tag name, you can arrange for special behaviour. Furthermore, you
can give an alternative description for the labelled tag; these show up
with the <code>format</code> style which I'll describe below (and which I
personally find very useful). You put the description after another
colon, with any spaces quoted. It would look like this:</p>
<pre><code> zstyle ':completion:*:aliens:*' tag-order \
'frooble:-funny:funny\ frooble' frooble
</code></pre>
<p>which is used when you're completing for the command <code>aliens</code>, which
presumably has completions tagged as `<code>frooble</code>' (if not, you're very
weird). Then completion will first look up styles for that tag under the
name <code>frooble-funny</code>, and if it finds completions using those styles it
will list them with a description (if you are using <code>format</code>) of `funny
frooble'. Otherwise, it will look up the styles for the tag under its
usual name and try completion again. It's presumably obvious that if you
don't have different styles for the two labels of the tag, you get the
same completions each time.</p>
<p>Rather than overload you with information on tags by giving examples of
how to use tag labels now, I'll reserve this for the description of the
<code>ignored-patterns</code> style below, which is one neat use for labels. In
fact, it's the one for which it was invented; there are probably lots of
other ones we haven't thought of yet.</p>
<p>One important note about <code>tag-order</code> which I may not have made as
explicit as I should have: <em>it doesn't change which tags are actually
valid in that completion</em>. Just putting a tag name into the list 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>
<p>Note that the rule for testing patterns means that you can always
specify a catch-all worst case by `<code>zstyle &quot;*&quot; 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>
<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>
<p><span id="l156"></span></p>
<h2 id="65-configuring-completion-using-styles"><a class="header" href="#65-configuring-completion-using-styles">6.5: Configuring completion using styles</a></h2>
<p>You now know how to define a style for a particular context, using</p>
<pre><code> zstyle &lt;context&gt; &lt;style&gt; &lt;value...&gt;
</code></pre>
<p>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>
<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>
<p>The most powerful way of using <code>zstyle</code> is with the option <code>-e</code>. This
says that the words you supply are to be evaluated as if as arguments to
<code>eval</code>. This should set the array <code>$reply</code> to the words to be used. So</p>
<pre><code> zstyle '*' days 'Monday Tuesday'
</code></pre>
<p>and</p>
<pre><code> zstyle -e '*' days 'reply=(Monday Tuesday)'
</code></pre>
<p>are equivalent --- but the intention, of course, is that in the second
case the argument can return a different value each time so that the
style can vary. It will usually be evaluated in the heat of completion,
hence picking up all the editing parameters; so for example</p>
<pre><code> zstyle -e ':completion:*' mystyles 'reply=(${NUMERIC:-0})'
</code></pre>
<p>will make the style return a non-zero integer (possibly indicating
<code>true</code>) if you entered a non-zero prefix argument to the command, as
described in <a href="zshguide04.html#zle">chapter 4</a>. However, the argument can
contain any zsh code whatsoever, not just a simple assignment. Remember
to quote it to prevent it from being turned into something else when the
<code>zstyle</code> command line is run.</p>
<p>Finally, you can delete a context for a style or a list of styles by</p>
<pre><code> zstyle -d [ &lt;context-pattern&gt; [ &lt;style&gt; ] ] ...
</code></pre>
<p>--- 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>
<p>By the way, I did mention in passing in <a href="zshguide04.html#zle">chapter 4</a>
that you could use styles in just the same way in ordinary zle widgets
(the ones created with `<code>zle -N</code>'), but you probably forgot about that
straight away. All the instructions about defining styles and using them
in your own functions from this chapter apply to zle functions. The only
difference is that in that case the convention for contexts is that the
context is set to `<code>:zle:</code><em>widget-name</em>' for executing the widget
<em>widget-name</em>.</p>
<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>
<p><span id="l157"></span></p>
<h3 id="651-specifying-completers-and-their-options"><a class="header" href="#651-specifying-completers-and-their-options">6.5.1: Specifying completers and their options</a></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,</p>
<pre><code> zstyle ':completion:*' completer _complete _correct _approximate
</code></pre>
<p>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.</p>
<p>There's a labelling feature for completers, rather like the one for tags
described, but not illustrated in detail, above. You can put a completer
in a list like this:</p>
<pre><code> zstyle ':completion:*' completer ... _complete:comp-label ...
</code></pre>
<p>which calls the completer <code>_complete</code>, but pretends its name is
<code>comp-label</code> when looking things up in styles, so you can try completers
more than once with different features enabled. As with tags, you can
write it like `<code>_complete:-label</code>', and the normal name will be
prepended to get the name `<code>complete-label</code>' --- just a shortcut, it
doesn't introduce anything new. I'll defer an example until you know
what the completers do.</p>
<p>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></p>
<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></p>
<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>
<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:</p>
<pre><code> % zstyle ':completion:*' max-errors 2
# just for the sake of example...
% zstyle ':completion:*' completer _approximate
% ls
ashes sackcloth
% echo siccl&lt;TAB&gt;
-&gt; echo sackcloth
% echo zicc&lt;TAB&gt;
&lt;Beep.&gt;
</code></pre>
<p>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>
<p>There's another way to give a maximum number of errors, using the
numeric prefix specified with <code>ESC-&lt;digit&gt;</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.</p>
<pre><code> zstyle ':completion:*:approximate:*' max-errors 2 numeric
</code></pre>
<p>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:</p>
<pre><code> % echo zicc&lt;ESC-3&gt;&lt;TAB&gt;
-&gt; echo sackcloth
</code></pre>
<p>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>
<p>Note that the context is examined straightaway in the completer, so at
this stage it is simply `<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>
<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>
<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>
<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>
<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></p>
<p>This is very similar to <code>_approximate</code>, except that the context is
`<code>:completion::correct:*</code>' (or `<code>:completion::correct-&lt;num&gt;:*</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>
<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>
<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></p>
<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>
<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:</p>
<ul>
<li><strong><code>glob</code></strong><br />
expands glob expressions, in other words does filename generation
using wildcards.</li>
<li><strong><code>substitute</code></strong><br />
expands expressions including and active `<code>$</code>' or backquotes.</li>
</ul>
<p>But remember that you need</p>
<pre><code> bindkey '^i' complete-word
</code></pre>
<p>when using this completer as otherwise the built-in expansion mechanism
which is run by the normal binding <code>expand-or-complete</code> will take over.</p>
<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,</p>
<pre><code> zstyle ':completion:*' completer _expand _complete
zstyle ':completion::expand:*' tag-order expansions
</code></pre>
<p>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>
<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>
<p>There is a slight problem when you try just to generate <code>glob</code>
expansions, without <code>substitute</code>. In fact, it doesn't take much thought
to see that an expression like `<code>$PWD/*.c</code>' doesn't mean anything if
<code>substitute</code> is inactive; it must be active to make sense of such
expressions. However, this is annoying if there are no matches: you end
up being offered a completion with the expanded <code>$PWD</code>, but `<code>*.c</code>'
still tacked on the end, which isn't what you want. If you use <code>_expand</code>
mainly for globbing, you might therefore want to set the style
<code>subst-globs-only</code> to true: if a completion just expands the parameters,
and globbing does nothing, then the expansion is rejected and the line
left untouched.</p>
<p>The <code>_expand</code> completer will also use the styles</p>
<ul>
<li><strong><code>accept-exact</code></strong><br />
applies to words beginning with a `<code>$</code>' or `<code>~</code>'. Suppose there is
a parameter `<code>$foo</code>' and a parameter `<code>$foobar</code>' and you have
`<code>$foo</code>' on the line. Normally the completion system will perform
completion at this point. However, with <code>accept-exact</code> set,
`<code>$foo</code>' will be expanded since it matches a parameter.</li>
<li><strong><code>add-space</code></strong><br />
means add a space after the expansion, as with a successful
completion --- although directories are given a `<code>/</code>' instead. For
finer control, it can be set to the word <code>file</code>, which means the
space is only added if the expanded word matches a file that already
exists (the idea being that, if it doesn't, you may want to complete
further). Both <code>true</code> and <code>file</code> may be combined with <code>subst</code>, which
prevents the adding of a space after expanding a substitution of the
form `<code>${...}</code>' or `<code>$(...)</code>'.</li>
<li><strong><code>keep_prefix</code></strong><br />
also addresses the question of whether a `<code>~</code>' or `<code>$</code>' should be
expanded. If set, the prefix will be retained, so expanding
`<code>~/f*</code>' to `<code>~/foo</code>' doesn't turn the `<code>~</code>' into `<code>/home/pws</code>'.
The default is the value `<code>changed</code>', which is a half-way house
been <code>false</code> and <code>true</code>: it means that if there was no other change
in the word, i.e. no other possible expansion was found, the `<code>~</code>'
or `<code>$</code>' will be expanded. If the effect of this style is that the
expansion is the same as the unexpanded word, the next completer in
the list after <code>_expand</code> will be tried.</li>
<li><strong><code>suffix</code></strong><br />
is similar to <code>keep_prefix</code>. The `suffix' referred to is something
after an expression beginning `<code>~</code>' or `<code>$</code>' that wouldn't be part
of that expansion. If this style is set, and such a suffix exists,
the expansion is not performed. So, for example, `<code>~pw&lt;TAB&gt;</code>' can
be expanded to `<code>~pws</code>', but `<code>~pw/</code>' is not eligible for
expansion; likewise `<code>$fo</code>' and `<code>$fo/</code>'. This style defaults to
<code>true</code> --- so if you want <code>_expand</code> always to expand such
expressions, you will need to set it to <code>false</code> yourself.</li>
</ul>
<p>An easier way of getting the sort of control over expansion which the
<code>_expand</code> completer provides 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>Setting different priorities for expansion is one good use for completer
labels, for example</p>
<pre><code> zstyle ':completion:*' completer _expand:-glob _expand:-subst
zstyle ':completion:*:expand-glob:*' glob yes
zstyle ':completion:*:expand-subst:*' substitute yes
</code></pre>
<p>is the basic set up to make <code>_expand</code> try glob completions and failing
that do substitutions, presenting the results as an expansion. You would
almost certainly want to add details to help this along.</p>
<p><strong><code>_history</code></strong></p>
<p>This completes words from the shell's history, in other words everything
you typed or had completed or expanded on previous lines. There are
three styles that affect it, <code>sort</code> and <code>remove-all-dups</code>; they are
described for the command widget <code>_history_complete_word</code> below. That
widget essentially performs the work of this completer as a special
keystroke.</p>
<p><strong><code>_prefix</code></strong></p>
<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>
<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>&lt;prefix&gt;&lt;completion&gt;&lt;suffix&gt;</code>' where the completion has changed
`<code>&lt;prefix&gt;</code>' to `<code>&lt;prefix&gt;&lt;completion&gt;</code>', ignoring <code>&lt;suffix&gt;</code>
throughout.</p>
<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>_complete _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>,
<code>_history</code>) is used.</p>
<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>
<p>The <code>_prefix</code> completer will re-look up the <code>completer</code> style. This
means 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:</p>
<pre><code> zstyle ':completion:::::' completer _complete \
&lt;other-completers&gt; _prefix
zstyle ':completion::prefix:::' completer _complete
</code></pre>
<p>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</code> context, however, or no completion at
all will be done.</p>
<p>The completer labelling trick is again useful here: you can call
<code>_prefix</code> more than once, wherever you choose in your list of
completers, and force it to look up in a different context each time.</p>
<pre><code> zstyle ':completion:*' completer _complete _prefix:-complete \
_approximate _prefix:-approximate
zstyle ':completion:*:prefix-complete:*' completer _complete
zstyle ':completion:*:prefix-approximate:*' completer _approximate
</code></pre>
<p>This tries ordinary completion, then the same for the prefix only, then
approximation, then the same for the prefix only. As mentioned in the
previous paragraph, it is perfectly legitimate to leave out the raw
<code>_complete</code> and <code>_approximate</code> completers and just use the forms with
the <code>_prefix</code> prefix.</p>
<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>&lt;TAB&gt;</code> in the middle of
<code>&lt;prefix&gt;&lt;suffix&gt;</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>
<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>_ignored</code></strong></p>
<p>Like <code>_prefix</code> this is a bit of a hybrid, mopping up after completions
which have already been generated. It allows you to have completions
which have already been rejected by the style `<code>ignored-patterns</code>'.
I'll describe that below, but it's effect is very simple: for the
context given, the list of patterns you specify are matched against
possible completions, and any that match are removed from the list. The
<code>_ignored</code> completer allows you to retrieve those removed completions
later in your completer list, in case nothing else matched.</p>
<p>This is used by the <code>$fignore</code> mechanism --- a list of suffixes of files
not normally to be completed --- which is actually built on top of
<code>ignored-patterns</code>, so if you use that in the way familiar to current
zsh users, where the ignored matches are shown if there are no unignored
matches, you need the <code>_ignored</code> completer in your completer list.</p>
<p>One slightly annoying feature with <code>_ignored</code> is if there is only a
single possible completion, since it will then be unconditionally
inserted. Hardly a surprise, but it can be annoying if you really don't
want that choice. There is a style <code>single-ignored</code> which you can set to
<code>show</code> --- just show the single ignored match, don't insert it --- or to
<code>menu</code> --- go to menu completion so that TAB cycles you between the
completion which <code>_ignored</code> produced and what you originally typed. The
latter gives a very natural way of handling ignored files; it's sort of
saying `well, I found this but you might not like it, so hit tab again
if you want to go back to what you had before'.</p>
<p>I said this was like <code>_prefix</code>, and indeed you can specify which
completers are called for the <code>_ignored</code> completer in just the same way,
by giving the <code>completer</code> style in the context
`<code>:completion:*:ignored:*</code>'. That means my description has been a
little over-simplified: <code>_ignored</code> doesn't really use the completions
which were ignored before; rather, when it's called it generates a list
of possibilities where the choices matched by <code>ignore-patterns</code> --- or
internally using <code>$fignore</code> --- are not ignored. So it should really be
called `<code>_not_ignored</code>', but it isn't.</p>
<p><strong><code>_match</code></strong></p>
<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>
<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>
<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&lt;TAB&gt;</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,</p>
<pre><code> zstyle ':completion::match:*' original only
</code></pre>
<p>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>
<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>_all_matches</code></strong></p>
<p>This has a similar effect to performing expansion instead of completion:
all the possible completions are inserted onto the command line.
However, it uses the results of ordinary contextual completion to
achieve this. The normal way that the completion system achieves this is
by influencing the behaviour of any subsequent completers which are
called --- hence you will need to put <code>_all_matches</code> in the list of
completers before any which you would like to have this behaviour.</p>
<p>You're unlikely to want to do this with every type of completion, so
there are two ways of limiting its effect. First, there is the
<code>avoid-completer</code> style: you can set this to a list of completers which
should <em>not</em> insert all matches, and they will be handled normally.</p>
<p>Then there is the style <code>old-matches</code>. This forces <code>_all_matches</code> to use
an existing list of matches, if it exists, rather than what would be
generated this time round. You can set the style to <code>only</code> instead of
true; in this case <code>_all_matches</code> will never apply to the completions
which would be generated this time round, it will only use whatever list
of completions already exists.</p>
<p>This can be a nuisance if applied to normal completion generation ---
the usual list would never be generated, since <code>_all_matches</code> would just
insert the non-existent list from last time --- so the manual recommends
two other ways of using the completer with this style. First, you can
add a condition to the use of the style:</p>
<pre><code> zstyle -e ':completion:*' old-matches 'reply=(${NUMERIC:-false})'
</code></pre>
<p>This returns false unless there is a non-zero numeric argument; if you
type <code>&lt;ESC&gt;1</code> in emacs mode, or just <code>1</code> in vi mode, before completion,
it will insert all the values generated by the immediately preceding
completion.</p>
<p>Otherwise, you can bind <code>_all_matches</code> separately. This is probably the
more useful; copying the manual entry:</p>
<pre><code> zle -C all-matches complete-word _generic
bindkey '^Xa' all-matches
zstyle ':completion:all-matches:*' completer _all_matches
zstyle ':completion:all-matches:*' old-matches only
</code></pre>
<p>Here we generate ourselves a new completion based on the <code>complete-word</code>
widget, called <code>all-matches</code> --- this name is arbitrary but convenient.
We bind that to the keystroke <code>^Xa</code>, and give it two special styles
which normal completion won't see. For the <code>completer</code> we set just
<code>_all_matches</code>, and for <code>old-matches</code> we set <code>only</code>; the effect is that
<code>^Xa</code> will only ever have the effect of inserting all the completions
which were generated by the last completion, whatever that was --- it
does not have to be an ordinary contextual completion, it may be the
result of any completion widget.</p>
<p><strong><code>_list</code></strong></p>
<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>
<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 must be set to one of
the values corresponding to `true' for the <code>_list</code> delaying behaviour
to take effect. You can test for a particular value of <code>$NUMERIC</code> or any
other condition by using the <code>-e</code> option of <code>zstyle</code> when defining the
style.</p>
<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></p>
<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></p>
<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>
<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&lt;ESC-/&gt;</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>
<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>
<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></p>
<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; just miss out any completers you don't want to use:</p>
<pre><code> _all_matches _list _oldlist _menu _expand _complete _match
_ignored _correct _approximate _prefix
</code></pre>
<p>Other orders are certainly possible and maybe even useful: for example,
the <code>_all_matches</code> completer applies to all the completers following not
listed in the <code>avoid-completer</code> style, so you might have good reason to
shift it further down the list.</p>
<p>Here's my example of labels for completers, which I mentioned just above
the list of different completers, whereby completers can be looked up
under different names.</p>
<pre><code> zstyle ':completion:*' completer _complete _approximate:-one \
_complete:-extended _approximate:-four
zstyle ':completion:*:approximate-one:*' max-errors 1
zstyle ':completion:*:complete-extended:*' \
matcher 'r:|[.,_-]=* r:|=*'
zstyle ':completion:*:approximate-four:*' max-errors 4
</code></pre>
<p>This tries the following in order.</p>
<ol>
<li>Ordinary, no-frills completion.</li>
<li>Approximation with one error, as given by the second style.</li>
<li>Ordinary completion with extended completion turned on, as given by
the third style. Sorry, this will be a black box until I talk about
the <code>matcher</code> style later on; for now, you'll just have to take my
word for it that this style allows the characters in the square
brackets to have a wildcard in front, so `<code>a-b</code>' can complete to
`<code>able-baker</code>', and so on.</li>
<li>Approximation with up to four errors, as given by the final style.</li>
</ol>
<p>Here's a rather bogus example. You have a directory containing:</p>
<pre><code> foobar fortified-badger frightfully-barbaric
</code></pre>
<p>Actually, it's not bogus at all, since I just created one. First try
`<code>echo foo&lt;TAB&gt;</code>'; no surprise, you get `<code>foobar</code>'. Now try completing
with `<code>fo-b&lt;TAB&gt;</code>' after the `<code>echo</code>': basic completion fails, it gets
to `_approximate:-one' and finds that it's allowed one error, so
accepts the completion `<code>foobar</code>' again. Now try `<code>fort-ba&lt;TAB&gt;</code>'.
This time nothing kicks in until the third completion, which effectively
allows it to match `<code>fort*-ba*&lt;TAB&gt;</code>', so you see `<code>fortified-badger</code>'
(no, I've never seen one myself, but they're nocturnal, you know).
Finally, try `<code>fortfully-ba&lt;TAB&gt;</code>'; the last entry, which allows up to
four errors, thoughtfully corrects `<code>or</code>' to `<code>righ</code>', and you get
`<code>frightfully-barbaric</code>'. All right, the example is somewhat unhinged,
but I think you can see the features are useful. If it makes you feel
better, it took me four or five attempts to get the styles right for
this.</p>
<p><span id="l158"></span></p>
<h3 id="652-changing-the-format-of-listings-groups-etc"><a class="header" href="#652-changing-the-format-of-listings-groups-etc">6.5.2: Changing the format of listings: groups etc.</a></h3>
<p><strong><code>format</code></strong></p>
<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:</p>
<pre><code> zstyle ':completion:*:descriptions' format 'Completing %d'
</code></pre>
<p>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):</p>
<pre><code> 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
</code></pre>
<p>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>
<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>
<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></p>
<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,</p>
<pre><code> zstyle ':completion:*' group-name ''
</code></pre>
<p>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>
<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 set, becomes:</p>
<pre><code> 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
</code></pre>
<p>which you may find more helpful, or you may find messier, depending on
deep psychological factors outside my control.</p>
<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:</p>
<pre><code> zstyle ':completion:*:-command-' group-order \
builtins functions commands
</code></pre>
<p>--- 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:</p>
<pre><code> 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
</code></pre>
<p>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></p>
<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></p>
<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>
<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 &lt;output-file&gt;</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></p>
<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:</p>
<pre><code> zmodload -i zsh/complist
</code></pre>
<p>The <code>-i</code> keeps it quiet if the module was already loaded. To install a
standard set of default colours, you can use:</p>
<pre><code> zstyle ':completion:*' list-colors ''
</code></pre>
<p>--- note the use of the `<code>default</code>' tag --- since a null string sets
the value to the default.</p>
<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:</p>
<pre><code> ZLS_COLORS=&quot;no=00:fi=00:di=01;34:ln=01;36:\
pi=40;33:so=01;35:bd=40;33;01:cd=40;33;01:\
ex=01;32:lc=\e[:rm=m:tc=00:sp=00:ma=07:hi=00:du=00
</code></pre>
<p>It has essentially the same format as <code>$LS_COLORS</code>, and indeed you can
get a more useful set of values by using the <code>dircolors</code> command which
comes with <code>ls</code>:</p>
<pre><code> ZLS_COLORS=&quot;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:&quot;
</code></pre>
<p>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>
<p>However, you need to define the style directly, since the completion
always uses that 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:</p>
<pre><code> zstyle ':completion:*' list-colors &quot;no=00&quot; &quot;fi=00&quot; ...
</code></pre>
<p>You can use an already defined <code>$LS_COLORS</code>:</p>
<pre><code> zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}
</code></pre>
<p>(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>
<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>=&lt;pat&gt;=&lt;col&gt;</code>. Here are two ways of getting jobs coloured
red in process listings for the `<code>kill</code>' command.</p>
<pre><code> zstyle ':completion:*:*:kill:*' list-colors '=%*=01;31'
</code></pre>
<p>This uses the method just described; jobs begin with `<code>%</code>'.</p>
<pre><code> zstyle ':completion:*:*:kill:*:jobs' list-colors 'no=01;31'
</code></pre>
<p>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>
<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.</p>
<pre><code> zstyle ':completion:*:*:kill:*:processes' list-colors \
'=(#b) #([0-9]#)*=0=01;31'
</code></pre>
<p>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></p>
<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:</p>
<pre><code> fignore=(.o \~ .dvi)
</code></pre>
<p>so that normal file completion will not produce object files, EMACS
backup files, or TeX DVI files.</p>
<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>
<p>Hence you can replace the use of <code>$fignore</code> above with the following:</p>
<pre><code> zstyle ':completion:*:files' ignored-patterns '*?.o' '*?~' '*?.dvi'
</code></pre>
<p>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>
<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. Another slight difference, as I said above when
discussing the <code>_ignored</code> completer, is that you get to choose whether
you want to see those ignored files if the normal completions fail, by
having <code>_ignored</code> in the completer list or not.</p>
<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,</p>
<pre><code> zstyle ':completion:*:*:dvips:argument*' \
tag-order globbed-files all-files
</code></pre>
<p>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>:</p>
<pre><code> zstyle ':completion:*:(all-|)files' ignored-patterns ...
</code></pre>
<p>Here's the example of using tag labels I promised earlier; it's simply
taken from the manual. To refresh your memory: tag labels are a way of
saying that tags should be looked up under a different name. Here we'll
do:</p>
<pre><code> zstyle ':completion:*:*:-command-:*' tag-order 'functions:-non-comp'
</code></pre>
<p>This applies in command position, from the special `<code>-command-</code>'
context, the place where functions occur most often, along with other
types of command which have their own tags. This says that when
functions are first looked up, they are to be looked up with the name
`<code>functions-non-comp</code>' --- remember that with a hyphen as the first
character of the label part, the bit after the colon, the <code>functions</code>
tag name itself, the bit before the colon, is to be stuck in front to
give the full label name `<code>functions-non-comp</code>'. We can use it as
follows:</p>
<pre><code> zstyle ':completion:*:functions-non-comp' ignored-patterns '_*'
</code></pre>
<p>In the context of this tag label, we have told completion to ignore any
patterns --- i.e. any function names --- beginning with an underscore.
What happens is this: when we try completion in command position,
<code>tag-order</code> is looked up and finds we want to try functions first, but
under the name <code>functions-non-comp</code>; this completes functions apart from
ones beginning with an underscore (presumably completion functions you
don't want to run interactively). Since <code>tag-order</code> normally tries all
the other tags, unless it was told not to, in this case all the normal
command completions will appear, including functions under their normal
tag name, so this just acts as a sort of filter for the first attempt at
completion. This is typically what tag labels are intended for ---
though maybe you can think up a lot of other uses, since the idea is
quite powerful, being backed up by the style mechanism.</p>
<p>You way wonder why you would want to ignore such functions at this
point. After all, you're only likely to be doing completion when you've
already typed the first character, which either is `<code>_</code>' or it isn't.
It becomes useful with correction and approximation --- particularly
since many completion functions are similar to the names of the commands
for which they handle completion. You don't want to be offered
`<code>_zmodload</code>' as a completion if you really want `<code>zmodload</code>'. The
combination of labels and ignored patterns does this for you.</p>
<p>You can generalise this using another feature: tags can actually be
patterns, which I mentioned but didn't demonstrate. Here's a more
sophisticated version of the previous example, adapted from the manual:</p>
<pre><code> zstyle ':completion:*:*:-command-:*' tag-order \
'functions:-non-comp:non-completion\ functions *' functions
</code></pre>
<p>It's enhanced so that completion tries all other possible tags at the
same time as the labelled <code>functions</code>. However, it only ever tries a tag
once at each step, so the `<code>*</code>' doesn't put back <code>functions</code> as you
might expect --- that's still tried under the label
`<code>functions-non-comp</code>', and the <code>ignored-patterns</code> style we set will
still work. In the final word, we try all possible functions, so that
those beginning with an underscore will be restored.</p>
<p>Use of the `<code>_ignored</code>' completer can allow you to play tricks without
having to label your tags:</p>
<pre><code> zstyle ':completion:*' completer _complete _ignored
zstyle ':completion:*:functions' ignored-patterns '_*'
</code></pre>
<p>Now anywhere the <code>functions</code> tag is valid, functions matching `<code>_*</code>'
aren't shown until completion reaches the `<code>_ignored</code>' in the completer
list. Of course, you should manipulate the completer list the way you
want; this just shows the bare bones.</p>
<p><strong><code>prefix-hidden</code>, <code>prefix-needed</code></strong></p>
<p>You will know that when the shell lists matches for files, the directory
part is removed. The boolean style <code>prefix-hidden</code> 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>
<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></p>
<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>
<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>There are some other, slightly more obscure, choices for <code>menu</code>:</p>
<ul>
<li><strong><code>yes=</code><em>num</em></strong><br />
turn on menu completion only if there are at least <em>num</em> matches;</li>
<li><strong><code>no=</code><em>num</em></strong><br />
turn off menu completion if there are as many as <em>num</em> matches;</li>
<li><strong><code>yes=long</code></strong><br />
turn on menu completion if the list does not fit on the screen, and
completion was attempted;</li>
<li><strong><code>yes=long-list</code></strong><br />
the same, but do it even if listing, not completion, was attempted;</li>
<li><strong><code>select=long</code></strong><br />
like <code>yes=long</code>, but this time turn on menu selection, too;</li>
<li><strong><code>select=long-list</code></strong><br />
like <code>yes=long-list</code>, but turn on menu selection, too.</li>
</ul>
<p>In case your eyes glazed over before the end, here's a full description
of the last one, <code>select=long-list</code>, which is quite useful: if you are
attempting completion or even just listing completions, and the list of
matches would be too long to fit on the screen, then menu selection is
turned on, so that you can use the cursor keys (and other selection
keys) to move up and down the list. Generally, the above possibilities
can be combined, unless the combined effect wouldn't work.</p>
<p>As always, <code>yes</code> and <code>true</code> are equivalent, as are <code>no</code> and <code>false</code>. It
just hurts the eyes of programmers to read something which appears to
assign a value to <code>true</code>.</p>
<p><strong><code>hidden</code></strong></p>
<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>
<p><span id="l159"></span></p>
<h3 id="653-styles-affecting-particular-completions"><a class="header" href="#653-styles-affecting-particular-completions">6.5.3: Styles affecting particular completions</a></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): patterns: <code>file-patterns</code></strong></p>
<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>directories</code>
and <code>all-files</code> are tried, in that order.</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. It has a labelling mechanism --- you can
specify a tag with a pattern for use in looking up other styles. Hence
`<code>*.o:object-files</code>' gives a pattern `<code>*.o</code>' and a tag name
`<code>object-files</code>' by which to refer to these.</p>
<p>The patterns you specify are tried in order; you don't need to use
<code>tag-order</code>. In fact <code>file-patterns</code> replicates its behaviour in that
you can put patterns in the same word to say they should be tried
together, before going on to the pattern(s) in the next word. Also, you
can give a description after a second colon in the same way. Indeed,
since <code>file-patterns</code> gets its hands on the tags first, any ordering
defined there can't be overridden by <code>tag-order</code>.</p>
<p>So, for example, after</p>
<pre><code> zstyle ':completion:*:*:foo:*:*' file-patterns \
'*.yo:yodl-files:yodl\ files *(-/):directories'
</code></pre>
<p>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
alter what's completed: `<code>foo</code>' isn't specially handled, so it causes
default completion, and that means completing files, so that
<code>file-patterns</code> is active anyway.</p>
<p>Here's a slightly enhanced example; it shows how <code>file-patterns</code> can be
used instead of <code>tag-order</code> to offer the tags in the order you want.</p>
<pre><code> zstyle ':completion:*:*:foo:*:*' file-patterns \
'*.yo:yodl-files:yodl\ files' '*(-/):directories:directories' \
'^*.yo(-^/):other-files:other\ files'
</code></pre>
<p>Completion will first try to show you only `<code>.yo</code>' files, if there are
any; otherwise it will show you directories, if there are any; otherwise
it will show you any other files: `<code>^*.yo(-^/)</code>' is an extended glob to
match any file which doesn't end in `<code>.yo</code>' and which isn't a directory
and doesn't link to a directory. As always, you can cycle through the
sets of possibilities using the `<code>_next_tag</code>' completion command.</p>
<p>Note that <code>file-patterns</code> is an exception to the general rule that
styles don't determine <em>which</em> tags are called only <em>where</em> they're
called, or what their behaviour is: this time, you actually get to
specify the set of tags which will be used. This means it doesn't use
the the standard file tags (unless you use those names yourself, of
course), just `<code>files</code>' if you don't specify one. Hence it's good style
to add the tags, following colons, although it'll work without.</p>
<p>Another thing to watch out for is that if there is already a completion
which handles a file type --- for example, if we had tried to alter the
effect of file completion for the `<code>yodl</code>' command instead of the
fictitious `<code>foo</code>' --- the results may well not be quite what you want.</p>
<p>Another feature is that `<code>%p</code>' in the pattern inserts the pattern which
would usually be used. That means that the following is essentially the
same as what file completion normally does:</p>
<pre><code> zstyle ':completion:*' file-patterns '%p:globbed-files' \
'*(-/):directories' '*:all-files'
</code></pre>
<p>You can turn completion for a command that usually doesn't use a pattern
into one that does. Another example taken from the manual:</p>
<pre><code> zstyle ':completion:*:*:rm:*:globbed-files' file-patterns \
'*.o:object-files' '%p:all-files'
</code></pre>
<p>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). The <code>%p</code> will use whatever
file completion normally would have; probably any file at all. You can
change this, if you like; there may be files you don't ever want
automatically completed after <code>rm</code>.</p>
<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): paths: <code>ambiguous</code>, <code>expand</code>, <code>file-sort</code>,
<code>special-dirs</code>, <code>ignore-parents</code>, <code>list-suffixes</code>, <code>squeeze-slashes</code></strong></p>
<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>
<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>ambiguous</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>
<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>.
Be careful when setting both --- they have to be separate words, for
example</p>
<pre><code> zstyle ':completion:*' expand prefix suffix
</code></pre>
<p>Don't put quotes around `<code>prefix suffix</code>' as it won't work.</p>
<p>With <code>prefix</code>, <code>expand</code> 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>
<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>
<p>In older versions of the completion system, <code>suffix</code> wasn't used if you
had menu completion active by default, although it was if menu
completion was only started by the <code>AUTO_MENU</code> option. However, in
recent versions, the setting is always respected. This means that
setting the <code>expand</code> style to include the value <code>suffix</code> allows menu
completion to cycle through all possible completions, as if there were a
`<code>*</code>' after each part of the path, so `<code>/u/i/k</code>' will offer all
matches for `<code>/u*/i*/k*</code>'.</p>
<p>The <code>file-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>
<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>ambiguous</code>, this is used with the
tag set to `<code>paths</code>'.</p>
<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>
<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 can 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>
<p>Next, there is <code>list-suffixes</code>. It applies when expanding out earlier
parts of the filename path, not just the last part. In this case, it is
possible that early parts of the path were ambiguous. Normally
completion stops at the point where it finds the ambiguity, and leaves
the rest of the path alone. When <code>list-suffixes</code> is set, it will list
all the possible values of all ambiguous components from the point of
ambiguity onward.</p>
<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>command</code>, <code>insert-ids</code></strong></p>
<p>Some functions, such as <code>kill</code>, take process IDs (i.e. numbers) as
arguments. These can be completed by using the <code>ps</code> command to generate
the process numbers. The <code>command</code> style allows you to specify which
arguments are to be passed to <code>ps</code> to generate the numbers; it is simply
<code>eval</code>'d to generate the command line. 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 tries to find a column which is headed
`<code>PID</code>' or `<code>pid</code>' (or even `<code>Pid</code>', in fact) to use for the process
IDs; if it doesn't find one, it just uses the first column.</p>
<p>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 the
value `<code>ps -u$USER</code>' for the style --- remembering to put this in
single quotes. Clearly, you need to make sure the context is narrow
enough to avoid unexpectedly calling odd commands.</p>
<p>You can make the value begin with a hyphen, then the usual command line
will put afterward and the hyphen removed. The suggested use for this is
adding `<code>command</code>' or `<code>builtin</code>' to make sure the right version of a
command is called.</p>
<p>The completion system allows you to type the name of a command, for
example `<code>emacs</code>', which will be converted to a PID. Note that this is
different from a job name beginning with `<code>%</code>'; in this case, any
command listed by <code>ps</code>, given the setting of the <code>command</code> style, can be
used. Obviously, command names can be ambiguous, unlike the process IDs
themselves, so the names are usually converted immediately to PIDs; if
the name could refer to more than one process, you get a menu of
possible PIDs.</p>
<p>The style <code>insert-ids</code> allows the completion system to keep using the
names rather than the PIDs. If it is set to <code>single</code>, the name will be
retained until you type enough to identify a particular process. If it
is set to <code>true</code> (or anything else but <code>menu</code>, actually), menu
completion is delayed until you have typed a string longer than the
common prefix of the PIDs. This is intended to be similar to
completion's usual logic --- don't do anything which gets rid of
information supplied by the user --- so is probably more useful in
practice than it sounds.</p>
<p><strong>Job control: <code>numbers</code></strong></p>
<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>
<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></p>
<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>
<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 containing just those you use
most often.</p>
<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>
<p>The last is probably the most useful, so I'll illustrate that. By
setting:</p>
<pre><code> zstyle ':completion:*' users-hosts \
pws:foo.bar.uk peters@frond.grub.uk
</code></pre>
<p>you tell <code>rsh</code> and friends the possible user/host combinations. Note
that for the separator you can use either `<code>:</code>', as usual inside the
completion system, or `<code>@</code>', which is more natural in this particular
case. 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>
<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>
<p>The other combined styles work in exactly the same way; just set the
values separated by colons or `<code>@</code>', it doesn't matter which.</p>
<p><strong>URLs for web browsers</strong></p>
<p>Completion for URLs is done by setting a parallel path somewhere on your
local machine. The <code>urls</code> style specifies the top directory for this.
For example, to complete the URL <code>http://zsh.org/</code>, you need to make a
set of subdirectories of the <code>path</code> directory <code>http/zsh.org/</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>mkdir</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; there is, however, a tool provided with
the shell distribution in <code>Misc/make-zsh-urls</code> which should be able to
help --- ask your system administrators about this if it isn't
installed, I'm sure they'll be delighted to help.</p>
<p>If you only have a few URLs you want to complete, you can use one of two
simpler forms for the <code>urls</code> style. First, if the value of the style
contains more than one word, the values are used directly as the URLs to
be completed, e.g.:</p>
<pre><code> zstyle ':completion:*:urls' urls \
http://www.foo.org/ ftp://ftp.bar.net
</code></pre>
<p>Alternatively, you can set the <code>urls</code> style to the name of a normal
file, which contains the URLs to complete separated by white space or
newlines.</p>
<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>
<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</p>
<pre><code> zstyle ':completion:*:urls' local \
www.footling.com /usr/local/www/files www
</code></pre>
<p>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></p>
<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>
<p><span id="l160"></span></p>
<h2 id="66-command-widgets"><a class="header" href="#66-command-widgets">6.6: Command widgets</a></h2>
<p><span id="l161"></span></p>
<h3 id="661-_complete_help"><a class="header" href="#661-_complete_help">6.6.1: <code>_complete_help</code></a></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>
<p><span id="l162"></span></p>
<h3 id="662-_correct_word-_correct_filename-_expand_word"><a class="header" href="#662-_correct_word-_correct_filename-_expand_word">6.6.2: <code>_correct_word</code>, <code>_correct_filename</code>, <code>_expand_word</code></a></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>
<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>
<p><span id="l163"></span></p>
<h3 id="663-_history_complete_word"><a class="header" href="#663-_history_complete_word">6.6.3: <code>_history_complete_word</code></a></h3>
<p>This is usually bound to `<code>&lt;ESC-/&gt;</code>' for completing back in the
history, and `<code>&lt;ESC-,&gt;</code>' for completing forward --- this will
automatically turn on menu completion, temporarily if you don't normally
have that set, to cycle through the matches. It will complete words from
the history list, starting with the most recent. Hence</p>
<pre><code> touch supercalifragilisticexpialidocious
cat sup&lt;ESC-/&gt;
</code></pre>
<p>will save you quite a bit of typing --- although in this particular
case, you can use `<code>&lt;ESC-.&gt;</code>' to insert the last word of the previous
command.</p>
<p>Various styles are available. You can set the `<code>stop</code>' style which
makes it stop once before cycling past the end (or beginning) of the
history list, telling you that the end was reached.</p>
<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. Finally, the <code>range</code> style is supported via the
<code>_history</code> completer, which does the work. This style restricts the
number of history words to be searched for matches and is most useful if
your history list is large. Setting it to a number <em>n</em> specifies that
only the last <em>n</em> history words should be searched for possible matches.
Alternatively, it can be a value of the form `<em>max</em><code>:</code><em>slice</em>', in
which case it will search through the last <em>slice</em> history words for
matches, and only if it doesn't find any, the <em>slice</em> words before that;
<em>max</em> gives an overall limit on the maximum number of words to search
through.</p>
<p><span id="l164"></span></p>
<h3 id="664-_most_recent_file"><a class="header" href="#664-_most_recent_file">6.6.4: <code>_most_recent_file</code></a></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>
<p>By the way, you can actually do the same by setting appropriate styles,
without any new functions. The trick is to persuade the system to use
the normal <code>_files</code> completer with the <code>file-sort</code> style. By restricting
the use of the styles to the context of the widget --- which is simply
the <code>_generic</code> completer described above:</p>
<pre><code> zstyle ':completion:(match-word|most-recent-file):*' \
match-original both
zstyle ':completion:most-recent-file::::' completer \
_menu _files _match
zstyle ':completion:most-recent-file:*' file-sort modification
zstyle ':completion:most-recent-file:*' file-patterns \
'*(.):normal\ files'
zstyle ':completion:most-recent-file:*' hidden true
zstyle ':completion:most-recent-file:*:descriptions' format ''
bindkey '^Xm' most-recent-file
zle -C most-recent-file menu-complete _generic
</code></pre>
<p>It may not be obvious how this works, so here's a blow by blow account
if you are interested. (It works even if you aren't interested,
however.)</p>
<ul>
<li>The `<code>zle -C</code>' defines a widget which does menu completion, and
behaves like ordinary completion (that's what <code>_generic</code> is for)
except that the context uses the name of the widget we define.</li>
<li>When we invoke the widget, the system uses the <code>completer</code> style to
decide what completions to perform. This instructs it: use menu
completion, complete files, use pattern matching if the completion
so far didn't work.</li>
<li>First, <code>_menu</code> comes along; it actually does nothing more than tell
the system to use menu completion.</li>
<li>Then <code>_files</code> generates a list of files. This uses the <code>file-sort</code>
and <code>file-patterns</code> styles defined for the <code>most-recent-file</code>
context. They produce a set of files in modification time order, and
include only regular files (so not directories, symlinks, device
files and so on).</li>
<li>If that failed, the <code>_match</code> style allows the word on the command
line to be treated as a pattern; for example, <code>*.c</code> to complete the
most recent C source file. This uses the <code>match-original</code> style; the
setting tells it that it should try first without adding an extra
`<code>*</code>' for matching (this is what we want for the case where we
already have a complete pattern like <code>*.c</code>), and if that fails, add
a <code>*</code> at the end and try again.</li>
<li>The <code>hidden</code> style means that the matches aren't listed; all that
happens is the first is inserted on the line. The setting for the
<code>format</code> tag similarly simplifies the display in this case by
removing verbose descriptions.</li>
<li>The net result is the first step of a menu completion: insert the
first matched file (the most recently modified) onto the line. This
is exactly what you want. Note, however, that as we are in menu
completion you can keep on hitting <code>^xm</code> and the shell will cycle
through the matches, which here gives you files that are
progressively less recently modified.</li>
</ul>
<p>Omit the <code>file-patterns</code> line if you don't want the match restricted to
regular files (I sometimes need the most recently modified directory,
but often it's irrelevant). The whole version using styles comes from
Oliver Kiddle, who recommends using <code>_generic</code> in this way any time you
want to generate a widget from a specific completion such as <code>_files</code>.
There is a brief section on <code>_generic</code> below.</p>
<p><span id="l165"></span></p>
<h3 id="665-_next_tags"><a class="header" href="#665-_next_tags">6.6.5: <code>_next_tags</code></a></h3>
<p>This is a very neat way of getting round the order of tags just with a
key sequence. An example is the best way of showing it; it's bound by
default to the key sequence `<code>^Xn</code>'.</p>
<pre><code> % tex ^D
Completing TeX or LaTeX file
bar.tex foo.tex guff.tex
</code></pre>
<p>Our file is not in that directory, but by default we don't get to see
the directory if there was a file that matched the pattern --- here
`<code>*.tex</code>'. (This will actually change in 4.1, since most people don't
know about <code>_next_tags</code> but do know about directories, but you can still
cycle through the different sets of tags.) You can set the <code>tag-order</code>
style to alter whether they appear at the same time, but <code>_next_tags</code>
lets you do this very simply. Just hit <code>^Xn</code>. You're now looking at</p>
<pre><code> Completing TeX or LaTeX file
dir1/ dir2/ dir3/
</code></pre>
<p>and if you carry on hitting <code>^Xn</code> you will get to all files, and then
you will be taken back to the <code>.tex</code> files again. (Where our file
actually is, is left as an exercise for the reader.)</p>
<p>Of course this works with any set of tags whatsover; it simply has the
effect of cycling you around the tag order.</p>
<p><span id="l166"></span></p>
<h3 id="666-_bash_completions"><a class="header" href="#666-_bash_completions">6.6.6: <code>_bash_completions</code></a></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:</p>
<pre><code> for key in '!' '$' '@' '/'; do
bindkey &quot;\e$key&quot; _bash_complete-word
bindkey &quot;^X$key&quot; _bash_list-choices
done
</code></pre>
<p>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>
<p><span id="l167"></span></p>
<h3 id="667-_read_comp"><a class="header" href="#667-_read_comp">6.6.7: <code>_read_comp</code></a></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>
<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>
<p><span id="l168"></span></p>
<h3 id="668-_generic"><a class="header" href="#668-_generic">6.6.8: <code>_generic</code></a></h3>
<p>Rather than being directly bound, like the others, this widget gives you
a way of creating your own special completions. You define it as a
widget and bind it as if it were any completion function:</p>
<pre><code> zle -C foo complete-word _generic
bindkey '&lt;keys&gt;' foo
</code></pre>
<p>Now the keys bound will perform ordinary contextual completion, but any
styles will be looked up with the command context `<code>foo</code>'. So you can
give it its own set of completers:</p>
<pre><code> zstyle ':completion:foo:*' completer _expand
</code></pre>
<p>and, indeed, give it special values for any style you like. To put it
another way, you've now got a complete, separate copy of the completion
system where the only difference is the extra word in the context.</p>
<p>Good example of the use of this function were given above in the
descriptions of <code>_all_matches</code> and <code>_most_recent_file</code>.</p>
<p><span id="l169"></span></p>
<h3 id="669-predict-on-incremental-complete-word"><a class="header" href="#669-predict-on-incremental-complete-word">6.6.9: <code>predict-on</code>, <code>incremental-complete-word</code></a></h3>
<p>These are not really complete commands 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,</p>
<pre><code> 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
</code></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>
<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>
<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 <code>always</code>, 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
completed, `<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>
<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>
<p><span id="l170"></span></p>
<h2 id="67-matching-control-and-controlling-where-things-are-inserted"><a class="header" href="#67-matching-control-and-controlling-where-things-are-inserted">6.7: Matching control and controlling where things are inserted</a></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</code> manual page; in the printed manual and
the `info' pages this occurs within the section `<code>Completion Widgets</code>'.</p>
<p>The <code>matcher-list</code> style takes an array value. The values will be tried
in order from left to right. For example,</p>
<pre><code> zstyle ':completion:*' matcher-list 'm:{a-z-}={A-Z_}' \
'r:|[-_./]=* r:|=*'
</code></pre>
<p>tries the first specification, which is for case-insensitive completion,
and if no matches 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>
<p><span id="l171"></span></p>
<h3 id="671-case-insensitive-matching"><a class="header" href="#671-case-insensitive-matching">6.7.1: Case-insensitive matching</a></h3>
<p>To perform case-insensitive matching for all completions, you can set:</p>
<pre><code> zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}'
</code></pre>
<p>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>
<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&lt;TAB&gt;</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>
<p>If you want completely case-insensitive matching, so that typing
`<code>MAKE&lt;TAB&gt;</code>' would also potentially complete to `<code>Makefile</code>' or
`<code>makefile</code>' (and so on), the extension is fairly obvious:</p>
<pre><code> zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
</code></pre>
<p>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>
<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>
<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>
<p><span id="l172"></span></p>
<h3 id="672-matching-option-names"><a class="header" href="#672-matching-option-names">6.7.2: Matching option names</a></h3>
<p>I explained back in <a href="zshguide01.html#intro">chapter 1</a> 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>
<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>:</p>
<pre><code> compadd -M 'B:|[nN][oO]= M:_= M:{A-Z}={a-z}' - ${(k)options}
</code></pre>
<p>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>
<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>
<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>
<p>The first part has an `anchor', indicated by what lies between the
`<code>:</code>' and the `<code>|</code>'. The <code>B</code> specifies that the case insensitive match
of `<code>no</code>' must occur at the start of the word on the command line (with
`<code>b</code>' it would be the word in the list of matches), but here it is lax
enough to allow this to happen after the `<code>M:_=</code>' has stripped any
initial underscores away. Hence it 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. Again, the capital `<code>B</code>' at the
start means 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>
<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:</p>
<pre><code> NO_GLob NO_GLobassign NO_GLobdots
NO_GLobalrcs NO_GLobcomplete NO_GLobsubst
</code></pre>
<p>--- 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>
<p><span id="l173"></span></p>
<h3 id="673-partial-word-completion"><a class="header" href="#673-partial-word-completion">6.7.3: Partial word completion</a></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:</p>
<pre><code> zstyle ':completion:*' matcher-list 'r:|.=* r:|=*'
</code></pre>
<p>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>
<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>
<p>Let's see that in action. Here are the actual contents of my actual
<code>tmp</code> directory, never mind why:</p>
<pre><code> regframe.rpm t.c testpage.dvi testpage.log testpage.ps
</code></pre>
<p>Now I set the <code>matcher-list</code> style as above and type:</p>
<pre><code> echo t.p&lt;TAB&gt;
</code></pre>
<p>and get</p>
<pre><code> echo testpage.ps
</code></pre>
<p>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>
<p>You might wonder what happens when there's a file <code>testpage.old.ps</code>
around, i.e. the anchor appears twice in that. With the matcher set as
given above, that won't be completed; the anchor needs to be matched
explicitly, not by a wildcard. If you don't like that, you can change
the `<code>*</code>' after the `<code>=</code>' in the specification to `<code>**</code>'; this form
allows the anchor to occur in the string being matched. You can think of
`<code>*</code>' and `<code>**</code>' as taking the shortest and the longest possible
matches respectively. If you use a lot of `<code>**</code>' specifications in your
matches, things can get very confusing, however.</p>
<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</p>
<pre><code> zstyle ':completion:*' matcher-list 'r:|[._-]=* r:|=*'
</code></pre>
<p><span id="l174"></span></p>
<h3 id="674-substring-completion"><a class="header" href="#674-substring-completion">6.7.4: Substring completion</a></h3>
<p>I've mentioned `<code>r</code>' and `<code>B</code>', but corresponding to `<code>r</code>' there is
`<code>l</code>', which anchors on the left instead of the right, and
corresponding to `<code>B</code>' there is `<code>E</code>' which matches at the end instead
of the beginning; and, of course, all exist in both upper- and lowercase
forms, meaning `keep what the user typed' and `keep what is in the
list of possible matches', respectively.</p>
<p>Here is an example of using `<code>l:|=*</code>' to match anything at the start of
the word: this is the effect of having an empty anchor, as you saw with
`<code>r</code>' above, but note with `<code>l</code>', the anchor appears, logically
enough, on the left of the `<code>|</code>', in the order they would appear on the
command line. By combining this with the `<code>r</code>' form, you can make the
completion system work when what is on the command line matches only a
substring of a trial completion --- i.e., has anything else on the left
and on the right. 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, then
partial-word completion (case-sensitively), then substring completion:</p>
<pre><code> zstyle ':completion:*' matcher-list 'm:{a-z}={A-Z}' \
'r:|[._-]=* r:|=*' 'l:|=* r:|=*'
</code></pre>
<p><span id="l175"></span></p>
<h3 id="675-partial-words-with-capitals"><a class="header" href="#675-partial-words-with-capitals">6.7.5: Partial words with capitals</a></h3>
<p>This section illustrates another feature: if you use `<code>||</code>' when
specifying anchors for `<code>L</code>' or `<code>R</code>' or their lowercase variants, the
pattern part for what appears on the command line, which would usually
be translated into some other pattern, is treated instead as another
anchor on the other side of the pattern --- which isn't matched against
the pattern in the word, it just has to appear. In other words, this
part matches without being `swallowed up' in the process. An example
(again adapted from the manual) will make this clearer.</p>
<pre><code> compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=** r:|=*' \
LikeTHIS LooHoo foo123 bar234
</code></pre>
<p>The four possible completions are on the second line. The second of the
two matcher specifications just allows anything to match on the right,
so if we are inside the word, the remainder may be completed. The first
word is where the action is; it says `A part of the completion which
has on the left something other than an upper case letter or a digit,
and on the right an upper case letter or a digit, may match anything,
including the anchor'. So in particular, this would allow `<code>LH</code>' to
complete to `<code>LooHoo</code>' --- and only that, since `<code>LikeTHIS</code>' has an
uppercase letter to the left of the `<code>H</code>', which is not allowed. In
other words, the chunks of word beginning with uppercase letters and
digits act like the start of substrings. (If you like, remember that
last sentence and the specification, and forget the rest.)</p>
<p><span id="l176"></span></p>
<h3 id="676-final-notes"><a class="header" href="#676-final-notes">6.7.6: Final notes</a></h3>
<p>To put everything together, the possible specifications are
`<code>m:...=...</code>', `<code>l:...|...=...</code>', `<code>r:...|...=...</code>',
`<code>b:...|...=...</code>' and `<code>e:...|...=...</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 together.</p>
<p>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>
<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>
<p>Although I won't talk about matching control after this section, 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>
<p>Actually, you can configure this to a considerable extent without
altering a function, using styles and labelled tags. From the manual:</p>
<pre><code> zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
</code></pre>
<p>In command <code>foo</code>, whatever the tags are, they are to be tried normally
first (the `<code>*</code>' argument to <code>tag-order</code>), then under the same name
with `<code>-case</code>' appended. The second style defines a matcher for any tag
ending in the suffix `<code>-case</code>', which allows lowercase characters to
match uppercase ones. The upshot is that completion of anything at all
for the command <code>foo</code> will be tried first case-sensitively, then
case-insensitively.</p>
<p><span id="l177"></span></p>
<h2 id="68-tutorial"><a class="header" href="#68-tutorial">6.8: Tutorial</a></h2>
<p>Before bamboozling you with everything there is to know about writing
your own completion function, I'll give you an example of something I
wrote myself recently. If you were doing this yourself, you would then
just stick this function somewhere in your function search path, and
next time you started the shell it would start doing its work. However,
the file already exists: it's called <code>_perforce</code> and you should find it
in the function search for versions 4.1.1 and above of zsh. I apologize
if it's not the ideal function to start with, but it is fresh in my
mind, so what I'm saying has some chance of being correct.</p>
<p>This section is subtitled, `How I struggled to write a set of
completions for Perforce'. Perforce is a commercial configuration
management tool (as they now call revision control systems); consult
<a href="http://www.perforce.com/">http://www.perforce.com/</a> for details. It's concepts aren't a million
miles from CVS, the archetypal system of this kind, but it was
sufficiently different that the completion functions needed rewriting
from the ground up. You won't need to know anything about CVS or
Perforce, because at each stage I'll explain what I'm trying to complete
and why. This should give you plenty of meat for writing completions of
your own. After the tutorial, the chapter goes into the individual
details, which will expand on some of the things that appeared briefly
in the tutorial.</p>
<p>What I tend to find the most complicated part of this is making sure the
completion system knows the correct types of completions and their tags
to be completed at once. This probably won't be your first priority when
trying to write completions of your own, but if you do it right, all the
stuff about selecting types and arranging them in groups that I showed
above will just work. In this tutorial we arrange to use enough of the
higher level functions that it will work without too much (apparent)
effort. Of course, working out from scratch which those functions are
isn't always that easy; hence the tutorial.</p>
<p>Needless to say, I will simplify grossly at a lot of points. You can see
the finished product in the zsh 4.1 distribution. It even has a few
comments in.</p>
<p><strong>Basic structure</strong></p>
<p>Like the <code>cvs</code> command and a few other of the more complicated commands
you might use, Perforce is run by a single command, <code>p4</code>, followed by an
argument giving the particular Perforce command, followed by an options
and arguments to that command.</p>
<p>This dictates the basic tasks the completion functions must do:</p>
<ul>
<li>If we are in the first argument, complete the name of the
subcommand.</li>
<li>If we are in a subsequent argument, look up the name of the
subcommand and call the function which handles its arguments.</li>
</ul>
<p>This is more complicated than most commands you will write completions
for. However, one useful feature of the completion system is you can do
completions in a recursive fashion. So once you get to the point where
you are handling arguments for a particular subcommand, you can
completely forget about the first step --- as if the subcommand was the
command on the line.</p>
<p>In addition to the subcommands, there are lots of other types of object
Perforce knows about: files, obviously, plus revisions of files, set of
changes (`changelists') applied at once, numbers of fixes applied to
files (essentially a way of tying changlists to a particular change
request for bugtracking purposes), types of file --- text, binary, etc.,
and several others. We will break down each of these completions into
its own function. That means that any time we need to complete a
particular type of object, wherever it appears (and many of these
objects can appear in lots of different places), we just call the same
function.</p>
<p>Hence there are a large number of different functions:</p>
<ul>
<li>The main dispatcher for the command, called <code>_perforce</code> for clarity
--- the main command it handles is `<code>p4</code>', but the name Perforce is
more familiar.</li>
<li>One function for each subcommand.</li>
<li>One function for each type of object Perforce knows about and we
complete (we don't bother completing dates, for example).</li>
<li>In some cases, in particular files, multiple functions since there
are different types of file --- regular files and directories
completed in the normal way, files completed by asking Perforce
where it has stored them, files opened for some form of change to be
made to them, and so on. Each of these is completed by a different
function.</li>
</ul>
<p>This makes it impractical to put all the functions in separate files
since editing them would be a nightmare. What's more, since we will
always go through the dispatcher <code>_perforce</code>, we don't need to tell the
shell to autoload all the other functions; it can just hook them in from
the main file. The file <code>_perforce</code> therefore has the structure:</p>
<pre><code> #compdef p4
# Main dispatcher
_perforce() {
# ...
}
# Helper functions for the various types of object
_perforce_files() {
# ...
}
# ...
# Dispatchers for the individual subcommands.
_perforce_cmd_help() {
# ...
}
# Code to make sure _perforce is run when we load it
_perforce &quot;$@&quot;
</code></pre>
<p>That last line is probably the least obvious. It's because of the fact
that zsh (unlike other shells) usually treats the file of an autoloaded
function as being the body of the function. Since everything else here
just defines a function, without the last line nothing would happen the
first time it was run; it would define <code>_perforce</code> and all the other
functions, but that was it. The last line makes sure <code>_perforce</code> gets
run with all the arguments passed down. The shell is smart enough to
know that the <code>_perforce</code> function we defined in the file is the one to
keep for future use, not the entire file, so from then on things are
easy; we just have a complete set of ready-defined files.</p>
<p>In fact the various helper functions didn't even need to use the `<code>_</code>'
convention for completion functions, since the completion system didn't
see them directly. However, I've kept it for consistency.</p>
<p>There's one extra trick: apart from <code>_perforce</code> itself, the function
definitions look like this:</p>
<pre><code> (( $+functions[_perforce_cmd_diff] )) ||
_perforce_cmd_diff() {
# body of function
}
</code></pre>
<p>This is to allow the user to override each function separately. The test
uses the <code>$functions</code> special associative array from the <code>zsh/parameter</code>
module, which the completion system loads. If the function is already
defined, because the corresponding element in the <code>$functions</code> parameter
is set, then we skip the definition of the function here, because the
user has already defined it. So if you were to write your own
<code>_perforce_cmd_diff</code> and put it into the function path, it would be
used, as you no doubt intended.</p>
<p><span id="l178"></span></p>
<h3 id="681-the-dispatcher"><a class="header" href="#681-the-dispatcher">6.8.1: The dispatcher</a></h3>
<p>This top level is only necessary for complex commands with multiple
subcommands. There are interesting titbits here, but if you just want to
know how to complete a command with ordinary UNIX-style argument
parsing, skip to the next section.</p>
<p>The main <code>_perforce</code> function has the two purposes described at the top
of the previous subsection. We need to decide whether we are in the
first word after the <code>p4</code> command itself. A simple way of doing that is:</p>
<pre><code> if (( CURRENT &gt; 2 )); then
# Remember the subcommand name
local cmd=${words[2]}
# Set the context for the subcommand.
curcontext=&quot;${curcontext%:*:*}:p4-$cmd&quot;
# Narrow the range of words we are looking at to exclude `p4'
(( CURRENT-- ))
shift words
# Run the completion for the subcommand
_perforce_cmd_$cmd
else
local hline
local -a cmdlist
_call_program help-commands p4 help commands | while read -A hline; do
(( ${#hline} &lt; 2 )) &amp;&amp; continue
[[ $hline[1] = (#i)perforce ]] &amp;&amp; continue
cmdlist=($cmdlist &quot;${hline[1]}:${hline[2,-1]}&quot;)
done
_describe -t p4-commands 'Perforce command' cmdlist
fi
</code></pre>
<p>This already looks a bit horrific, but it breaks down quite easily. We
test the <code>$CURRENT</code> parameter, which is a special parameter in the
completion system giving the word on the command line we are on. This is
the syntactic word --- the completion system has already done the hard
job (and that's not an overstatement, I can tell you) of deciding what
makes up a word on the command line, taking into account quoting and
special characters. The array of words is stored, unsurprisingly, in the
array <code>$words</code>. So word 1 will be `<code>p4</code>' and word 2 the subcommand.</p>
<p>Hence if we are past word 2, we look at <code>${words[2]}</code> to get the
subcommand, and use that to decide what to do next. The change to
<code>$curcontext</code> is a bit of cleverness to make it easy for the user to
defined styles for particular subcommands; refresh your mind by looking
at the discussion of styles and contexts above if you need to. For
example, if you are completing after `<code>p4 diff</code>', the context will look
something like
`<code>:completion::complete:p4-diff:argument-1:opened-files</code>' where the
remainder says you are on the first argument and are complete the tag
`<code>opened-files</code>', We'll see down below how we tell the system to use
that tag; the `<code>argument-1</code>' is handled by the <code>_arguments</code> utility
function, which takes away a lot of the load of handling options and
arguments in a standard UNIX format.</p>
<p>Next, we pretend that the `<code>p4</code>' at the start wasn't there by removing
the front of <code>$words</code> and decrementing <code>$CURRENT</code> so as to reflect its
new position in <code>$words</code>. The reason for doing this is that we are going
to use <code>_arguments</code> for handling the subcommand. As is only sensible,
this function looks at the first element of <code>$words</code> to find the command
word, and treats the rest as options or arguments to the command.</p>
<p>We then dispatch the right function for the command simply by
constructing the name of the function on the fly. Of course it's a
little neater to check the function exists first;
<code>$+functions[_perforce_cmd_$cmd]</code> would come to our aid again.</p>
<p>However, if we're still on the second (original) word, we have to
generate a list of functions to complete. We will do this by asking
Perforce's help system to list them, and store the results in the array
<code>$cmdlist</code>. The loop has a couple of checks to remove blank lines and
the title line at the start. The remaining lines have a command and a
description. We take the command, but also tack the description on after
a colon --- we can then show the user the description, too, as a bit of
extra help.</p>
<p>Actually, the Perforce command that generates the list of subcommands is
simply `<code>p4 help command</code>'. (That's really all you need to know; skip
the rest of the paragraph if you just want the basics.) The
`<code>_call_program help-commands</code>' was stuck in front for the name of
configurability. Before executing the command, the system checks in the
current context with the given tag <code>help-commands</code> for the style
<code>command</code>. If it finds a value for that style, it will use that as the
command to execute in the place of the remaining arguments. If the style
it read began with <code>-</code>, then the command it was going to execute ---
i.e. `<code>p4 help commands</code>' is appended to the end of the command read
from the style, so that the user's command can process the original
command if it needs to. This is really extreme sophistication; you will
rarely actually need the <code>command</code> style, but if you are writing a
completion for others to use it's polite to give them a chance to
intercept calls in this way.</p>
<p>The <code>_describe</code> command then does the work for us. The `<code>-t p4-commands</code>' gives the tag we are going to use; the convention is that
tag names are plural, though there's nothing to enforce this. Then we
give an overall description --- this is what appears after
`<code>Completing </code>' in the examples of the <code>format</code> style above; if you
don't have that set, you won't see it. Finally, we give the array name
--- note it is the <em>name</em>, not the substituted value. This is more
efficient because the shell doesn't need to extract the values until the
last minute; until then it can pass around just the single word. The
<code>_description</code> function knows about the `<code>completion:description</code>'
syntax; reread what I said about the <code>verbose</code> style for what the system
does with the descriptions for the completion.</p>
<p>The <code>_describe</code> function is one level above the completion system's
basic builtin command, <code>compadd</code>; it just knows about a single tag, with
a little icing sugar to display verbose descriptions. Later, we'll see
ways of building up alternatives where different types of completion can
be completed at the same point. There are lots of ways of doing this;
some of the more complicated are relegated to the detailed descriptions
that follow the tutorial.</p>
<p><span id="l179"></span></p>
<h3 id="682-subcommand-completion-_arguments"><a class="header" href="#682-subcommand-completion-_arguments">6.8.2: Subcommand completion: <code>_arguments</code></a></h3>
<p>Suppose we are now completing after `<code>p4 diff</code>'. We have altered the
command line so that the function now sees the `<code>diff</code>' as the first
word, as if this were the command. This makes the next step easier; the
<code>_arguments</code> function won't see irrelevant words on the command line,
since it is designed to handle the arguments to a simple command in the
standard form `<code>command [ options ] arguments ...</code>'. Here's the simple
version.</p>
<pre><code>
_perforce_cmd_diff() {
_arguments -s : \
'-f[diff every file]' \
'-t[include non-text files]' \
'(-sd -se -sr)-sa[opened files, different or missing]' \
'(-sa -se -sr)-sd[unopened files, missing]' \
'(-sa -sd -sr)-se[unopened files, different]' \
'(-sa -sd -se)-sr[opened files, same as depot]' \
'-d-[select diff option]:diff option:'\
'((b\:ignore\ blanks c\:context n\:RCS s\:summary'\
'u\:unified w\:ignore\ all\ whitespace))' \
&quot;*::file:_perforce_files&quot;
}
</code></pre>
<p>I've split the argument beginning <code>-d</code> into three lines to fit, but it's
just a single argument. Also, for clarity I've missed out the line with
the `<code>$+functions</code>' test to see if <code>_perforce_cmd_diff</code> was already
defined; I'll forget about that for now.</p>
<p>The function <code>_arguments</code> has been described as having `the syntax from
hell', but with the arguments already laid out in front of you it
doesn't look so bad. The are three types of argument: options to
<code>_arguments</code> itself, arguments saying how to handle options to the
command (i.e. `<code>p4 diff</code>'), and arguments saying how to handle normal
arguments to the command.</p>
<p>The first two are for <code>_arguments</code> itself; `<code>-s</code>' tells it that
single-letter options are allowed, i.e. they can be combined as in
`<code>-ft</code>'. Luckily for our purposes, that doesn't stop us having multiple
word options, too. The colon on its own then says everything else is an
argument relating to the command line being handled.</p>
<p>We then start off with some simple options; as you can probably guess
straight away, the first two say that `<code>p4 diff -f</code>' passes a flag to
say any file can be diff'ed (not just ones open for editing), and that
`<code>p4 diff -t</code>' passes a flag to say that binary files can be diff'ed
(not just text files). Note the use of square brackets for giving a
description; this is handled by the <code>verbose</code> style as I mentioned for
<code>_describe</code>. In fact, the list of possible options and arguments,
suitably rearranged, will end up passing through <code>_describe</code>. The
descriptions in square brackets are optional, as the use of square
brackets might suggest; you could just have `<code>-f</code>' and `<code>-t</code>' (making
it fairly obvious why the `<code>:</code>' to separate off _arguments's own
options is a good idea).</p>
<p>The next step in complexity is that set of functions with the list in
parentheses in front. These give mutually exclusive options. In other
words, if there's already a <code>-sa</code> on the command line, don't complete
any of <code>-sd</code>, <code>-se</code> or <code>-sr</code>, and so on. (Remember that by default you
need to type the first `<code>-</code>' of an option, or the system will go
straight to normal arguments, which we'll come to in a moment.)</p>
<p>Next comes the specification for the option <code>-d</code>. All those colons
indicate that this option has an argument, and the <code>-</code> following
straight after the <code>-d</code> indicates that it has to be in the same word,
i.e. follow the <code>-d</code> without a space. After the first colon comes a
description for the argument. This is what you see when you try to
complete the after <code>-d</code>; compare this with the expression in square
brackets before, which is what you see when you try to complete the <code>-d</code>
itself. Then after the second colon is an expression saying how to
complete that argument.</p>
<p>This final part of the specification for an option with an argument can
take various forms. The simplest is just a single space; this means
there's nothing to complete, but the system is aware the user needs to
type something for that word and can prompt with the description. The
next simplest is a set of words in parentheses: here, we could have had
`<code>(b c n s u w)</code>'. Instead, we've had a variant on that which gives yet
another set of descriptions, namely those for the individual completions
that appear after <code>-d</code>. Note various things: the parentheses are doubled
and the colons and spaces within the completion options are backslashed.
All of these are simply there to make it easy for <code>_arguments</code> to parse
the string. The upshot of this is that in the following context:</p>
<pre><code> p4 diff -d
</code></pre>
<p>a verbose completion using the <code>format</code> style as described above looks
like:</p>
<pre><code> Completing diff option
b # ignore blanks
c # context
n # RCS
s # summary
u # unified
w # ignore all whitespace
</code></pre>
<p>or similar --- I have the <code>list-separator</code> style set to `<code>#</code>', because
it looks like a comment normal shell syntax, but in your case you may
get `<code>-``-</code>' as the separator.</p>
<p>(In case you were wondering why the colons needed to be quoted when it
seemed you'd already got to the last argument: it's possible for options
to have multiple arguments, and you can continue having sets of
<code>:</code><em>description</em><code>:</code><em>action</em> pairs. This means the system needs some way
of distinguishing these colons from ones inside arguments. While I'm
digressing, you may also have noticed that I could have written the
<code>-s</code><em>X</em> as an option with arguments, in which case you can have a bonus
point.)</p>
<p>The final argument starts with a `<code>*</code>', which means it applies to all
remaining arguments to `<code>p4 diff</code>' after the options have been
processed. Most of the rest is similar to the form for options, except
for the doubled colon, which indicates that <code>$CURRENT</code> and <code>$words</code>
should be altered to reflect only the arguments being handled by this
argument specifier --- exactly what we did before calling
<code>_perforce_cmd_diff</code> in the first place, in fact. As we mentioned
before, this makes the next step of processing easier if happens to call
<code>_arguments</code> again. (Actually it doesn't in this case.) The `<code>file</code>'
then describes the arguments and the final part, <code>_perforce_files</code>,
tells the system to call that function to complete a file name.</p>
<p>There are numerous (it sometimes seems, endless) subtleties to
<code>_arguments</code>. I won't try to go into them in the tutorial; see the
description of <code>_arguments</code> below for something more detailed to refer
to, and if you are feeling <em>really</em> brave look at the description in the
<code>zshcompsys</code> manual page. Even better, dig into one of the existing
completion functions --- something handling completion for a UNIX
command is probably good, since these make heavy use of <code>_arguments</code> ---
and see how those work. Despite the complexities, I would definitely
suggest using <code>_arguments</code> wherever possible to take away any need on
your part to do processing of command line arguments.</p>
<p><span id="l180"></span></p>
<h3 id="683-completing-particular-argument-types"><a class="header" href="#683-completing-particular-argument-types">6.8.3: Completing particular argument types</a></h3>
<p>Now we'll look inside the <code>_perforce_files</code> function as an example of
the nitty gritty of completing one particular type of argument, which
might have some quite complicated internal structure. This is true in
Perforce as the filename can have extra information tacked on the end:
`<code>file#</code><em>revision</em>' indicates the revision of a file,
`<code>file@</code><em>change</em>' indicates a change status, and in some cases you can
get `<code>file@</code><em>change1</em><code>,</code><em>change2</em>' to indicate a range of changes
(likewise revisions). Furthermore, <code>file</code> can be specified in different
ways, and the file to be completed may be limited by some kind of
context information. We'll start from simple filenames and gradually add
these possibilities in.</p>
<p><strong>Different types of file, part 1</strong></p>
<p>There are so many possibilities for files that I'm going to split up
<code>_perforce_files</code> into individual functions handling different aspects.
For example, even if we are just handling ordinary files in the way the
completion system normally does, Perforce commands understand a special
file name `<code>...</code>' which means `every subdirectory to any depth'.
(Interestingly, zsh used to have this to mean the same thing, instead of
`<code>**</code>'; it was changed in zsh because as the `<code>.</code>'s are regular
characters there's no easy way of quoting them. You didn't need to know
this.)</p>
<p>I'm going to say we can complete both like this:</p>
<pre><code> _alternative \
&quot;files:file:_path_files&quot; \
&quot;subdirs:subdirectory search:_perforce_subdir_search&quot;
</code></pre>
<p>The function <code>_alternative</code> is a little bit like <code>_arguments</code>, but
thankfully much simpler. It's name gives away its purpose; every
argument specifies one of a set of possible alternatives, all of which
are valid at that point --- so the user is offered anything which
matches out of the choices, unlike <code>_arguments</code>, which has to decide
between the various possibilities. It's a sort of glorified loop around
`<code>_describe</code>', with <code>_arguments</code>'s conventions on the action for
generating completions (up to a point --- <code>_alternative</code> doesn't have
all the whackier ones, though it does have the ones I've been talking
about so far).</p>
<p>Each set of possibilities consists of the name of a tag, a description,
and an argument. The tag isn't present in <code>_arguments</code>. If you use <code>^xh</code>
to tell you about valid tags, you'll see <code>_arguments</code> has its own
generic tag, <code>argument-rest</code>; this isn't usually all that useful, so we
are going to supply more specific ones.</p>
<p>In the first possibility, it's the standard one for files, `<code>files</code>.
The function is the basic low-level one for completing files, too; it's
described below, but you already know a lot about the effect since it's
the completion system's workhorse which you use it all the time without
realising. Actually, it will supply its own tags, but that doesn't
matter since they will silently override what we say.</p>
<p>The second possibility is the new one we're adding. I've therefore
invented a suitable tag `<code>subdirs</code>', a description, `<code>subdirectory search</code>', and the name of the function I'm going to supply to do the
completion. This is quite simple:</p>
<pre><code> _perforce_subdir_search() {
compset -P '*/'
compadd &quot;$@&quot; '...'
}
</code></pre>
<p>The first line tells the completion system to ignore anything up to the
last `<code>/</code>'. That's so we can append a `<code>...</code>' to any directory which
already exists on the command line. The builtin <code>compset</code> does various
low-level transformations of this time. Note that the <code>-P</code> is `greedy'
--- it looks for the longest possible pattern match, which is the usual
default in zsh and other UNIX pattern matchers.</p>
<p>The second line actually adds the `<code>...</code>' as a completion; <code>compadd</code> is
the key builtin for the whole completion system. I've actually passed
some on the arguments which we got to `<code>_perforce_subdir_search</code>' via
`<code>&quot;$@&quot;</code>'. In fact, looking back it seems as if there weren't any!
However, <code>_alternative</code> actually passed some behind my back --- and it's
a good thing, too, since it's exactly those arguments that give the tag
`<code>subdirs</code>' and the description `<code>subdirectory search</code>'. So that extra
`<code>&quot;$@&quot;</code>' is actually quite important. The buck stops here; there's
nothing below <code>compadd</code>. A function of this simplest only works well
when the handling of tags and contexts has already been done; but we
just saw that <code>_alternative</code> did that, so as long as we always call
<code>_perforce_subdir_search</code> suitably, we're in the clear.</p>
<p><strong>Different types of file, part 2</strong></p>
<p>Furthermore, a Perforce file specification can look like a normal UNIX
file path, or it can look like:</p>
<pre><code> //depot/dirs/moredirs/file
</code></pre>
<p>(don't get confused with paths to network resources, which also use the
doubled slash or backslash on some systems, notably Cygwin). We could
use <code>_alternative</code> to handle this, too, and if I was writing <code>_perforce</code>
again I probably would for simplicity. However, I decided to do it just
by testing for the `<code>//</code>' in <code>_perforce_files</code>. This means that the
structure of <code>p4_files</code> so far looks like:</p>
<pre><code> if [[ $PREFIX = //* ]]; then
# ask Perforce for files that match
local -a altfiles
altfiles=(
'depot-files:file in depot:_perforce_depot_files'
depot-dirs:directory in depot:_perforce_depot_dirs'
)
# add other alternatives, such as the `...' thing
altfiles=($altfiles
&quot;subdirs:subdirectory search:_perforce_subdir_search&quot;
)
_alternative $altfiles
else
_alternative \
&quot;files:file:_path_files&quot; \
&quot;subdirs:subdirectory search:_perforce_subdir_search&quot;
fi
</code></pre>
<p>where we are still to write the functions for the first two alternatives
in the first branch; the `<code>...</code>' is still valid for that branch, so
I've added that as the third alternative. I've used the array
<code>$altfiles</code> because, actually, the structure is more complicated than
I've shown; doing it this way makes it easier to add different sets of
alternatives.</p>
<p>The choice of which branch is made by examining the <code>$PREFIX</code> special
variable, which contains everything (well, everything interesting) that
comes before the cursor position in the word being completed. There is a
counterpart <code>$SUFFIX</code> which we will see in a moment. The `almost
everything' comes because sometimes we definitely don't want to see the
whole <code>$PREFIX</code>. Completing the three dots was such as case --- we
didn't want to see anything up to the last <code>/</code>. What that `<code>compset -P '*/'</code>' actually did was move the matched pattern from the front of
<code>$PREFIX</code> to the end of <code>$IPREFIX</code>, another special parameter which
contains parts of the completion we aren't currently interested in, but
which are still there. This allows us to concentrate on a particular
part of the completion. However you do that --- whether by <code>compset</code> or
directly manipulating <code>$PREFIX</code> and friends --- the completion system
usually restores the parameters when you exit the function where you
altered them. This fits in nicely with what we're doing here with
<code>_alternative</code> --- if we handle adding `<code>...</code>' by ignoring everything
up to the last slash, for example, we don't want the next completion we
try to continue to ignore that; other file completions will want to look
at the directory path.</p>
<p>`Depot' is Perforce's name for what CVS calls a repository --- the
central location where all versions of all files are stored, and from
where they are retrieved when you ask to look at one. I've separated out
`<code>depot-dirs</code>' and `<code>depot-files</code>' for various reasons. First, the
commands to examine files and directories are different, so the
completion function is different. Second, we can offer different tags
for files and directories --- this is what <code>_path_files</code> does for normal
UNIX files. Third, it will later allow us more control --- some commands
only operate on directories. Here's <code>_perforce_depot_files</code>;
<code>_perforce_depot_dirs</code> is extremely similar:</p>
<pre><code> _perforce_depot_files() {
# Normal completion of files in depots
local pfx=${(Q)PREFIX} expl
local -a files
compset -P '*/'
files=(${${${(f)&quot;$(\
_call_program files p4 files \
\&quot;\$pfx\*\$\{\(Q\)SUFFIX\}\&quot; 2&gt;/dev/null)&quot;}%\#*}##*/})
[[ $#files -eq 1 &amp;&amp; $files[1] = '' ]] &amp;&amp; files=()
compadd &quot;$@&quot; -a files
}
</code></pre>
<p>A little messy (and still not quite the full horror). I've split the key
line in the middle which fetches the list from Perforce to make it fit.
If you ploughed through chapter 5, you'll recognised what's going on
here --- we're reading a list of files, one per line, from the command
`<code>p4 files</code>', and we're stripping off the directory at the front, and
everything from a `<code>#</code>' on at the end. The latter is a revision number;
we're not handling those at this point, though we will later.</p>
<p>Notice the way I remembered <code>$PREFIX</code> before I told the system to ignore
it for the word we're now completing. I remembered it as
`<code>${(Q)PREFIX}</code>' in order to remove any quotes from the name. For
example, if the name on the line so far had a space, <code>$PREFIX</code> (which
comes from what is on the command line without any quotes being
stripped) would have the space quoted somehow, e.g. `<code>name\ with\ space</code>'. We arrange for <code>$pfx</code> to contain `<code>name with space</code>', which is
how Perforce knows the file, using the <code>(Q)</code> parameter flag. We then
pass the argument <code>&quot;$pfx*${(Q)SUFFIX}&quot;</code> to `<code>p4 files</code>'; this generates
matching files internally. The extra layer of backslash-quoting is for
the benefit of <code>_call_program</code>, which re-evaluates its arguments; this
ensures the argument is expanded at the point it gets passed to <code>p4 files</code>. All this goes to show just how difficult getting the quoting
right can be.</p>
<p>Once we've got the list of bare filenames, we check to see if the list
is just one element with no length. That's an artefact of the the
<code>&quot;$(cmd)&quot;</code> syntax; if the output is empty, because its quoted you still
get one zero-length string output, which we don't want.</p>
<p>Finally, we pass the result to <code>compadd</code> as before. Again, tags and the
description have already been handled and we just need to make sure the
appropriate options get passed in with <code>&quot;$@&quot;</code>. This time we use the
`<code>-a</code>' option which tells <code>compadd</code> that any arguments are array name,
not a list of completions. This is more efficient; compadd only needs to
expand the array internally instead of the shell passing a potentially
huge list to the builtin.</p>
<p><strong>Handling extra bits on a completion</strong></p>
<p>`Extra bits' on a completion could be anything; common examples include
an extra value for a comma-separated list (the <code>_values</code> functions is
for this), or some kind of modifier applied to the completion you have
already. We've already seen an example, in fact, since the principle of
handling the directory and basename parts of a file is very similar. The
phrase `extra bits' may already alert you to the fact that we are
heading towards the deeper recesses of completion.</p>
<p>Anyway, here's how we tack a revision or change number onto the end of a
file.</p>
<p>I'll stick with revisions: `<em>filename</em><code>#</code><em>revision</em>', where <em>revision</em>
is a number. For the full sophistication, there are three steps to this.
First, make it easy for the user to add `<code>#</code>' to an existing filename;
second, recognise that a `<code>#</code>' is already there so that revisions need
to be completed; third, find out the actual revisions which can be
completed. As a revision is just a number, you might think completing it
was a bit pointless. However, given the sophistication of zsh's
completion system there's actually one very good reason --- we can
supply a description with the revisions, so that the user is given
information about the revisions and can pick the right one without
running some external command to find out. There was the same sort of
rationale behind the `<code>-d</code>' option to <code>p4 diff</code>; there was just one
letter to type, but zsh was able to generate extra information to
describe the possibilities, so it wasn't just laziness.</p>
<p>First part: make it easy for the user to add the `<code>#</code>'. This actually
depends on a new feature in version 4.1 of zsh; in 4.0 you couldn't play
the trick we need or grabbing the keyboard input after a completion was
finished unless you specified a particular suffix to add to the
completion (such as the `<code>/</code>' after a directory --- this is
historically where this feature came from).</p>
<p>The method is to add an extra argument everywhere we complete a file
name. For example, change the <code>compadd</code> in <code>_perforce_depot_files</code> to:</p>
<pre><code> compadd &quot;$@&quot; -R _perforce_file_suffix -a files
</code></pre>
<p>where the option argument specifies a function:</p>
<pre><code> _perforce_file_suffix() {
[[ $1 = 1 ]] || return
if [[ $LBUFFER[-1] = ' ' ]]; then
if [[ $KEYS = '#' ]]; then
# Suffix removal with an added backslash
LBUFFER=&quot;$LBUFFER[1,-2]\\&quot;
elif [[ $KEYS = (*[^[:print:]]*|[[:blank:]\;\&amp;\|@]) ]]; then
# Normal suffix removal
LBUFFER=&quot;$LBUFFER[1,-2]&quot;
fi
fi
}
</code></pre>
<p>This has been simplified, too; I've ignored revision ranges in the form
<em>file</em><code>#</code><em>rev1</em><code>,</code><em>rev2</em>. However, I've handled changes (`<code>@</code>'
following a filename) as well as revisions. You'll see this function
looks much more like a zle widget rather than a completion widget ---
which is exactly what it is; it's not called as part of the completion
system at all. After the specified completion, zle reads in the next
keystroke, which is stored in <code>$KEYS</code>, and calls this function as a zle
widget. This means it can manipulate the line buffer; we only need to
look at what is at the left of the cursor, stored in <code>$LBUFFER</code>.</p>
<p>The function is called with the length of the suffix added to the
function. In this case, it's just a space --- we've finished a normal
completion, so the system has automatically added a space to what's on
the command line. We therefore check we've just got one single character
in the suffix, to avoid getting confused.</p>
<p>Next, we look at what's immediately left of the cursor, which is the
last character in <code>$LBUFFER</code>, i.e. <code>$LBUFFER[-1]</code>, to make sure this is
a space.</p>
<p>If everything looks OK, we consider the keys typed and decide whether to
modify the line. You may already have noticed that in some cases zsh
automatically removes that space by itself; for example, if you hit
return --- or any other non-printing character --- or if it's a
character that terminates a command such as `<code>&amp;</code>' or `<code>;</code>'. We emulate
that behaviour --- most of the second test is simply to do that. The
only differences from normal are if the key typed was `<code>@</code>' or `<code>#</code>'.</p>
<p>The `<code>@</code>' is simple --- we just remove the last character, the same as
we do for the other characters. For `<code>#</code>', however, we also add a
backslash to the command line before the `<code>#</code>'. That's because `<code>#</code>'
is a special character with extended globbing, and the completion system
generally runs with extended globbing switched on. Adding the backslash
means the user doesn't have to; it's never harmful.</p>
<p>To show the next effect, suppose we complete a file name:</p>
<pre><code> p4 diff fil&lt;TAB&gt;
</code></pre>
<p>to get:</p>
<pre><code> p4 diff filename _
</code></pre>
<p>where `<code>_</code>' shows the cursor position, and then typed `<code>#</code>'; we would
get:</p>
<pre><code> p4 diff filename\#
</code></pre>
<p>with the cursor right at the end.</p>
<p>So far so good. For the second step, we need to modify <code>_perforce_files</code>
to spot that there is a `<code>#</code>' on the line before the cursor, and to
call the revision code. To do this we add an extra branch at the start
of the `<code>if</code>' in <code>_perforce_files</code> --- at the start, because any `<code>#</code>'
before the cursor forces us to look at revisions, so this takes
precedence over the other choices. When this is added, the code will
look like:</p>
<pre><code> if [[ -prefix *\# ]]; then
_perforce_revisions
elif [[ $PREFIX = //* ]]; then
# as before.
</code></pre>
<p>In fact, that <code>-prefix</code> test is just a fancy way of saying the same
thing as the `<code>[[ $PREFIX = *\# ]]</code>' and if I wasn't so hopelessly
inconsistent I would have written both tests the same.</p>
<p>So now the third step: write <code>_perforce_revisions</code> to complete revisions
numbers with the all-important descriptions.</p>
<pre><code> _perforce_revisions() {
local rline match mbegin mend pfx
local -a rl
pfx=${${(Q)PREFIX}%%\#*}
compset -P '*\#'
# Numerical revision numbers, possibly with text.
if [[ -z $PREFIX || $PREFIX = &lt;-&gt; ]]; then
# always allowed (same as none)
rl=($rl 0)
_call_program filelog p4 filelog \$pfx 2&gt;/dev/null |
while read rline; do
if [[ $rline = (#b)'... #'(&lt;-&gt;)*\'(*)\' ]]; then
rl=($l &quot;${match[1]}:${match[2]}&quot;)
fi
done
fi
# Non-numerical (special) revision names.
if [[ -z $PREFIX || $PREFIX != &lt;-&gt; ]]; then
rl=($rl 'head:head revision' 'none:empty revision'
'have:current synced revision')
fi
_describe -t revisions 'revision' rl
}
</code></pre>
<p>Thankfully, a lot of the structure of this is already familiar. We
extract the existing prefix before the `<code>#</code>', being careful about
quoting --- this is the filename for which we want a list of revisions.
We ignore everything in the command argument before the `<code>#</code>'. After
generating the completions, we use the <code>_describe</code> function to add them
with the tag `<code>revisions</code>' and the description `<code>revision</code>'.</p>
<p>The main new part is the loop over output from `<code>p4 filelog</code>', which is
the Perforce command that tells us about the revisions of a file. We
extract the revision number and the comment from the line using
backreferences (see previous chapter) and weld them together with a
colon so that <code>_describe</code> will be able to separate the completion from
its description. Then we add a few special non-numerical revisions which
Perforce allows, and pass this list down to <code>_describe</code>. The extra
<code>if</code>'s are a very minor optimization to check if we are completing a
numerical or non-numerical revision.</p>
<p><span id="l181"></span></p>
<h3 id="684-the-rest"><a class="header" href="#684-the-rest">6.8.4: The rest</a></h3>
<p>It's obvious that this tutorial could expand in any number of
directions, but as it's really just to point out some possibilities and
directions, that would would miss the point. So the rest of this chapter
takes the completion system apart and looks at the individual
components. It should at least now be a bit more obvious where each
component fits.</p>
<p><span id="l182"></span></p>
<h2 id="69-writing-new-completion-functions-and-widgets"><a class="header" href="#69-writing-new-completion-functions-and-widgets">6.9: Writing new completion functions and widgets</a></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
in more detail than I did in the tutorial. However, I'll try to do it in
such a way that you don't need to know every single detail. 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 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>
<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 a function that completes files ending in
<code>.gz</code> (the supplied function which does this has now changed), 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>:</p>
<pre><code> #compdef gunzip zcat
local expl
_description files expl 'compressed file'
_files &quot;$expl[@]&quot; -g '*.[gG][zZ]'
</code></pre>
<p>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>
<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>
<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 do 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):</p>
<pre><code> fpath=(~/funcs $fpath)
</code></pre>
<p>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>
<p><span id="l183"></span></p>
<h3 id="691-loading-completion-functions-compdef"><a class="header" href="#691-loading-completion-functions-compdef">6.9.1: Loading completion functions: <code>compdef</code></a></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>
<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>
<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>
<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 &lt;_function&gt; &lt;command-to-handle&gt;</code>' to <code>.zshrc</code> after the call to
<code>compinit</code>.</p>
<p>It's also high time I mentioned an easy way of using the completion
already defined for an existing function: `<code>compdef newcmd=oldcmd</code>'
tells the completion system that the completion arguments for
`<code>newcmd</code>' are to be the same as the ones already defined for
`<code>oldcmd</code>'; it will complain if nothing is known about completing for
<code>oldcmd</code>. This works recursively; you can now define completions in
terms of that for <code>newcmd</code>. If you happen to know the name of the
completion function called, you can use that; the following three lines
are broadly equivalent:</p>
<pre><code> compdef $_comps[typeset] foo
compdef _vars_eq foo
compdef foo=typeset
</code></pre>
<p>since the completion for <code>typeset</code> is stored in <code>$_comps</code> along with all
the others, and this happens to resolve to <code>_vars_eq</code>; but the last
example is easier and safer and the intention more obvious. The manual
refers to <code>typeset</code> here as a `service' for <code>foo</code> (guess what the shell
stores in the associative array element <code>$_services[foo]</code>).</p>
<p>There's actually more to services: when a function is called, the
parameter <code>$service</code> is set. Usually this will just be the name of the
command being completed for, or one of the special contexts like
`<code>-math-</code>'. However, in a case like the last <code>compdef</code> in the list
above, the service will be <code>typeset</code> even though the command name may be
`<code>foo</code>'.</p>
<p>This is also used in `<code>#compdef</code>' lines. The top of `<code>_gzip</code>'
contains:</p>
<pre><code> #compdef gzip gunzip gzcat=gunzip
</code></pre>
<p>which says that the file provides two services, for <code>gzip</code> and <code>gunzip</code>,
and also handles completion for <code>gzcat</code>, but with the service name
<code>gunzip</code>. Only a few of the completion functions actually care what
service they provide (you can check, obviously, by looking to see if
they refer to <code>$service</code>); but you may have uses for this. Note that if
you define services with a <code>compdef</code> command, <em>all</em> the arguments must
be in the <em>foo</em><code>=</code><em>bar</em> form; the mixed form is only useful after a
<code>#compdef</code> inside completion functions.</p>
<p><span id="l184"></span></p>
<h3 id="692-adding-a-set-of-completions-compadd"><a class="header" href="#692-adding-a-set-of-completions-compadd">6.9.2: Adding a set of completions: <code>compadd</code></a></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:</p>
<pre><code> _foo() { compadd Yan Tan Tethera; }
compdef _foo foo
</code></pre>
<p>Now type `<code>foo </code>' and experiment with completions after it. If only
it were all that simple.</p>
<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 `<strong>Completion Widgets</strong>'
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 &lt;description&gt;</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>
<p><code>-P &lt;prefix&gt;</code> and <code>-S &lt;suffix&gt;</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>
<p><code>-J &lt;group&gt;</code> is the way group names are specified, used by the
<code>group-name</code> tag; there is also <code>-V &lt;group&gt;</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 useful
where you need to have unquoted metacharacters in the final completion.
It is also useful when you are completion something where the result
isn't going to be expanded by the shell.</p>
<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>
<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>
<p><span id="l185"></span></p>
<h3 id="693-functions-for-generating-filenames-etc"><a class="header" href="#693-functions-for-generating-filenames-etc">6.9.3: Functions for generating filenames, etc.</a></h3>
<p>However, for most types of completion the possibilities 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></p>
<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>
<p>For more specific use, you can give it various options: `<code>-/</code>' means
complete directories, and, as you saw, `<code>-g &quot;&lt;pattern&gt;&quot;</code>' gives a
filename generation pattern to produce matching files.</p>
<p>A couple of other options, which can be combined with the ones above,
are worthy of mention. If you use `<code>-W &lt;dir&gt;</code>', then completion takes
place under directory <code>&lt;dir</code>&gt; rather than in the current directory ---
it has no effect if you are using an absolute path. Here, `<code>&lt;dir&gt;</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</code>', you can do this:</p>
<pre><code> local oomph_dirs
oomph_dirs=(. /usr/local/oomph)
_files -W oomph_dirs -g '*.mph'
</code></pre>
<p>--- 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>
<p>The system that implements <code>$fignore</code> and the <code>ignored-patterns</code> style
can be intercepted, if you need to, with the option `<code>-F &quot;&lt;pat&gt;&quot;</code>';
`<code>&lt;pat&gt;</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-patterns</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>
<p>In addition, <code>_files</code> also takes many of the standard completion options
which apply to <code>compadd</code>, for convenience.</p>
<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>. Because it doesn't handle
the tags, <code>_path_files</code> is too lowly to do the usual tricks with label
loops, i.e. pretending `<code>dog:-setter</code>' is a tag `<code>dog-setter</code>' with
the usual completions for `<code>dog</code>'; likewise, it doesn't implement the
<code>file-patterns</code> style. So you need to know what you're doing when you
use it directly.</p>
<p><strong>Parameters and options</strong></p>
<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. Furthermore, they are
all at a high enough level to handle tags with labels: to translate that
into English, you can use them directly without any of the preprocessing
described later on which are necessary to make sure the styles dealing
with tags are respected.</p>
<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></p>
<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>
<p><span id="l186"></span></p>
<h3 id="694-the-zshparameter-module"><a class="header" href="#694-the-zshparameter-module">6.9.4: The <code>zsh/parameter</code> module</a></h3>
<p>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>. 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. Note in particular <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>
<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>
<ul>
<li><strong><code>$aliases</code>, <code>$dis_aliases</code>, <code>$galiases</code></strong><br />
The keys of these arrays give ordinary aliases, disabled ordinary
aliases for those where you have done <code>disable -a &lt;alias&gt;</code> to turn
them off temporarily, and global aliases as defined with <code>alias -g</code>.</li>
<li><strong><code>$builtins</code>, <code>$dis_builtins</code></strong><br />
The keys give active and disabled shell builtin commands.</li>
<li><strong><code>$commands</code></strong><br />
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.</li>
<li><strong><code>$functions</code>, <code>$dis_functions</code></strong><br />
The keys are active and disabled shell functions.</li>
<li><strong><code>$history</code></strong><br />
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.</li>
<li><strong><code>$jobtexts</code>, <code>$jobdirs</code>, <code>$jobstates</code></strong><br />
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.</li>
<li><strong><code>$modules</code></strong><br />
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.</li>
<li><strong><code>$nameddirs</code></strong><br />
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.</li>
<li><strong><code>$options</code>, <code>$parameters</code></strong><br />
The keys give shell options and parameters, and are used by the
functions <code>_options</code> and <code>_parameters</code> for completion, so you will
mostly not need to refer to them directly.</li>
<li><strong><code>$userdirs</code></strong><br />
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.</li>
</ul>
<p>Now here are the ordinary arrays, which you would therefore refer to
simply as <code>${reswords}</code> etc.</p>
<ul>
<li><strong><code>$dirstack</code></strong><br />
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.</li>
<li><strong><code>$funcstack</code></strong><br />
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.</li>
<li><strong><code>$historywords</code></strong><br />
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.</li>
<li><strong><code>$reswords</code>, <code>$dis_reswords</code></strong><br />
The active and disabled reserved words (effectively syntactically
special commands) understood by the shell.</li>
</ul>
<p><strong>Other ways of getting at information</strong></p>
<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>
<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:</p>
<pre><code> print ${${(f)&quot;$(limit)&quot;}%% *}
</code></pre>
<p>which you can test does the right thing. Here's a translation:
<code>&quot;$(limit)&quot;</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>
<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>
<p><span id="l187"></span></p>
<h3 id="695-special-completion-parameters-and-compset"><a class="header" href="#695-special-completion-parameters-and-compset">6.9.5: Special completion parameters and <code>compset</code></a></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>
<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>
<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>
<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*$SUFFIX</code>.</p>
<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>
<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</p>
<pre><code> if compset -P &quot;*/&quot;; 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
</code></pre>
<p>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>&lt;N&gt;</code> between the
<code>-P</code> and the pattern, which says to move only up to the <code>&lt;N&gt;</code>th such
match; here, that would be a pattern with exactly <code>&lt;N&gt;</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>
<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:</p>
<pre><code> if [[ -prefix */ ]]; then
# same as with `compset -P &quot;*/&quot;', except prefixes were left alone.
fi
</code></pre>
<p>These have the advantage of looking like all the standard tests
understood by the shell.</p>
<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 &quot;echo hi&quot;</code>', the
word <code>&quot;echo hi&quot;</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>
<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>
<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 <strong>Zsh Line Editor</strong> 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>
<p>Here are a few examples of using special parameters and <code>compset</code>.</p>
<p>One of the shortest standard completions is this, <code>_precommand</code>:</p>
<pre><code> #compdef - nohup nice eval time rusage noglob nocorrect exec
shift words
(( CURRENT-- ))
_normal
</code></pre>
<p>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>
<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>&lt;user&gt;@&lt;host&gt;</code>, and it's used
anywhere the <code>user-hosts</code> style, described above, is appropriate:</p>
<pre><code> 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
</code></pre>
<p>We test to see if there is already a `<code>&lt;user&gt;@</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>
<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.</p>
<pre><code> local file
file=($~PREFIX*$~SUFFIX(om[${NUMERIC:-1}]N))
(( $#file )) &amp;&amp; compadd -U -i &quot;$IPREFIX&quot; -I &quot;$ISUFFIX&quot; -f -Q - $file
</code></pre>
<p>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>
<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, so if you
need to keep it you have to pass it back to <code>compadd</code>. For example,
suppose you were in a context where you were completing after
`<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 &quot;$IPREFIX&quot;</code>' to make sure it's retained. The same argument goes
for the ignored suffix. However, there's currently no way of getting
<code>_most_recent_file</code> to work on only a part of a string, so this
explanation really only applies when you call it from another completion
function, not directly from the command line.</p>
<p><span id="l188"></span></p>
<h3 id="696-fancier-completion-using-the-tags-and-styles-mechanism"><a class="header" href="#696-fancier-completion-using-the-tags-and-styles-mechanism">6.9.6: Fancier completion: using the tags and styles mechanism</a></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></p>
<p>The simplest way of making your own completion function recognize tags
is to 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,</p>
<pre><code> local expl
_description files expl 'my special files'
_files &quot;$expl[@]&quot;
</code></pre>
<p>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>
<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
unconditionally to say so, irrespective of tags etc.; the function
<code>_message</code> does this, taking the message as its sole argument.</p>
<p>There are two levels above that; these implement the tags mechanism in
full. In <code>_description</code>, all that happens is that the user is informed
what tag is coming up; there's no check what preferences the user has
for tags (the first level), nor whether he wants tags to be split up
using the labelling mechanism, e.g. picking out certain sorts of files
using the labelled tag `<code>file:-myfiles</code>' to get the final tag
`<code>file-myfiles</code>' (the second level).</p>
<p>To get this for simple cases you use the function <code>_wanted</code>. Unlike
<code>_description</code>, it's an interface to the function that generates
completion as well as a handler for tags --- that's so it can loop over
the generated tags, checking the labels. The call above would now look
like this:</p>
<pre><code> _wanted files expl 'my special files' _files
</code></pre>
<p>Note that you now don't pass the <code>&quot;$expl[@]&quot;</code>, which hasn't even been
set yet; <code>_wanted</code> will generate the string using the parameter name you
say (here `<code>expl</code>', as usual), and assume that the function generating
the completions can use the result passed down to it. This is true of
pretty much anything you are likely to want to use.</p>
<p>Note also the fact you need to pass `<code>_files</code>', i.e. the function
generating the completion. You can put pretty much any command line
which generates completions here, down to a simple `<code>compadd</code>'
expression. The reason it has to be here is the tag labelling business:
<code>_wanted</code> could check whether the tag you specify, `<code>files</code>', is wanted
by the user and then return control to you, but it wouldn't be able to
split up and loop over labelled tags set in this case for the
<code>file-patterns</code> style and in other case by the <code>tag-order</code> style.</p>
<p>Unless you're really going into the bowels, <code>_wanted</code> is probably the
lowest level you will want to use. I'd suggest you remember that one,
and only go back and look at the other stuff if you need to do something
more complicated.</p>
<p>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 <code>_tags</code>
function without arguments does this. Finally, you need to use
<code>_requested</code>, which works a bit like <code>_wanted</code> but is made to fit inside
the loop we are using. The end result looks like this:</p>
<pre><code> local expl ret=1
_tags foo bar rod
while _tags; do
_requested foo expl &quot;This is the description for tag foo&quot; \
compadd all foos completions &amp;&amp; ret=0
_requested bar expl &quot;This is the description for tag bar&quot; \
compadd all bars completions &amp;&amp; ret=0
_requested rod expl &quot;This is the description for tag rod&quot; \
compadd all rods completions &amp;&amp; ret=0
(( ret )) || return 0 # leave if matches were generated
done
</code></pre>
<p>If you do include the completion function line as arguments, the loop
over labels for the tag you specify is automatically handled as with
<code>_wanted</code>. It may be a little confusing that both <code>_requested</code> and
<code>_wanted</code> exist: the specific difference is that with <code>_requested</code> you
call the <code>_tags</code> function yourself, whereas <code>_wanted</code> assumes the only
valid tag is its argument and acts accordingly, and can be used only for
simple, `one-shot' completions.</p>
<p>With <code>_requested</code>, unlike <code>_wanted</code>, you can separate out the arguments
to the completion generator itself --- here <code>compadd</code> --- into a
different statement, remembering the <code>&quot;$expl[@]&quot;</code> argument in that case.
You can miss out the second and third arguments for <code>_requested</code> in this
way. This time the loop which generates labels for tags is not
performed, and you have to arrange it yourself, with the usual trade off
of greater complexity for greater flexibility. To do this, there are two
other functions: <code>_all_labels</code> and <code>_next_label</code>. The simpler case is
with <code>_all_labels</code>, which just implements the loop over the labels using
the same arguments as <code>_wanted</code>:</p>
<pre><code> _requested values &amp;&amp;
_all_labels values expl 'values for my special things' \
compadd alpha bravo charlie delta echo foxtrot.
</code></pre>
<p>In case you haven't understood (and it's quite complicated, I'm afraid):
the <code>_requested</code> looks at whether the tag you use has been asked for by
the user. Having found out that it is, the <code>_all_labels</code> function calls
the command <code>compadd</code> which actually adds the completions, but it does
it in such a way as to take account of labelled tags --- you might have
both a plain `<code>values</code>' tag and `<code>values:-special</code>' labelled tag, and
<code>_all_labels</code> is needed to decide which is being used here. This last
example is actually exactly what <code>_requested</code> does when given the
<code>compadd</code> as argument, so it's only really useful when there is some
code between the <code>_requested</code> and the <code>_all_labels</code>, for example to
compute the strings to complete.</p>
<p>The most complicated case you are likely to come across is when inside
the part of the tags loop which handles a particular tag (i.e. the
<code>_requested</code> lines in the example above), you actually want to add more
than one possible sort of completion. Then <code>_all_labels</code> is no longer
enough, because completion needs to sort out the different things which
are being added. This can also happen when there is only one valid tag,
but that has multiple completions so that <code>_wanted</code> isn't any use. In
this case you need to use <code>_next_label</code> inside a loop, which, as its
names suggests, fixes up labels for the current tag and stops when it's
found the right one. Here's a stripped down example which handles
completion of messages from the <code>MH</code> mail handling system; you'll find
it complete inside the function <code>_mh</code>.</p>
<pre><code> _tags sequences
while _tags; do
while _next_label sequences expl sequence; do
compadd &quot;$expl[@]&quot; $(mark $foldnam 2&gt;/dev/null |
awk -F: '{ print $1 }') &amp;&amp; ret=0
compadd &quot;$expl[@]&quot; reply next cur prev \
first last all unseen &amp;&amp; ret=0
_files &quot;$expl[@]&quot; -W folddir -g '&lt;-&gt;' &amp;&amp; ret=0
done
(( ret )) || return 0
done
</code></pre>
<p>Here's what's going on. The <code>_tags</code> call works just as it did in the
first example I showed for that, deciding whether the tag in question,
<code>sequences</code>, has been asked for; the tag name comes because MH allows
you to define sets of messages called exactly `sequences'. The first
`<code>while</code>' selects all values from <code>tag-order</code> where the `<code>sequences</code>'
tag appears, with or without a label. The second `<code>while</code>' loop then
sorts out any occurrences of labelled sequences to be presented to the
user at the same time, i.e. given in the same element of the <code>tag-order</code>
value array. The first <code>compadd</code> extracts from the folder (MH's name for
a directory) identified by the function the names of any sequences you
have defined; the second adds a lot of standard sequences --- although
strictly speaking <code>unseen</code> isn't a standard sequence since you can name
it yourself in <code>~/.mh_profile</code>. Finally, the third adds files in the
folder itself whose names are just digits, which is how MH stores
messages. The handling of <code>return</code> makes sure it stops as soon as you
have matches for one particular element of <code>tag-order</code>; if you put it in
the inner loop, you would just have the first of those sets that
happened to be generated, while here, if you specify that all types of
sequence should appear in the same completion list, they are all
correctly collected.</p>
<p>Why, in that last example, is there no call to <code>_requested</code>, now I've
gone to the trouble of explaining what that does? The answer is that
there is only one tag; <code>_tags</code> can decide if we want it at all, and
after that the tag is known, so we don't need <code>_requested</code> to find that
information out for us. It's only needed if there is more than one type
of match --- indeed, that's why we introduced it, so this is not
actually a new complication, although you can be forgiven for thinking
otherwise.</p>
<p>Here's an example of using that code for sequences. You might decide
that you only want to see named sequences unless there aren't any,
otherwise ordinary messages. You could do this by setting your styles as
follows:</p>
<pre><code> zstyle ':completion:*' tag-order sequences:-name sequences:-num
zstyle ':completion:*:sequences-name' ignored-patterns '(|,)&lt;-&gt;'
zstyle ':completion:*:sequences-num' ignored-patterns '^&lt;-&gt;'
</code></pre>
<p>which tries <code>sequences</code> under the labels <code>sequences-name</code> and
<code>sequences-num</code>; which ignore completions which are all digits, and
those which are not all digits, respectively. The slight twiddle in the
pattern for <code>sequences-name</code> ignores messages marked for deletion as
well, which have a comma stuck in front of the number (this is
configurable, so your version of MH may be different).</p>
<p>All of <code>_description</code>, <code>_wanted</code>, <code>_requested</code>, <code>_all_labels</code> and
<code>_next_label</code> take the options <code>-J</code> and <code>-V</code> 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>
<p>If your requirements are simple enough, you can replace that <code>_tags</code>
loop above with a single function, <code>_alternative</code>. This takes a series
of arguments each in the form `&lt;tag&gt;:&lt;description&gt;:&lt;action&gt;',
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>-&gt;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:</p>
<pre><code> local tmpcdpath
tmpcdpath=(${(@)cdpath:#.})
_alternative \
'local-directories:local directories:_path_files -/' \
'path-directories:directories in cdpath:
_path_files -W tmpcdpath -/'
</code></pre>
<p>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>
<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>&lt;action&gt;</code> part of the
arguments to <code>_alternative</code>.</p>
<p><strong>How to look up styles</strong></p>
<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. However, by the same token don't
try to squeeze too much meaning into one style, which will force the
user to narrow the context --- it's always much easier to set a style
for the general context `<code>:completion:*</code>' than to have to worry about
all the circumstances where you need a particular value.</p>
<p>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:</p>
<pre><code> zstyle -b &quot;:completion:${curcontext}:tag&quot; style-name parameter
</code></pre>
<p>If the tag is irrelevant, you can leave it empty, but you still need the
final colon since there should always be six in total. 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>
<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>
<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>, and <code>-a</code> specify boolean
(<code>parameter</code> is either <code>yes</code> or <code>no</code>), scalar (<code>parameter</code> is a scalar),
and array (<code>parameter</code> is an array, which may still be a single word, of
course), You can retrieve an associative array with <code>-a</code> as long as the
parameter has already been declared as one.</p>
<p>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>
<p>Typical usages are thus:</p>
<pre><code> if zstyle -t &quot;:completion:${curcontext}:&quot; foo; then
# do things in a fooish way
else
# do things in an unfooish way
fi
</code></pre>
<p>or to use the value:</p>
<pre><code> local val
if zstyle -s &quot;:completion:${curcontext}:&quot; foo val; then
# use $val to establish how fooish to be
else
# be defaultly fooish
fi
</code></pre>
<p><span id="l189"></span></p>
<h3 id="697-getting-the-work-done-for-you-handling-arguments-etc"><a class="header" href="#697-getting-the-work-done-for-you-handling-arguments-etc">6.9.7: Getting the work done for you: handling arguments etc.</a></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. The
good news is that all the higher functions here handle tags and labels
internally, so you don't need to worry about <code>_tags</code>, <code>_wanted</code>,
<code>_requested</code>, etc. There's one exception: the `state' mechanism to be
described, where a function signals you that you're in a given state
using the parameter <code>$state</code>, expects you to handle tag labels yourself
--- pretty reasonable, as you have requested that the function return
control to you to generate the completions. I've mentioned that here so
that I don't have to gum up the description of the functions in this
section by mentioning it again.</p>
<p><strong>Handling ordinary arguments</strong></p>
<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>
<p>The basic usage is to call it with a series of arguments (which I'll
call `specifications') like:</p>
<pre><code> &lt;where I am&gt;:&lt;description&gt;:&lt;what action to take&gt;
</code></pre>
<p>although there are a whole series of more complicated possibilities.</p>
<p>The initial `<code>&lt;where I am&gt;</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>&lt;where I am&gt;</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>
<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>
<p>The action can have various forms, chosen to be easily distinguishable
from one another.</p>
<ol>
<li>
<p>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>.</p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>A completion function to call, with any arguments, such as `<code>_files -/</code>' to complete directories. Usually this does the business with
<code>$expl</code> which should be familiar from the section on basic tag
handling, however you can put an extra space in front of the action
to have it called exactly as is, after word splitting.</p>
</li>
<li>
<p>A word preceded by `<code>-&gt;</code>' for example `<code>-&gt;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>-&gt;</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>
<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-&lt;option&gt;-&lt;arg&gt;</code>,
for example <code>option-file-1</code> for the first argument of the
<code>option-file</code> option, or <code>argument-N</code>, for example <code>argument-2</code> for
the second argument of the command.</p>
<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.</p>
</li>
<li>
<p>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.</p>
</li>
</ol>
<p>These are the main possibilities, but I have not described every
variation. As always, you should see the manual for all the detail.</p>
<p>Here's a concocted example for that `<code>-&gt;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>'.</p>
<pre><code> local context state line
typeset -A opt_args
_arguments '-type[specify type]:type:-&gt;type' \
'*:greek letter:-&gt;gklet' &amp;&amp; return 0
case $state in
(type) compadd normal unusual &amp;&amp; return 0
;;
(gklet) compadd alpha beta gamma &amp;&amp; return 0
;;
esac
return 1
</code></pre>
<p>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>
<p>I haven't shown the gory tag handling; as it's written, you'll see that
no tag is ever defined for the <code>compadd</code> arguments shown. In this case
you could just use <code>_wanted</code>. What you get for free with arguments,
however, is the context: in the first case, you would have
`<code>:option-type-1</code>' in the argument field (the second last, just before
the tag), and in the second case `<code>:argument-rest:</code>'. Go back to where
I originally described contexts if you've forgotten about these; I
didn't tell you at the time, but it's the <code>_argument</code> function that is
responsible for them. (However, you can supply a `<code>-C</code>' argument to
<code>_wanted</code> to tell that a context.)</p>
<p>A note about the form: that `<code>&amp;&amp; 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. I already
showed this in the section on tags, but you might have skipped that.</p>
<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 options 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></p>
<p>Option handling is broadly similar, with the `<code>&lt;where I am&gt;</code>' part just
giving the option name --- I already showed one example with `<code>-type</code>'
above. 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</p>
<pre><code> _arguments '-turnmeon'
</code></pre>
<p>for an option with no arguments,</p>
<pre><code> _arguments '-file:input file:_files'
</code></pre>
<p>for an option with one argument, or</p>
<pre><code> _arguments '-iofiles:input file:_files:output file:_files'
</code></pre>
<p>for an option with two arguments, both files but with different
descriptions.</p>
<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 descriptions 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:</p>
<pre><code> _arguments '-on[turn me on, why not]'
</code></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:</p>
<pre><code> _arguments '(-off)-on[turn me on, why not]' \
'(-on)-off[turn me off, please]'
</code></pre>
<p>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>
<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:</p>
<pre><code> _arguments '*-o[specify extra options]:option string:-&gt;option'
</code></pre>
<p>allows you to complete any number of `<code>-o &lt;option&gt;</code>' sets using the
<code>$state</code> mechanism. The <code>*</code> appears after any list of excluded options.</p>
<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,</p>
<pre><code> _arguments '-file=:input file:_files'
</code></pre>
<p>allows you to complete `<code>-file </code><em>&lt;filename&gt;</em>' or
`<code>-file=</code><em>&lt;filename&gt;</em>'. With</p>
<pre><code> _arguments '-file=-:input file:_files'
</code></pre>
<p>only the second is possible, i.e. the argument must be after the `<code>=</code>',
not in its own word.</p>
<p>You can handle optional and repeated arguments to options, too. This
illustrates some possibilities:</p>
<pre><code> _arguments '-option:first arg:-&gt;first::optional arg:-&gt;second'
</code></pre>
<p>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.</p>
<pre><code> _arguments '-option:first arg:-&gt;first:*:other args:-&gt;other'
</code></pre>
<p>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>.</p>
<pre><code> _arguments '-option:first arg:-&gt;first:*-:other args till -:-&gt;other'
</code></pre>
<p>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:</p>
<pre><code> cmdname -option &lt;first&gt; &lt;other1&gt; &lt;other2&gt; .... - &lt;remainder&gt;
</code></pre>
<p>where of course completion for <code>&lt;remainder&gt;</code> might be handled by other
specifications.</p>
<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>-``-prefix</code>'
on the command line is still handled as a single long option by
<code>_arguments</code>.</p>
<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>-``-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>' form, and even in many cases whether they
take an argument, and if so what type that is. It knows because
`<code>&lt;command&gt; -``-help</code>' often prints out a message like
`<code>-``-file=FILE</code>' which would tell <code>_arguments</code> (1) that `<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>
<p>You specify that the command in question works in this way by using the
(fairly memorable) option `<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>'; 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>'.</p>
<p>So for example, here is the completion for <code>gdb</code>, the GNU debugger,
which not surprisingly understands the GNU option format:</p>
<pre><code> _arguments -- '*=(CORE|SYM)FILE:core file:_files' \
'*=EXECFILE:executable:_files -g \*\(\*\)' \
'*=TTY:terminal device:compadd /dev/tty\*' &amp;&amp; return 0
</code></pre>
<p>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>
<p><span id="l190"></span></p>
<h3 id="698-more-completion-utility-functions"><a class="header" href="#698-more-completion-utility-functions">6.9.8: More completion utility functions</a></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>_call_function</code></strong></p>
<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:</p>
<pre><code> local ret # returned status from called function, if it was called
_call_function ret _hook_function arg1 arg2 &amp;&amp; return ret
# if we get here, _hook_function wasn't called,
# so do the default stuff.
</code></pre>
<p>As you can work out, <code>_call_function</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>
<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>_contexts</code></strong></p>
<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>_contexts</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>_contexts -math-</code>' to try mathematical completion, since
ordinary array subscripts can contain mathematical expressions.</p>
<p>This is also too low level to handle tags. In zsh 4.1, it is made
obsolete by a cleverer mechanism for handling different contexts which
can be used, for example, for handling of arguments to redirections for
particular commands, or keys in a particular associative array. I expect
I'll describe that when 4.1 is finally released.</p>
<p><strong><code>_describe</code></strong></p>
<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:</p>
<pre><code> _describe &quot;description of set 1&quot; descs1 compls1 \
&lt;compadd-opts-1&gt; -- \
&quot;description of set 2&quot; ...
</code></pre>
<p>where you can have any number of sets separated by the `<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>&lt;compadd-opts-1&gt;</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>
<p><strong><code>_combination</code></strong></p>
<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:</p>
<pre><code> _combination my-accounts users-hosts users
</code></pre>
<p>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>
<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:</p>
<pre><code> _combination my-accounts users-hosts users=$userarg hosts
</code></pre>
<p>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>
<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 &lt;sep&gt;</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>
<p>As you can see, this function is at a high enough level to handle the
tags mechanism itself.</p>
<p><strong><code>_multi_parts</code></strong></p>
<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:</p>
<pre><code> local groups expl
groups=($(awk -F: '{ print $1 }' ~/.newsrc))
_wanted groups expl 'newsgroup' _multi_parts &quot;$expl[@]&quot; . groups
</code></pre>
<p>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></p>
<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</p>
<pre><code> local expl
array1=(apple banana cucumber)
_wanted breakfast expl 'breakfast' \
_sep_parts array1 + '(bread toast croissant)' @ '(bowl plate saucer)';
</code></pre>
<p>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></p>
<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>
<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:</p>
<pre><code> 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)'
</code></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>
<p>Hence a typical(?) list to be completed by this would be
`<code>rw,uid=123,bs=2048</code>'.</p>
<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></p>
<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>
<p><span id="l191"></span></p>
<h2 id="610-finally"><a class="header" href="#610-finally">6.10: Finally</a></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>
<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>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="zshguide05.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="zshguide07.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="zshguide05.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="zshguide07.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<!-- Livereload script (if served using the cli tool) -->
<script type="text/javascript">
var socket = new WebSocket("ws://localhost:3000/__livereload");
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
Reference in New Issue Copy Permalink