4760 lines
270 KiB
HTML
4760 lines
270 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Completion System - Zsh Manual</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 -->
|
||
<link rel="stylesheet" href="./theme/catppuccin.css">
|
||
<link rel="stylesheet" href="./theme/catppuccin-highlight.css">
|
||
|
||
</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 "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-&-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html"><strong aria-hidden="true">14.</strong> Expansion</a></li><li class="chapter-item expanded "><a href="Parameters.html"><strong aria-hidden="true">15.</strong> Parameters</a></li><li class="chapter-item expanded "><a href="Options.html"><strong aria-hidden="true">16.</strong> Options</a></li><li class="chapter-item expanded "><a href="Shell-Builtin-Commands.html"><strong aria-hidden="true">17.</strong> Shell Builtin Commands</a></li><li class="chapter-item expanded "><a href="Zsh-Line-Editor.html"><strong aria-hidden="true">18.</strong> Zsh Line Editor</a></li><li class="chapter-item expanded "><a href="Completion-Widgets.html"><strong aria-hidden="true">19.</strong> Completion Widgets</a></li><li class="chapter-item expanded "><a href="Completion-System.html" class="active"><strong aria-hidden="true">20.</strong> Completion System</a></li><li class="chapter-item expanded "><a href="Completion-Using-compctl.html"><strong aria-hidden="true">21.</strong> Completion Using compctl</a></li><li class="chapter-item expanded "><a href="Zsh-Modules.html"><strong aria-hidden="true">22.</strong> Zsh Modules</a></li><li class="chapter-item expanded "><a href="Calendar-Function-System.html"><strong aria-hidden="true">23.</strong> Calendar Function System</a></li><li class="chapter-item expanded "><a href="TCP-Function-System.html"><strong aria-hidden="true">24.</strong> TCP Function System</a></li><li class="chapter-item expanded "><a href="Zftp-Function-System.html"><strong aria-hidden="true">25.</strong> Zftp Function System</a></li><li class="chapter-item expanded "><a href="User-Contributions.html"><strong aria-hidden="true">26.</strong> User Contributions</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>
|
||
<li role="none"><button role="menuitem" class="theme" id="latte">Latte</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="frappe">Frappé</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="macchiato">Macchiato</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mocha">Mocha</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 Manual</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="#20-completion-system">20 Completion System</a>
|
||
<ul>
|
||
<li><a href="#201-description">20.1 Description</a></li>
|
||
<li><a href="#202-initialization">20.2 Initialization</a>
|
||
<ul>
|
||
<li><a href="#2021-use-of-compinit">20.2.1 Use of compinit</a></li>
|
||
<li><a href="#2022-autoloaded-files">20.2.2 Autoloaded files</a></li>
|
||
<li><a href="#2023-functions">20.2.3 Functions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#203-completion-system-configuration">20.3 Completion System Configuration</a>
|
||
<ul>
|
||
<li><a href="#2031-overview">20.3.1 Overview</a></li>
|
||
<li><a href="#2032-standard-tags">20.3.2 Standard Tags</a></li>
|
||
<li><a href="#2033-standard-styles">20.3.3 Standard Styles</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#204-control-functions">20.4 Control Functions</a></li>
|
||
<li><a href="#205-bindable-commands">20.5 Bindable Commands</a></li>
|
||
<li><a href="#206-utility-functions">20.6 Utility Functions</a></li>
|
||
<li><a href="#207-completion-system-variables">20.7 Completion System Variables</a></li>
|
||
<li><a href="#208-completion-directories">20.8 Completion Directories</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Completion-System"></span> <span
|
||
id="Completion-System-1"></span></p>
|
||
<h1 id="20-completion-system"><a class="header" href="#20-completion-system">20 Completion System</a></h1>
|
||
<p><span id="index-completion-system"></span> <span
|
||
id="index-completion_002c-programmable-1"></span> <span
|
||
id="index-completion_002c-controlling-1"></span></p>
|
||
<hr />
|
||
<p><span id="Description-2"></span></p>
|
||
<h2 id="201-description"><a class="header" href="#201-description">20.1 Description</a></h2>
|
||
<p>This describes the shell code for the ‘new’ completion system, referred
|
||
to as compsys. It is written in shell functions based on the features
|
||
described in the previous chapter, <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a>.</p>
|
||
<p>The features are contextual, sensitive to the point at which completion
|
||
is started. Many completions are already provided. For this reason, a
|
||
user can perform a great many tasks without knowing any details beyond
|
||
how to initialize the system, which is described in
|
||
<a href="#Initialization">Initialization</a>.</p>
|
||
<p>The context that decides what completion is to be performed may be</p>
|
||
<ul>
|
||
<li>an argument or option position: these describe the position on the
|
||
command line at which completion is requested. For example ‘first
|
||
argument to rmdir, the word being completed names a directory’;</li>
|
||
<li>a special context, denoting an element in the shell’s syntax. For
|
||
example ‘a word in command position’ or ‘an array subscript’.</li>
|
||
</ul>
|
||
<p>A full context specification contains other elements, as we shall
|
||
describe.</p>
|
||
<p>Besides commands names and contexts, the system employs two more
|
||
concepts, <em>styles</em> and <em>tags</em>. These provide ways for the user to
|
||
configure the system’s behaviour.</p>
|
||
<p>Tags play a dual role. They serve as a classification system for the
|
||
matches, typically indicating a class of object that the user may need
|
||
to distinguish. For example, when completing arguments of the ls command
|
||
the user may prefer to try files before directories, so both of these
|
||
are tags. They also appear as the rightmost element in a context
|
||
specification.</p>
|
||
<p>Styles modify various operations of the completion system, such as
|
||
output formatting, but also what kinds of completers are used (and in
|
||
what order), or which tags are examined. Styles may accept arguments and
|
||
are manipulated using the zstyle command described in <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>.</p>
|
||
<p>In summary, tags describe <em>what</em> the completion objects are, and style
|
||
how they are to be completed. At various points of execution, the
|
||
completion system checks what styles and/or tags are defined for the
|
||
current context, and uses that to modify its behavior. The full
|
||
description of context handling, which determines how tags and other
|
||
elements of the context influence the behaviour of styles, is described
|
||
in <a href="#Completion-System-Configuration">Completion System Configuration</a>.</p>
|
||
<p>When a completion is requested, a dispatcher function is called; see the
|
||
description of _main_complete in the list of control functions below.
|
||
This dispatcher decides which function should be called to produce the
|
||
completions, and calls it. The result is passed to one or more
|
||
<em>completers</em>, functions that implement individual completion strategies:
|
||
simple completion, error correction, completion with error correction,
|
||
menu selection, etc.</p>
|
||
<p>More generally, the shell functions contained in the completion system
|
||
are of two types:</p>
|
||
<ul>
|
||
<li>those beginning ‘comp’ are to be called directly; there are only a
|
||
few of these;</li>
|
||
<li>those beginning ‘_’ are called by the completion code. The shell
|
||
functions of this set, which implement completion behaviour and may
|
||
be bound to keystrokes, are referred to as ‘widgets’. These
|
||
proliferate as new completions are required.</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Initialization"></span> <span id="Initialization-1"></span></p>
|
||
<h2 id="202-initialization"><a class="header" href="#202-initialization">20.2 Initialization</a></h2>
|
||
<p><span id="index-compinstall"></span> <span
|
||
id="index-completion-system_002c-installing"></span></p>
|
||
<p>If the system was installed completely, it should be enough to call the
|
||
shell function compinit from your initialization file; see the next
|
||
section. However, the function compinstall can be run by a user to
|
||
configure various aspects of the completion system.</p>
|
||
<p>Usually, compinstall will insert code into .zshrc, although if file’s
|
||
location. Note that it is up to you to make sure that the lines added to
|
||
.zshrc are actually run; you may, for example, need to move them to an
|
||
earlier place in the file if .zshrc usually returns early. So long as
|
||
you keep them all together (including the comment lines at the start and
|
||
finish), you can rerun compinstall and it will correctly locate and
|
||
modify these lines. Note, however, that any code you add to this section
|
||
by hand is likely to be lost if you rerun compinstall, although lines
|
||
using the command ‘zstyle’ should be gracefully handled.</p>
|
||
<p>The new code will take effect next time you start the shell, or run
|
||
.zshrc by hand; there is also an option to make them take effect
|
||
immediately. However, if compinstall has removed definitions, you will
|
||
need to restart the shell to see the changes.</p>
|
||
<p>To run compinstall you will need to make sure it is in a directory
|
||
mentioned in your fpath parameter, which should already be the case if
|
||
zsh was properly configured as long as your startup files do not remove
|
||
the appropriate directories from fpath. Then it must be autoloaded
|
||
(‘autoload -U compinstall’ is recommended). You can abort the
|
||
installation any time you are being prompted for information, and your
|
||
.zshrc will not be altered at all; changes only take place right at the
|
||
end, where you are specifically asked for confirmation.</p>
|
||
<hr />
|
||
<p><span id="Use-of-compinit"></span></p>
|
||
<h3 id="2021-use-of-compinit"><a class="header" href="#2021-use-of-compinit">20.2.1 Use of compinit</a></h3>
|
||
<p><span id="index-compinit"></span> <span
|
||
id="index-completion-system_002c-initializing"></span></p>
|
||
<p>This section describes the use of compinit to initialize completion for
|
||
the current session when called directly; if you have run compinstall it
|
||
will be called automatically from your .zshrc.</p>
|
||
<p>To initialize the system, the function compinit should be in a directory
|
||
mentioned in the fpath parameter, and should be autoloaded (‘autoload -U
|
||
compinit’ is recommended), and then run simply as ‘compinit’. This will
|
||
define a few utility functions, arrange for all the necessary shell
|
||
functions to be autoloaded, and will then re-define all widgets that do
|
||
completion to use the new system. If you use the menu-select widget,
|
||
which is part of the zsh/complist module, you should make sure that that
|
||
module is loaded before the call to compinit so that that widget is also
|
||
re-defined. If completion styles (see below) are set up to perform
|
||
expansion as well as completion by default, and the TAB key is bound to
|
||
expand-or-complete, compinit will rebind it to complete-word; this is
|
||
necessary to use the correct form of expansion.</p>
|
||
<p>Should you need to use the original completion commands, you can still
|
||
bind keys to the old widgets by putting a ‘.’ in front of the widget
|
||
name, e.g. ‘.expand-or-complete’.</p>
|
||
<p>To speed up the running of compinit, it can be made to produce a dumped
|
||
configuration that will be read in on future invocations; this is the
|
||
default, but can be turned off by calling compinit with the option -D.
|
||
The dumped file is .zcompdump in the same directory as the startup files
|
||
(i.e. $ZDOTDIR or $HOME); alternatively, an explicit file name can be
|
||
given by ‘compinit -d <code>dumpfile</code>’. The next invocation of compinit will
|
||
read the dumped file instead of performing a full initialization.</p>
|
||
<p>If the number of completion files changes, compinit will recognise this
|
||
and produce a new dump file. However, if the name of a function or the
|
||
arguments in the first line of a #compdef function (as described below)
|
||
change, it is easiest to delete the dump file by hand so that compinit
|
||
will re-create it the next time it is run. The check performed to see if
|
||
there are new functions can be omitted by giving the option -C. In this
|
||
case the dump file will only be created if there isn’t one already.</p>
|
||
<p>The dumping is actually done by another function, compdump, but you will
|
||
only need to run this yourself if you change the configuration (e.g.
|
||
using compdef) and then want to dump the new one. The name of the old
|
||
dumped file will be remembered for this purpose.</p>
|
||
<p>If the parameter _compdir is set, compinit uses it as a directory where
|
||
completion functions can be found; this is only necessary if they are
|
||
not already in the function search path.</p>
|
||
<p>For security reasons compinit also checks if the completion system would
|
||
use files not owned by root or by the current user, or files in root or
|
||
by the current user. If such files or directories are found, compinit
|
||
will ask if the completion system should really be used. To avoid these
|
||
tests and make all files found be used without asking, use the option
|
||
-u, and to make compinit silently ignore all insecure files and
|
||
directories use the option -i. This security check is skipped entirely
|
||
when the -C option is given, provided the dumpfile exists.</p>
|
||
<p><span id="index-compaudit"></span></p>
|
||
<p>The security check can be retried at any time by running the function
|
||
compaudit. This is the same check used by compinit, but when it is
|
||
executed directly any changes to fpath are made local to the function so
|
||
they do not persist. The directories to be checked may be passed as
|
||
arguments; if none are given, compaudit uses fpath and _compdir to find
|
||
completion system directories, adding missing ones to fpath as
|
||
necessary. To force a check of exactly the directories currently named
|
||
in fpath, set _compdir to an empty string before calling compaudit or
|
||
compinit.</p>
|
||
<p><span id="index-bashcompinit"></span></p>
|
||
<p>The function bashcompinit provides compatibility with bash’s
|
||
programmable completion system. When run it will define the functions,
|
||
compgen and complete which correspond to the bash builtins with the same
|
||
names. It will then be possible to use completion specifications and
|
||
functions written for bash.</p>
|
||
<hr />
|
||
<p><span id="Autoloaded-files"></span></p>
|
||
<h3 id="2022-autoloaded-files"><a class="header" href="#2022-autoloaded-files">20.2.2 Autoloaded files</a></h3>
|
||
<p><span id="index-completion-system_002c-autoloaded-functions"></span></p>
|
||
<p>The convention for autoloaded functions used in completion is that they
|
||
start with an underscore; as already mentioned, the fpath/FPATH
|
||
parameter must contain the directory in which they are stored. If zsh
|
||
was properly installed on your system, then fpath/FPATH automatically
|
||
contains the required directories for the standard functions.</p>
|
||
<p>For incomplete installations, if compinit does not find enough files
|
||
beginning with an underscore (fewer than twenty) in the search path, it
|
||
will try to find more by adding the directory _compdir to the search
|
||
path. If that directory has a subdirectory named Base, all
|
||
subdirectories will be added to the path. Furthermore, if the
|
||
subdirectory Base has a subdirectory named Core, compinit will add all
|
||
subdirectories of the subdirectories to the path: this allows the
|
||
functions to be in the same format as in the zsh source distribution.</p>
|
||
<p><span id="index-compdef_002c-use-of-by-compinit"></span></p>
|
||
<p>When compinit is run, it searches all such files accessible via
|
||
fpath/FPATH and reads the first line of each of them. This line should
|
||
contain one of the tags described below. Files whose first line does not
|
||
start with one of these tags are not considered to be part of the
|
||
completion system and will not be treated specially.</p>
|
||
<p>The tags are:</p>
|
||
<p>#compdef <code>name</code> ... [ -{p|P} <code>pattern</code> ... [ -N <code>name</code> ... ] ]<br />
|
||
The file will be made autoloadable and the function defined in it will
|
||
be called when completing <code>name</code>s, each of which is either the name of a
|
||
command whose arguments are to be completed or one of a number of
|
||
special contexts in the form -<code>context</code>- described below.</p>
|
||
<p>Each <code>name</code> may also be of the form ‘<code>cmd</code>=<code>service</code>’. When completing
|
||
the command <code>cmd</code>, the function typically behaves as if the command (or
|
||
special context) <code>service</code> was being completed instead. This provides a
|
||
way of altering the behaviour of functions that can perform many
|
||
different completions. It is implemented by setting the parameter
|
||
$service when calling the function; the function may choose to interpret
|
||
this how it wishes, and simpler functions will probably ignore it.</p>
|
||
<p>If the #compdef line contains one of the options -p or -P, the words
|
||
following are taken to be patterns. The function will be called when
|
||
completion is attempted for a command or context that matches one of the
|
||
patterns. The options -p and -P are used to specify patterns to be tried
|
||
before or after other completions respectively. Hence -P may be used to
|
||
specify default actions.</p>
|
||
<p>The option -N is used after a list following -p or -P; it specifies that
|
||
remaining words no longer define patterns. It is possible to toggle
|
||
between the three options as many times as necessary.</p>
|
||
<p>#compdef -k <code>style key-sequence</code> ...<br />
|
||
This option creates a widget behaving like the builtin widget <code>style</code>
|
||
and binds it to the given <code>key-sequence</code>s, if any. The <code>style</code> must be
|
||
one of the builtin widgets that perform completion, namely
|
||
complete-word, delete-char-or-list, expand-or-complete,
|
||
expand-or-complete-prefix, list-choices, menu-complete,
|
||
menu-expand-or-complete, or reverse-menu-complete. If the zsh/complist
|
||
module is loaded (see <a href="Zsh-Modules.html#The-zsh_002fcomplist-Module">The zsh/complist
|
||
Module</a>) the widget
|
||
menu-select is also available.</p>
|
||
<p>When one of the <code>key-sequence</code>s is typed, the function in the file will
|
||
be invoked to generate the matches. Note that a key will not be re-bound
|
||
if it already was (that is, was bound to something other than
|
||
undefined-key). The widget created has the same name as the file and can
|
||
be bound to any other keys using bindkey as usual.</p>
|
||
<p>#compdef -K <code>widget-name</code> <code>style</code> <code>key-sequence</code> [ <code>name</code> <code>style</code> <code>seq</code> ... ]<br />
|
||
This is similar to -k except that only one <code>key-sequence</code> argument may
|
||
be given for each <code>widget-name</code> <code>style</code> pair. However, the entire set of
|
||
three arguments may be repeated with a different set of arguments. Note
|
||
in particular that the <code>widget-name</code> must be distinct in each set. If it
|
||
does not begin with ‘_’ this will be added. The <code>widget-name</code> should
|
||
not clash with the name of any existing widget: names based on the name
|
||
of the function are most useful. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">#compdef -K _foo_complete complete-word "^X^C" \
|
||
_foo_list list-choices "^X^D"
|
||
</code></pre>
|
||
</div>
|
||
<p>(all on one line) defines a widget _foo_complete for completion, bound
|
||
to ‘^X^C’, and a widget _foo_list for listing, bound to ‘^X^D’.</p>
|
||
<p>#autoload [ <code>options</code> ]<br />
|
||
Functions with the #autoload tag are marked for autoloading but are not
|
||
otherwise treated specially. Typically they are to be called from within
|
||
one of the completion functions. Any <code>options</code> supplied will be passed
|
||
to the autoload builtin; a typical use is +X to force the function to be
|
||
loaded immediately. Note that the -U and -z flags are always added
|
||
implicitly.</p>
|
||
<p>The # is part of the tag name and no white space is allowed after it.
|
||
The #compdef tags use the compdef function described below; the main
|
||
difference is that the name of the function is supplied implicitly.</p>
|
||
<p>The special contexts for which completion functions can be defined are:</p>
|
||
<p><span
|
||
id="index-_002darray_002dvalue_002d_002c-completion-context"></span></p>
|
||
<p>-array-value-</p>
|
||
<p>The right hand side of an array-assignment (‘<code>name</code>=(<code>...</code>)’)</p>
|
||
<p><span
|
||
id="index-_002dassign_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p>-assign-parameter-</p>
|
||
<p>The name of a parameter in an assignment, i.e. on the left hand side of
|
||
an ‘=’</p>
|
||
<p><span
|
||
id="index-_002dbrace_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p>-brace-parameter-</p>
|
||
<p>The name of a parameter expansion within braces (‘${<code>...</code>}’)</p>
|
||
<p><span id="index-_002dcommand_002d_002c-completion-context"></span></p>
|
||
<p>-command-</p>
|
||
<p>A word in command position</p>
|
||
<p><span id="index-_002dcondition_002d_002c-completion-context"></span></p>
|
||
<p>-condition-</p>
|
||
<p>A word inside a condition (‘[[<code>...</code>]]’)</p>
|
||
<p><span id="index-_002ddefault_002d_002c-completion-context"></span></p>
|
||
<p>-default-</p>
|
||
<p>Any word for which no other completion is defined</p>
|
||
<p><span id="index-_002dequal_002d_002c-completion-context"></span></p>
|
||
<p>-equal-</p>
|
||
<p>A word beginning with an equals sign</p>
|
||
<p><span id="index-_002dfirst_002d_002c-completion-context"></span></p>
|
||
<p>-first-</p>
|
||
<p>This is tried before any other completion function. The function called
|
||
may set the _compskip parameter to one of various values: all: no
|
||
further completion is attempted; a string containing the substring
|
||
patterns: no pattern completion functions will be called; a string
|
||
containing default: the function for the ‘-default-’ context will not be
|
||
called, but functions defined for commands will be.</p>
|
||
<p><span id="index-_002dmath_002d_002c-completion-context"></span></p>
|
||
<p>-math-</p>
|
||
<p>Inside mathematical contexts, such as ‘((<code>...</code>))’</p>
|
||
<p><span id="index-_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p>-parameter-</p>
|
||
<p>The name of a parameter expansion (‘$<code>...</code>’)</p>
|
||
<p><span id="index-_002dredirect_002d_002c-completion-context"></span></p>
|
||
<p>-redirect-</p>
|
||
<p>The word after a redirection operator.</p>
|
||
<p><span id="index-_002dsubscript_002d_002c-completion-context"></span></p>
|
||
<p>-subscript-</p>
|
||
<p>The contents of a parameter subscript.</p>
|
||
<p><span id="index-_002dtilde_002d_002c-completion-context"></span></p>
|
||
<p>-tilde-</p>
|
||
<p>After an initial tilde (‘~’), but before the first slash in the word.</p>
|
||
<p><span id="index-_002dvalue_002d_002c-completion-context"></span></p>
|
||
<p>-value-</p>
|
||
<p>On the right hand side of an assignment.</p>
|
||
<p>Default implementations are supplied for each of these contexts. In most
|
||
cases the context -<code>context</code>- is implemented by a corresponding function
|
||
_<code>context</code>, for example the context ‘-tilde-’ and the function
|
||
‘_tilde’).</p>
|
||
<p>The contexts -redirect- and -value- allow extra context-specific
|
||
information. (Internally, this is handled by the functions for each
|
||
context calling the function _dispatch.) The extra information is added
|
||
separated by commas.</p>
|
||
<p>For the -redirect- context, the extra information is in the form
|
||
‘-redirect-,<code>op</code>,<code>command</code>’, where <code>op</code> is the redirection operator and
|
||
<code>command</code> is the name of the command on the line. If there is no command
|
||
on the line yet, the <code>command</code> field will be empty.</p>
|
||
<p>For the -value- context, the form is ‘-value-,<code>name</code>,<code>command</code>’, where
|
||
<code>name</code> is the name of the parameter on the left hand side of the
|
||
assignment. In the case of elements of an associative array, for example
|
||
‘assoc=(key <TAB>’, <code>name</code> is expanded to ‘<code>name</code>-<code>key</code>’. In certain
|
||
special contexts, such as completing after ‘make CFLAGS=’, the <code>command</code>
|
||
part gives the name of the command, here make; otherwise it is empty.</p>
|
||
<p>It is not necessary to define fully specific completions as the
|
||
functions provided will try to generate completions by progressively
|
||
replacing the elements with ‘-default-’. For example, when completing
|
||
after ‘foo=<TAB>’, _value will try the names ‘-value-,foo,’ (note the
|
||
empty <code>command</code> part), ‘-value-,foo,-default-’
|
||
and‘-value-,-default-,-default-’, in that order, until it finds a
|
||
function to handle the context.</p>
|
||
<p>As an example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">compdef '_files -g "*.log"' '-redirect-,2>,-default-'
|
||
</code></pre>
|
||
</div>
|
||
<p>completes files matching ‘*.log’ after ‘2> <TAB>’ for any command with
|
||
no more specific handler defined.</p>
|
||
<p>Also:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">compdef _foo -value-,-default-,-default-
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that _foo provides completions for the values of parameters
|
||
for which no special function has been defined. This is usually handled
|
||
by the function _value itself.</p>
|
||
<p>The same lookup rules are used when looking up styles (as described
|
||
below); for example</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
|
||
</code></pre>
|
||
</div>
|
||
<p>is another way to make completion after ‘2> <TAB>’ complete files
|
||
matching ‘*.log’.</p>
|
||
<hr />
|
||
<p><span id="Functions-3"></span></p>
|
||
<h3 id="2023-functions"><a class="header" href="#2023-functions">20.2.3 Functions</a></h3>
|
||
<p>The following function is defined by compinit and may be called
|
||
directly.</p>
|
||
<p><span id="index-compdef"></span> <span
|
||
id="index-completion-system_002c-adding-definitions"></span></p>
|
||
<p>compdef [ -ane ] <code>function name</code> ... [ -{p|P} <code>pattern</code> ... [ -N <code>name</code> ...]]<br />
|
||
compdef -d <code>name</code> ...<br />
|
||
compdef -k [ -an ] <code>function style key-sequence</code> [ <code>key-sequence</code> ... ]<br />
|
||
compdef -K [ -an ] <code>function name style key-seq</code> [ <code>name style seq</code> ... ]<br />
|
||
The first form defines the <code>function</code> to call for completion in the
|
||
given contexts as described for the #compdef tag above.</p>
|
||
<p>Alternatively, all the arguments may have the form ‘<code>cmd</code>=<code>service</code>’.
|
||
Here <code>service</code> should already have been defined by ‘<code>cmd1</code>=<code>service</code>’
|
||
lines in #compdef files, as described above. The argument for <code>cmd</code> will
|
||
be completed in the same way as <code>service</code>.</p>
|
||
<p>The <code>function</code> argument may alternatively be a string containing almost
|
||
any shell code. If the string contains an equal sign, the above will
|
||
take precedence. The option -e may be used to specify the first argument
|
||
is to be evaluated as shell code even if it contains an equal sign. The
|
||
string will be executed using the eval builtin command to generate
|
||
completions. This provides a way of avoiding having to define a new
|
||
completion function. For example, to complete files ending in ‘.h’ as
|
||
arguments to the command foo:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">compdef '_files -g "*.h"' foo
|
||
</code></pre>
|
||
</div>
|
||
<p>The option -n prevents any completions already defined for the command
|
||
or context from being overwritten.</p>
|
||
<p>The option -d deletes any completion defined for the command or contexts
|
||
listed.</p>
|
||
<p>The <code>name</code>s may also contain -p, -P and -N options as described for the
|
||
#compdef tag. The effect on the argument list is identical, switching
|
||
between definitions of patterns tried initially, patterns tried finally,
|
||
and normal commands and contexts.</p>
|
||
<p>The parameter $_compskip may be set by any function defined for a
|
||
pattern context. If it is set to a value containing the substring
|
||
‘patterns’ none of the pattern-functions will be called; if it is set to
|
||
a value containing the substring ‘all’, no other function will be
|
||
called. Setting $_compskip in this manner is of particular utility when
|
||
using the -p option, as otherwise the dispatcher will move on to
|
||
additional functions (likely the default one) after calling the
|
||
pattern-context one, which can mangle the display of completion
|
||
possibilities if not handled properly.</p>
|
||
<p>The form with -k defines a widget with the same name as the <code>function</code>
|
||
that will be called for each of the <code>key-sequence</code>s; this is like the
|
||
#compdef -k tag. The function should generate the completions needed and
|
||
will otherwise behave like the builtin widget whose name is given as the
|
||
<code>style</code> argument. The widgets usable for this are: complete-word,
|
||
delete-char-or-list, expand-or-complete, expand-or-complete-prefix,
|
||
list-choices, menu-complete, menu-expand-or-complete, and
|
||
reverse-menu-complete, as well as menu-select if the zsh/complist module
|
||
is loaded. The option -n prevents the key being bound if it is already
|
||
to bound to something other than undefined-key.</p>
|
||
<p>The form with -K is similar and defines multiple widgets based on the
|
||
same <code>function</code>, each of which requires the set of three arguments
|
||
<code>name</code>, <code>style</code> and <code>key-seq</code>uence, where the latter two are as for -k
|
||
and the first must be a unique widget name beginning with an underscore.</p>
|
||
<p>Wherever applicable, the -a option makes the <code>function</code> autoloadable,
|
||
equivalent to autoload -U <code>function</code>.</p>
|
||
<p>The function compdef can be used to associate existing completion
|
||
functions with new commands. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">compdef _pids foo
|
||
</code></pre>
|
||
</div>
|
||
<p>uses the function _pids to complete process IDs for the command foo.</p>
|
||
<p>Note also the _gnu_generic function described below, which can be used
|
||
to complete options for commands that understand the ‘--help’ option.</p>
|
||
<hr />
|
||
<p><span id="Completion-System-Configuration"></span> <span
|
||
id="Completion-System-Configuration-1"></span></p>
|
||
<h2 id="203-completion-system-configuration"><a class="header" href="#203-completion-system-configuration">20.3 Completion System Configuration</a></h2>
|
||
<p><span id="index-completion-system_002c-configuration"></span></p>
|
||
<p>This section gives a short overview of how the completion system works,
|
||
and then more detail on how users can configure how and when matches are
|
||
generated.</p>
|
||
<hr />
|
||
<p><span id="Overview-2"></span></p>
|
||
<h3 id="2031-overview"><a class="header" href="#2031-overview">20.3.1 Overview</a></h3>
|
||
<p>When completion is attempted somewhere on the command line the
|
||
completion system begins building the context. The context represents
|
||
everything that the shell knows about the meaning of the command line
|
||
and the significance of the cursor position. This takes account of a
|
||
number of things including the command word (such as ‘grep’ or ‘zsh’)
|
||
and options to which the current word may be an argument (such as the
|
||
‘-o’ option to zsh which takes a shell option as an argument).</p>
|
||
<p>The context starts out very generic ("we are beginning a completion")
|
||
and becomes more specific as more is learned ("the current word is in a
|
||
position that is usually a command name" or "the current word might be a
|
||
variable name" and so on). Therefore the context will vary during the
|
||
same call to the completion system.</p>
|
||
<p>This context information is condensed into a string consisting of
|
||
multiple fields separated by colons, referred to simply as ‘the context’
|
||
in the remainder of the documentation. Note that a user of the
|
||
completion system rarely needs to compose a context string, unless for
|
||
example a new function is being written to perform completion for a new
|
||
command. What a user may need to do is compose a <em>style</em> pattern, which
|
||
is matched against a context when needed to look up context-sensitive
|
||
options that configure the completion system.</p>
|
||
<p>The next few paragraphs explain how a context is composed within the
|
||
completion function suite. Following that is discussion of how <em>styles</em>
|
||
are defined. Styles determine such things as how the matches are
|
||
generated, similarly to shell options but with much more control. They
|
||
are defined with the zstyle builtin command (<a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>).</p>
|
||
<p>The context string always consists of a fixed set of fields, separated
|
||
by colons and with a leading colon before the first. Fields which are
|
||
not yet known are left empty, but the surrounding colons appear anyway.
|
||
The fields are always in the order
|
||
:completion:<code>function</code>:<code>completer</code>:<code>command</code>:<code>argument</code>:<code>tag</code>. These
|
||
have the following meaning:</p>
|
||
<ul>
|
||
<li>The literal string completion, saying that this style is used by the
|
||
completion system. This distinguishes the context from those used
|
||
by, for example, zle widgets and ZFTP functions.</li>
|
||
<li>The <code>function</code>, if completion is called from a named widget rather
|
||
than through the normal completion system. Typically this is blank,
|
||
but it is set by special widgets such as predict-on and the various
|
||
functions in the Widget directory of the distribution to the name of
|
||
that function, often in an abbreviated form.</li>
|
||
<li>The <code>completer</code> currently active, the name of the function without
|
||
the leading underscore and with other underscores converted to
|
||
hyphens. A ‘completer’ is in overall control of how completion is to
|
||
be performed; ‘complete’ is the simplest, but other completers exist
|
||
to perform related tasks such as correction, or to modify the
|
||
behaviour of a later completer. See <a href="#Control-Functions">Control
|
||
Functions</a> for more information.</li>
|
||
<li>The <code>command</code> or a special -<code>context</code>-, just at it appears following
|
||
the #compdef tag or the compdef function. Completion functions for
|
||
commands that have sub-commands usually modify this field to contain
|
||
the name of the command followed by a minus sign and the
|
||
sub-command. For example, the completion function for the cvs
|
||
command sets this field to cvs-add when completing arguments to the
|
||
add subcommand.</li>
|
||
<li>The <code>argument</code>; this indicates which command line or option argument
|
||
we are completing. For command arguments this generally takes the
|
||
form argument-<code>n</code>, where <code>n</code> is the number of the argument, and for
|
||
arguments to options the form option-<code>opt</code>-<code>n</code> where <code>n</code> is the
|
||
number of the argument to option <code>opt</code>. However, this is only the
|
||
case if the command line is parsed with standard UNIX-style options
|
||
and arguments, so many completions do not set this.</li>
|
||
<li>The <code>tag</code>. As described previously, tags are used to discriminate
|
||
between the types of matches a completion function can generate in a
|
||
certain context. Any completion function may use any tag name it
|
||
likes, but a list of the more common ones is given below.</li>
|
||
</ul>
|
||
<p>The context is gradually put together as the functions are executed,
|
||
starting with the main entry point, which adds :completion: and the
|
||
<code>function</code> element if necessary. The completer then adds the <code>completer</code>
|
||
element. The contextual completion adds the <code>command</code> and <code>argument</code>
|
||
options. Finally, the <code>tag</code> is added when the types of completion are
|
||
known. For example, the context name</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">:completion::complete:dvips:option-o-1:files
|
||
</code></pre>
|
||
</div>
|
||
<p>says that normal completion was attempted as the first argument to the
|
||
option -o of the command dvips:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">dvips -o ...
|
||
</code></pre>
|
||
</div>
|
||
<p>and the completion function will generate filenames.</p>
|
||
<p>Usually completion will be tried for all possible tags in an order given
|
||
by the completion function. However, this can be altered by using the
|
||
tag-order style. Completion is then restricted to the list of given tags
|
||
in the given order.</p>
|
||
<p>The _complete_help bindable command shows all the contexts and tags
|
||
available for completion at a particular point. This provides an easy
|
||
way of finding information for tag-order and other styles. It is
|
||
described in <a href="#Bindable-Commands">Bindable Commands</a>.</p>
|
||
<p>When looking up styles the completion system uses full context names,
|
||
including the tag. Looking up the value of a style therefore consists of
|
||
two things: the context, which is matched to the most specific (best
|
||
fitting) pattern, and the name of the style itself, which must be
|
||
matched exactly. The following examples demonstrate that patterns may be
|
||
loosely defined for styles that apply broadly, or as tightly defined as
|
||
desired for styles that apply in narrower circumstances.</p>
|
||
<p>For example, many completion functions can generate matches in a simple
|
||
and a verbose form and use the verbose style to decide which form should
|
||
be used. To make all such functions use the verbose form, put</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' verbose yes
|
||
</code></pre>
|
||
</div>
|
||
<p>in a startup file (probably .zshrc). This gives the verbose style the
|
||
value yes in every context inside the completion system, unless that
|
||
context has a more specific definition. It is best to avoid giving the
|
||
pattern as ‘*’ in case the style has some meaning outside the
|
||
completion system.</p>
|
||
<p>Many such general purpose styles can be configured simply by using the
|
||
compinstall function.</p>
|
||
<p>A more specific example of the use of the verbose style is by the
|
||
completion for the kill builtin. If the style is set, the builtin lists
|
||
full job texts and process command lines; otherwise it shows the bare
|
||
job numbers and PIDs. To turn the style off for this use only:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:kill:*:*' verbose no
|
||
</code></pre>
|
||
</div>
|
||
<p>For even more control, the style can use one of the tags ‘jobs’ or
|
||
‘processes’. To turn off verbose display only for jobs:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:kill:*:jobs' verbose no
|
||
</code></pre>
|
||
</div>
|
||
<p>The -e option to zstyle even allows completion function code to appear
|
||
as the argument to a style; this requires some understanding of the
|
||
internals of completion functions (see <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a>)). For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -e ':completion:*' hosts 'reply=($myhosts)'
|
||
</code></pre>
|
||
</div>
|
||
<p>This forces the value of the hosts style to be read from the variable
|
||
myhosts each time a host name is needed; this is useful if the value of
|
||
myhosts can change dynamically. For another useful example, see the
|
||
example in the description of the file-list style below. This form can
|
||
be slow and should be avoided for commonly examined styles such as menu
|
||
and list-rows-first.</p>
|
||
<p>Note that the order in which styles are <em>defined</em> does not matter; the
|
||
style mechanism uses the most specific possible match for a particular
|
||
style to determine the set of values. Strings are preferred over
|
||
patterns (for example, ‘:completion::complete:::foo’ is more specific
|
||
than ‘:completion::complete:::*’), and longer patterns are preferred
|
||
over the pattern ‘*’. See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a> for details.</p>
|
||
<p>Context patterns that use something other than a wildcard (*) to match
|
||
the middle parts of the context — the <code>completer</code>, <code>command</code>, and
|
||
<code>argument</code> in
|
||
:completion:<code>function</code>:<code>completer</code>:<code>command</code>:<code>argument</code>:<code>tag</code> — should
|
||
include all six colons (:) explicitly. Without this, a pattern such as
|
||
:completion:*:foo:* could match foo against a component other than the
|
||
intended one (for example, against <code>completer</code> when a match against
|
||
<code>command</code> was intended).</p>
|
||
<p>Style names like those of tags are arbitrary and depend on the
|
||
completion function. However, the following two sections list some of
|
||
the most common tags and styles.</p>
|
||
<hr />
|
||
<p><span id="Standard-Tags"></span></p>
|
||
<h3 id="2032-standard-tags"><a class="header" href="#2032-standard-tags">20.3.2 Standard Tags</a></h3>
|
||
<p><span id="index-completion-system_002c-tags"></span></p>
|
||
<p>Some of the following are only used when looking up particular styles
|
||
and do not refer to a type of match.</p>
|
||
<p><span id="index-accounts_002c-completion-tag"></span></p>
|
||
<p>accounts</p>
|
||
<p>used to look up the users-hosts style</p>
|
||
<p><span id="index-all_002dexpansions_002c-completion-tag"></span></p>
|
||
<p>all-expansions</p>
|
||
<p>used by the _expand completer when adding the single string containing
|
||
all possible expansions</p>
|
||
<p><span id="index-all_002dfiles_002c-completion-tag"></span></p>
|
||
<p>all-files</p>
|
||
<p>for the names of all files (as distinct from a particular subset, see
|
||
the globbed-files tag).</p>
|
||
<p><span id="index-arguments_002c-completion-tag"></span></p>
|
||
<p>arguments</p>
|
||
<p>for arguments to a command</p>
|
||
<p><span id="index-arrays_002c-completion-tag"></span></p>
|
||
<p>arrays</p>
|
||
<p>for names of array parameters</p>
|
||
<p><span id="index-association_002dkeys_002c-completion-tag"></span></p>
|
||
<p>association-keys</p>
|
||
<p>for keys of associative arrays; used when completing inside a subscript
|
||
to a parameter of this type</p>
|
||
<p><span id="index-bookmarks_002c-completion-tag"></span></p>
|
||
<p>bookmarks</p>
|
||
<p>when completing bookmarks (e.g. for URLs and the zftp function suite)</p>
|
||
<p><span id="index-builtins_002c-completion-tag"></span></p>
|
||
<p>builtins</p>
|
||
<p>for names of builtin commands</p>
|
||
<p><span id="index-characters_002c-completion-tag"></span></p>
|
||
<p>characters</p>
|
||
<p>for single characters in arguments of commands such as stty. Also used
|
||
when completing character classes after an opening bracket</p>
|
||
<p><span id="index-colormapids_002c-completion-tag"></span></p>
|
||
<p>colormapids</p>
|
||
<p>for X colormap ids</p>
|
||
<p><span id="index-colors_002c-completion-tag"></span></p>
|
||
<p>colors</p>
|
||
<p>for color names</p>
|
||
<p><span id="index-commands_002c-completion-tag"></span></p>
|
||
<p>commands</p>
|
||
<p>for names of external commands. Also used by complex commands such as
|
||
cvs when completing names subcommands.</p>
|
||
<p><span id="index-contexts_002c-completion-tag"></span></p>
|
||
<p>contexts</p>
|
||
<p>for contexts in arguments to the zstyle builtin command</p>
|
||
<p><span id="index-corrections_002c-completion-tag"></span></p>
|
||
<p>corrections</p>
|
||
<p>used by the _approximate and _correct completers for possible
|
||
corrections</p>
|
||
<p><span id="index-cursors_002c-completion-tag"></span></p>
|
||
<p>cursors</p>
|
||
<p>for cursor names used by X programs</p>
|
||
<p><span id="index-default_002c-completion-tag"></span></p>
|
||
<p>default</p>
|
||
<p>used in some contexts to provide a way of supplying a default when more
|
||
specific tags are also valid. Note that this tag is used when only the
|
||
<code>function</code> field of the context name is set</p>
|
||
<p><span id="index-descriptions_002c-completion-tag"></span></p>
|
||
<p>descriptions</p>
|
||
<p>used when looking up the value of the format style to generate
|
||
descriptions for types of matches</p>
|
||
<p><span id="index-devices_002c-completion-tag"></span></p>
|
||
<p>devices</p>
|
||
<p>for names of device special files</p>
|
||
<p><span id="index-directories_002c-completion-tag"></span></p>
|
||
<p>directories</p>
|
||
<p>for names of directories — local-directories is used instead when
|
||
completing arguments of cd and related builtin commands when the cdpath
|
||
array is set</p>
|
||
<p><span id="index-directory_002dstack_002c-completion-tag"></span></p>
|
||
<p>directory-stack</p>
|
||
<p>for entries in the directory stack</p>
|
||
<p><span id="index-displays_002c-completion-tag"></span></p>
|
||
<p>displays</p>
|
||
<p>for X display names</p>
|
||
<p><span id="index-domains_002c-completion-tag"></span></p>
|
||
<p>domains</p>
|
||
<p>for network domains</p>
|
||
<p><span id="index-email_002d_002a_002c-completion-tag"></span></p>
|
||
<p>email-<code>plugin</code></p>
|
||
<p>for email addresses from the ‘_email-<code>plugin</code>’ backend of
|
||
_email_addresses</p>
|
||
<p><span id="index-expansions_002c-completion-tag"></span></p>
|
||
<p>expansions</p>
|
||
<p>used by the _expand completer for individual words (as opposed to the
|
||
complete set of expansions) resulting from the expansion of a word on
|
||
the command line</p>
|
||
<p><span id="index-extensions_002c-completion-tag"></span></p>
|
||
<p>extensions</p>
|
||
<p>for X server extensions</p>
|
||
<p><span id="index-file_002ddescriptors_002c-completion-tag"></span></p>
|
||
<p>file-descriptors</p>
|
||
<p>for numbers of open file descriptors</p>
|
||
<p><span id="index-files_002c-completion-tag"></span></p>
|
||
<p>files</p>
|
||
<p>the generic file-matching tag used by functions completing filenames</p>
|
||
<p><span id="index-fonts_002c-completion-tag"></span></p>
|
||
<p>fonts</p>
|
||
<p>for X font names</p>
|
||
<p><span id="index-fstypes_002c-completion-tag"></span></p>
|
||
<p>fstypes</p>
|
||
<p>for file system types (e.g. for the mount command)</p>
|
||
<p><span id="index-functions_002c-completion-tag"></span></p>
|
||
<p>functions</p>
|
||
<p>names of functions — normally shell functions, although certain commands
|
||
may understand other kinds of function</p>
|
||
<p><span id="index-globbed_002dfiles_002c-completion-tag"></span></p>
|
||
<p>globbed-files</p>
|
||
<p>for filenames when the name has been generated by pattern matching</p>
|
||
<p><span id="index-groups_002c-completion-tag"></span></p>
|
||
<p>groups</p>
|
||
<p>for names of user groups</p>
|
||
<p><span id="index-history_002dwords_002c-completion-tag"></span></p>
|
||
<p>history-words</p>
|
||
<p>for words from the history</p>
|
||
<p><span id="index-hosts_002c-completion-tag"></span></p>
|
||
<p>hosts</p>
|
||
<p>for hostnames</p>
|
||
<p><span id="index-indexes_002c-completion-tag"></span></p>
|
||
<p>indexes</p>
|
||
<p>for array indexes</p>
|
||
<p><span id="index-interfaces_002c-completion-tag"></span></p>
|
||
<p>interfaces</p>
|
||
<p>for network interfaces</p>
|
||
<p><span id="index-jobs_002c-completion-tag"></span></p>
|
||
<p>jobs</p>
|
||
<p>for jobs (as listed by the ‘jobs’ builtin)</p>
|
||
<p><span id="index-keymaps_002c-completion-tag"></span></p>
|
||
<p>keymaps</p>
|
||
<p>for names of zsh keymaps</p>
|
||
<p><span id="index-keysyms_002c-completion-tag"></span></p>
|
||
<p>keysyms</p>
|
||
<p>for names of X keysyms</p>
|
||
<p><span id="index-libraries_002c-completion-tag"></span></p>
|
||
<p>libraries</p>
|
||
<p>for names of system libraries</p>
|
||
<p><span id="index-limits_002c-completion-tag"></span></p>
|
||
<p>limits</p>
|
||
<p>for system limits</p>
|
||
<p><span id="index-local_002ddirectories_002c-completion-tag"></span></p>
|
||
<p>local-directories</p>
|
||
<p>for names of directories that are subdirectories of the current working
|
||
directory when completing arguments of cd and related builtin commands
|
||
(compare path-directories) — when the cdpath array is unset, directories
|
||
is used instead</p>
|
||
<p><span id="index-mailboxes_002c-completion-tag"></span></p>
|
||
<p>mailboxes</p>
|
||
<p>for e-mail folders</p>
|
||
<p><span id="index-manuals_002c-completion-tag"></span></p>
|
||
<p>manuals</p>
|
||
<p>for names of manual pages</p>
|
||
<p><span id="index-maps_002c-completion-tag"></span></p>
|
||
<p>maps</p>
|
||
<p>for map names (e.g. NIS maps)</p>
|
||
<p><span id="index-messages_002c-completion-tag"></span></p>
|
||
<p>messages</p>
|
||
<p>used to look up the format style for messages</p>
|
||
<p><span id="index-modifiers_002c-completion-tag"></span></p>
|
||
<p>modifiers</p>
|
||
<p>for names of X modifiers</p>
|
||
<p><span id="index-modules_002c-completion-tag"></span></p>
|
||
<p>modules</p>
|
||
<p>for modules (e.g. zsh modules)</p>
|
||
<p><span id="index-my_002daccounts_002c-completion-tag"></span></p>
|
||
<p>my-accounts</p>
|
||
<p>used to look up the users-hosts style</p>
|
||
<p><span id="index-named_002ddirectories_002c-completion-tag"></span></p>
|
||
<p>named-directories</p>
|
||
<p>for named directories (you wouldn’t have guessed that, would you?)</p>
|
||
<p><span id="index-names_002c-completion-tag"></span></p>
|
||
<p>names</p>
|
||
<p>for all kinds of names</p>
|
||
<p><span id="index-newsgroups_002c-completion-tag"></span></p>
|
||
<p>newsgroups</p>
|
||
<p>for USENET groups</p>
|
||
<p><span id="index-nicknames_002c-completion-tag"></span></p>
|
||
<p>nicknames</p>
|
||
<p>for nicknames of NIS maps</p>
|
||
<p><span id="index-options_002c-completion-tag"></span></p>
|
||
<p>options</p>
|
||
<p>for command options</p>
|
||
<p><span id="index-original_002c-completion-tag"></span></p>
|
||
<p>original</p>
|
||
<p>used by the _approximate, _correct and _expand completers when
|
||
offering the original string as a match</p>
|
||
<p><span id="index-other_002daccounts_002c-completion-tag"></span></p>
|
||
<p>other-accounts</p>
|
||
<p>used to look up the users-hosts style</p>
|
||
<p><span id="index-packages_002c-completion-tag"></span></p>
|
||
<p>packages</p>
|
||
<p>for packages (e.g. rpm or installed Debian packages)</p>
|
||
<p><span id="index-parameters_002c-completion-tag"></span></p>
|
||
<p>parameters</p>
|
||
<p>for names of parameters</p>
|
||
<p><span id="index-path_002ddirectories_002c-completion-tag"></span></p>
|
||
<p>path-directories</p>
|
||
<p>for names of directories found by searching the cdpath array when
|
||
completing arguments of cd and related builtin commands (compare
|
||
local-directories)</p>
|
||
<p><span id="index-paths_002c-completion-tag"></span></p>
|
||
<p>paths</p>
|
||
<p>used to look up the values of the expand, ambiguous and special-dirs
|
||
styles</p>
|
||
<p><span id="index-pods_002c-completion-tag"></span></p>
|
||
<p>pods</p>
|
||
<p>for perl pods (documentation files)</p>
|
||
<p><span id="index-ports_002c-completion-tag"></span></p>
|
||
<p>ports</p>
|
||
<p>for communication ports</p>
|
||
<p><span id="index-prefixes_002c-completion-tag"></span></p>
|
||
<p>prefixes</p>
|
||
<p>for prefixes (like those of a URL)</p>
|
||
<p><span id="index-printers_002c-completion-tag"></span></p>
|
||
<p>printers</p>
|
||
<p>for print queue names</p>
|
||
<p><span id="index-processes_002c-completion-tag"></span></p>
|
||
<p>processes</p>
|
||
<p>for process identifiers</p>
|
||
<p><span id="index-processes_002dnames_002c-completion-tag"></span></p>
|
||
<p>processes-names</p>
|
||
<p>used to look up the command style when generating the names of processes
|
||
for killall</p>
|
||
<p><span id="index-sequences_002c-completion-tag"></span></p>
|
||
<p>sequences</p>
|
||
<p>for sequences (e.g. mh sequences)</p>
|
||
<p><span id="index-sessions_002c-completion-tag"></span></p>
|
||
<p>sessions</p>
|
||
<p>for sessions in the zftp function suite</p>
|
||
<p><span id="index-signals_002c-completion-tag"></span></p>
|
||
<p>signals</p>
|
||
<p>for signal names</p>
|
||
<p><span id="index-strings_002c-completion-tag"></span></p>
|
||
<p>strings</p>
|
||
<p>for strings (e.g. the replacement strings for the cd builtin command)</p>
|
||
<p><span id="index-styles_002c-completion-tag"></span></p>
|
||
<p>styles</p>
|
||
<p>for styles used by the zstyle builtin command</p>
|
||
<p><span id="index-suffixes_002c-completion-tag"></span></p>
|
||
<p>suffixes</p>
|
||
<p>for filename extensions</p>
|
||
<p><span id="index-tags_002c-completion-tag"></span></p>
|
||
<p>tags</p>
|
||
<p>for tags (e.g. rpm tags)</p>
|
||
<p><span id="index-targets_002c-completion-tag"></span></p>
|
||
<p>targets</p>
|
||
<p>for makefile targets</p>
|
||
<p><span id="index-time_002dzones_002c-completion-tag"></span></p>
|
||
<p>time-zones</p>
|
||
<p>for time zones (e.g. when setting the TZ parameter)</p>
|
||
<p><span id="index-types_002c-completion-tag"></span></p>
|
||
<p>types</p>
|
||
<p>for types of whatever (e.g. address types for the xhost command)</p>
|
||
<p><span id="index-urls_002c-completion-tag"></span></p>
|
||
<p>urls</p>
|
||
<p>used to look up the urls and local styles when completing URLs</p>
|
||
<p><span id="index-users_002c-completion-tag"></span></p>
|
||
<p>users</p>
|
||
<p>for usernames</p>
|
||
<p><span id="index-values_002c-completion-tag"></span></p>
|
||
<p>values</p>
|
||
<p>for one of a set of values in certain lists</p>
|
||
<p><span id="index-variant_002c-completion-tag"></span></p>
|
||
<p>variant</p>
|
||
<p>used by _pick_variant to look up the command to run when determining
|
||
what program is installed for a particular command name.</p>
|
||
<p><span id="index-visuals_002c-completion-tag"></span></p>
|
||
<p>visuals</p>
|
||
<p>for X visuals</p>
|
||
<p><span id="index-warnings_002c-completion-tag"></span></p>
|
||
<p>warnings</p>
|
||
<p>used to look up the format style for warnings</p>
|
||
<p><span id="index-widgets_002c-completion-tag"></span></p>
|
||
<p>widgets</p>
|
||
<p>for zsh widget names</p>
|
||
<p><span id="index-windows_002c-completion-tag"></span></p>
|
||
<p>windows</p>
|
||
<p>for IDs of X windows</p>
|
||
<p><span id="index-zsh_002doptions_002c-completion-tag"></span></p>
|
||
<p>zsh-options</p>
|
||
<p>for shell options</p>
|
||
<hr />
|
||
<p><span id="Standard-Styles"></span></p>
|
||
<h3 id="2033-standard-styles"><a class="header" href="#2033-standard-styles">20.3.3 Standard Styles</a></h3>
|
||
<p><span id="index-completion-system_002c-styles"></span></p>
|
||
<p>Note that the values of several of these styles represent boolean
|
||
values. Any of the strings ‘true’, ‘on’, ‘yes’, and ‘1’ can be used for
|
||
the value ‘true’ and any of the strings ‘false’, ‘off’, ‘no’, and ‘0’
|
||
for the value ‘false’. The behavior for any other value is undefined
|
||
except where explicitly mentioned. The default value may be either
|
||
‘true’ or ‘false’ if the style is not set.</p>
|
||
<p>Some of these styles are tested first for every possible tag
|
||
corresponding to a type of match, and if no style was found, for the
|
||
list-colors and styles controlling completion listing such as
|
||
list-packed and last-prompt. When tested for the default tag, only the
|
||
<code>function</code> field of the context will be set so that a style using the
|
||
default tag will normally be defined along the lines of:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:default' menu ...
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-accept_002dexact_002c-completion-style"></span></p>
|
||
<p>accept-exact</p>
|
||
<p>This is tested for the default tag in addition to the tags valid for the
|
||
current context. If it is set to ‘true’ and any of the trial matches is
|
||
the same as the string on the command line, this match will immediately
|
||
be accepted (even if it would otherwise be considered ambiguous).</p>
|
||
<p>When completing pathnames (where the tag used is ‘paths’) this style
|
||
accepts any number of patterns as the value in addition to the boolean
|
||
values. Pathnames matching one of these patterns will be accepted
|
||
immediately even if the command line contains some more partially typed
|
||
pathname components and these match no file under the directory
|
||
accepted.</p>
|
||
<p>This style is also used by the _expand completer to decide if words
|
||
beginning with a tilde or parameter expansion should be expanded. For
|
||
example, if there are parameters foo and foobar, the string ‘$foo’ will
|
||
only be expanded if accept-exact is set to ‘true’; otherwise the
|
||
completion system will be allowed to complete $foo to $foobar. If the
|
||
style is set to ‘continue’, _expand will add the expansion as a match
|
||
and the completion system will also be allowed to continue.</p>
|
||
<p><span id="index-accept_002dexact_002ddirs_002c-completion-style"></span></p>
|
||
<p>accept-exact-dirs</p>
|
||
<p>This is used by filename completion. Unlike accept-exact it is a
|
||
boolean. By default, filename completion examines all components of a
|
||
path to see if there are completions of that component, even if the
|
||
component matches an existing directory. For example, when completion
|
||
after /usr/bin/, the function examines possible completions to /usr.</p>
|
||
<p>When this style is ‘true’, any prefix of a path that matches an existing
|
||
directory is accepted without any attempt to complete it further. Hence,
|
||
in the given example, the path /usr/bin/ is accepted immediately and
|
||
completion tried in that directory.</p>
|
||
<p>This style is also useful when completing after directories that
|
||
magically appear when referenced, such as ZFS .zfs directories or NetApp
|
||
.snapshot directories. When the style is set the shell does not check
|
||
for the existence of the directory within the parent directory.</p>
|
||
<p>If you wish to inhibit this behaviour entirely, set the path-completion
|
||
style (see below) to ‘false’.</p>
|
||
<p><span id="index-add_002dspace_002c-completion-style"></span></p>
|
||
<p>add-space</p>
|
||
<p>This style is used by the _expand completer. If it is ‘true’ (the
|
||
default), a space will be inserted after all words resulting from the
|
||
expansion, or a slash in the case of directory names. If the value is
|
||
‘file’, the completer will only add a space to names of existing files.
|
||
Either a boolean ‘true’ or the value ‘file’ may be combined with
|
||
‘subst’, in which case the completer will not add a space to words
|
||
generated from the expansion of a substitution of the form ‘$(<code>...</code>)’ or
|
||
‘${<code>...</code>}’.</p>
|
||
<p>The _prefix completer uses this style as a simple boolean value to
|
||
decide if a space should be inserted before the suffix.</p>
|
||
<p><span id="index-ambiguous_002c-completion-style"></span></p>
|
||
<p>ambiguous</p>
|
||
<p>This applies when completing non-final components of filename paths, in
|
||
other words those with a trailing slash. If it is set, the cursor is
|
||
left after the first ambiguous component, even if menu completion is in
|
||
use. The style is always tested with the paths tag.</p>
|
||
<p><span id="index-assign_002dlist_002c-completion-style"></span></p>
|
||
<p>assign-list</p>
|
||
<p>When completing after an equals sign that is being treated as an
|
||
assignment, the completion system normally completes only one filename.
|
||
In some cases the value may be a list of filenames separated by colons,
|
||
as with PATH and similar parameters. This style can be set to a list of
|
||
patterns matching the names of such parameters.</p>
|
||
<p>The default is to complete lists when the word on the line already
|
||
contains a colon.</p>
|
||
<p><span id="index-auto_002ddescription_002c-completion-style"></span></p>
|
||
<p>auto-description</p>
|
||
<p>If set, this style’s value will be used as the description for options
|
||
that are not described by the completion functions, but that have
|
||
exactly one argument. The sequence ‘%d’ in the value will be replaced by
|
||
the description for this argument. Depending on personal preferences, it
|
||
may be useful to set this style to something like ‘specify: %d’. Note
|
||
that this may not work for some commands.</p>
|
||
<p><span id="index-avoid_002dcompleter_002c-completion-style"></span></p>
|
||
<p>avoid-completer</p>
|
||
<p>This is used by the _all_matches completer to decide if the string
|
||
consisting of all matches should be added to the list currently being
|
||
generated. Its value is a list of names of completers. If any of these
|
||
is the name of the completer that generated the matches in this
|
||
completion, the string will not be added.</p>
|
||
<p>The default value for this style is ‘_expand _old_list _correct
|
||
_approximate’, i.e. it contains the completers for which a string with
|
||
all matches will almost never be wanted.</p>
|
||
<p><span id="index-cache_002dpath_002c-completion-style"></span></p>
|
||
<p>cache-path</p>
|
||
<p>This style defines the path where any cache files containing dumped
|
||
completion data are stored. It defaults to ‘$ZDOTDIR/.zcompcache’, or
|
||
‘$HOME/.zcompcache’ if $ZDOTDIR is not defined. The completion cache
|
||
will not be used unless the use-cache style is set.</p>
|
||
<p><span id="index-cache_002dpolicy_002c-completion-style"></span></p>
|
||
<p>cache-policy</p>
|
||
<p>This style defines the function that will be used to determine whether a
|
||
cache needs rebuilding. See the section on the _cache_invalid function
|
||
below.</p>
|
||
<p><span id="index-call_002dcommand_002c-completion-style"></span></p>
|
||
<p>call-command</p>
|
||
<p>This style is used in the function for commands such as make and ant
|
||
where calling the command directly to generate matches suffers problems
|
||
such as being slow or, as in the case of make can potentially cause
|
||
actions in the makefile to be executed. If it is set to ‘true’ the
|
||
command is called to generate matches. The default value of this style
|
||
is ‘false’.</p>
|
||
<p><span id="index-command_002c-completion-style"></span></p>
|
||
<p>command</p>
|
||
<p>In many places, completion functions need to call external commands to
|
||
generate the list of completions. This style can be used to override the
|
||
command that is called in some such cases. The elements of the value are
|
||
joined with spaces to form a command line to execute. The value can also
|
||
start with a hyphen, in which case the usual command will be added to
|
||
the end; this is most useful for putting ‘builtin’ or ‘command’ in front
|
||
to make sure the appropriate version of a command is called, for example
|
||
to avoid calling a shell function with the same name as an external
|
||
command.</p>
|
||
<p>As an example, the completion function for process IDs uses this style
|
||
with the processes tag to generate the IDs to complete and the list of
|
||
processes to display (if the verbose style is ‘true’). The list produced
|
||
by the command should look like the output of the ps command. The first
|
||
line is not displayed, but is searched for the string ‘PID’ (or ‘pid’)
|
||
to find the position of the process IDs in the following lines. If the
|
||
line does not contain ‘PID’, the first numbers in each of the other
|
||
lines are taken as the process IDs to complete.</p>
|
||
<p>Note that the completion function generally has to call the specified
|
||
command for each attempt to generate the completion list. Hence care
|
||
should be taken to specify only commands that take a short time to run,
|
||
and in particular to avoid any that may never terminate.</p>
|
||
<p><span id="index-command_002dpath_002c-completion-style"></span></p>
|
||
<p>command-path</p>
|
||
<p>This is a list of directories to search for commands to complete. The
|
||
default for this style is the value of the special parameter path.</p>
|
||
<p><span id="index-commands_002c-completion-style"></span></p>
|
||
<p>commands</p>
|
||
<p>This is used by the function completing sub-commands for the system
|
||
initialisation scripts (residing in /etc/init.d or somewhere not too far
|
||
away from that). Its values give the default commands to complete for
|
||
those commands for which the completion function isn’t able to find them
|
||
out automatically. The default for this style are the two strings
|
||
‘start’ and ‘stop’.</p>
|
||
<p><span id="index-complete_002c-completion-style"></span></p>
|
||
<p>complete</p>
|
||
<p>This is used by the _expand_alias function when invoked as a bindable
|
||
command. If set to ‘true’ and the word on the command line is not the
|
||
name of an alias, matching alias names will be completed.</p>
|
||
<p><span id="index-complete_002doptions_002c-completion-style"></span></p>
|
||
<p>complete-options</p>
|
||
<p>This is used by the completer for cd, chdir and pushd. For these
|
||
commands a - is used to introduce a directory stack entry and completion
|
||
of these is far more common than completing options. Hence unless the
|
||
value of this style is ‘true’ options will not be completed, even after
|
||
an initial -. If it is ‘true’, options will be completed after an
|
||
initial - unless there is a preceding -- on the command line.</p>
|
||
<p><span id="index-completer_002c-completion-style"></span></p>
|
||
<p>completer</p>
|
||
<p>The strings given as the value of this style provide the names of the
|
||
completer functions to use. The available completer functions are
|
||
described in <a href="#Control-Functions">Control Functions</a>.</p>
|
||
<p>Each string may be either the name of a completer function or a string
|
||
of the form ‘<code>function</code>:<code>name</code>’. In the first case the <code>completer</code> field
|
||
of the context will contain the name of the completer without the
|
||
leading underscore and with all other underscores replaced by hyphens.
|
||
In the second case the <code>function</code> is the name of the completer to call,
|
||
but the context will contain the user-defined <code>name</code> in the <code>completer</code>
|
||
field of the context. If the <code>name</code> starts with a hyphen, the string for
|
||
the context will be build from the name of the completer function as in
|
||
the first case with the <code>name</code> appended to it. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer _complete _complete:-foo
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, completion will call the _complete completer twice, once using
|
||
‘complete’ and once using ‘complete-foo’ in the <code>completer</code> field of the
|
||
context. Normally, using the same completer more than once only makes
|
||
sense when used with the ‘<code>functions</code>:<code>name</code>’ form, because otherwise
|
||
the context name will be the same in all calls to the completer;
|
||
possible exceptions to this rule are the _ignored and _prefix
|
||
completers.</p>
|
||
<p>The default value for this style is ‘_complete _ignored’: only
|
||
completion will be done, first using the ignored-patterns style and the
|
||
$fignore array and then without ignoring matches.</p>
|
||
<p><span id="index-condition_002c-completion-style"></span></p>
|
||
<p>condition</p>
|
||
<p>This style is used by the _list completer function to decide if
|
||
insertion of matches should be delayed unconditionally. The default is
|
||
‘true’.</p>
|
||
<p><span id="index-delimiters_002c-completion-style"></span></p>
|
||
<p>delimiters</p>
|
||
<p>This style is used when adding a delimiter for use with history
|
||
modifiers or glob qualifiers that have delimited arguments. It is an
|
||
array of preferred delimiters to add. Non-special characters are
|
||
preferred as the completion system may otherwise become confused. The
|
||
default list is :, +, /, -, %. The list may be empty to force a
|
||
delimiter to be typed.</p>
|
||
<p><span id="index-disabled_002c-completion-style"></span></p>
|
||
<p>disabled</p>
|
||
<p>If this is set to ‘true’, the _expand_alias completer and bindable
|
||
command will try to expand disabled aliases, too. The default is
|
||
‘false’.</p>
|
||
<p><span id="index-domains_002c-completion-style"></span></p>
|
||
<p>domains</p>
|
||
<p>A list of names of network domains for completion. If this is not set,
|
||
domain names will be taken from the file /etc/resolv.conf.</p>
|
||
<p><span id="index-environ_002c-completion-style"></span></p>
|
||
<p>environ</p>
|
||
<p>The environ style is used when completing for ‘sudo’. It is set to an
|
||
array of ‘<code>VAR</code>=<code>value</code>’ assignments to be exported into the local
|
||
environment before the completion for the target command is invoked.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:sudo::' environ \
|
||
PATH="/sbin:/usr/sbin:$PATH" HOME="/root"
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-expand_002c-completion-style"></span></p>
|
||
<p>expand</p>
|
||
<p>This style is used when completing strings consisting of multiple parts,
|
||
such as path names.</p>
|
||
<p>If one of its values is the string ‘prefix’, the partially typed word
|
||
from the line will be expanded as far as possible even if trailing parts
|
||
cannot be completed.</p>
|
||
<p>If one of its values is the string ‘suffix’, matching names for
|
||
components after the first ambiguous one will also be added. This means
|
||
that the resulting string is the longest unambiguous string possible.
|
||
However, menu completion can be used to cycle through all matches.</p>
|
||
<p><span id="index-extra_002dverbose_002c-completion-style"></span></p>
|
||
<p>extra-verbose</p>
|
||
<p>If set, the completion listing is more verbose at the cost of a probable
|
||
decrease in completion speed. Completion performance will suffer if this
|
||
style is set to ‘true’.</p>
|
||
<p><span id="index-fake_002c-completion-style"></span></p>
|
||
<p>fake</p>
|
||
<p>This style may be set for any completion context. It specifies
|
||
additional strings that will always be completed in that context. The
|
||
form of each string is ‘<code>value</code>:<code>description</code>’; the colon and
|
||
description may be omitted, but any literal colons in <code>value</code> must be
|
||
quoted with a backslash. Any <code>description</code> provided is shown alongside
|
||
the value in completion listings.</p>
|
||
<p>It is important to use a sufficiently restrictive context when
|
||
specifying fake strings. Note that the styles fake-files and
|
||
fake-parameters provide additional features when completing files or
|
||
parameters.</p>
|
||
<p><span id="index-fake_002dalways_002c-completion-style"></span></p>
|
||
<p>fake-always</p>
|
||
<p>This works identically to the fake style except that the
|
||
ignored-patterns style is not applied to it. This makes it possible to
|
||
override a set of matches completely by setting the ignored patterns to
|
||
‘*’.</p>
|
||
<p>The following shows a way of supplementing any tag with arbitrary data,
|
||
but having it behave for display purposes like a separate tag. In this
|
||
example we use the features of the tag-order style to divide the
|
||
named-directories tag into two when performing completion with the
|
||
standard completer complete for arguments of cd. The tag
|
||
named-directories-normal behaves as normal, but the tag
|
||
named-directories-mine contains a fixed set of directories. This has the
|
||
effect of adding the match group ‘extra directories’ with the given
|
||
completions.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion::complete:cd:*' tag-order \
|
||
'named-directories:-mine:extra\ directories
|
||
named-directories:-normal:named\ directories *'
|
||
zstyle ':completion::complete:cd:*:named-directories-mine' \
|
||
fake-always mydir1 mydir2
|
||
zstyle ':completion::complete:cd:*:named-directories-mine' \
|
||
ignored-patterns '*'
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-fake_002dfiles_002c-completion-style"></span></p>
|
||
<p>fake-files</p>
|
||
<p>This style is used when completing files and looked up without a tag.
|
||
Its values are of the form ‘<code>dir</code>:<code>names...</code>’. This will add the <code>names</code>
|
||
(strings separated by spaces) as possible matches when completing in the
|
||
directory <code>dir</code>, even if no such files really exist. The dir may be a
|
||
pattern; pattern characters or colons in <code>dir</code> should be quoted with a
|
||
backslash to be treated literally.</p>
|
||
<p>This can be useful on systems that support special file systems whose
|
||
top-level pathnames can not be listed or generated with glob patterns
|
||
(but see accept-exact-dirs for a more general way of dealing with this
|
||
problem). It can also be used for directories for which one does not
|
||
have read permission.</p>
|
||
<p>The pattern form can be used to add a certain ‘magic’ entry to all
|
||
directories on a particular file system.</p>
|
||
<p><span id="index-fake_002dparameters_002c-completion-style"></span></p>
|
||
<p>fake-parameters</p>
|
||
<p>This is used by the completion function for parameter names. Its values
|
||
are names of parameters that might not yet be set but should be
|
||
completed nonetheless. Each name may also be followed by a colon and a
|
||
string specifying the type of the parameter (like ‘scalar’, ‘array’ or
|
||
‘integer’). If the type is given, the name will only be completed if
|
||
parameters of that type are required in the particular context. Names
|
||
for which no type is specified will always be completed.</p>
|
||
<p><span id="index-file_002dlist_002c-completion-style"></span></p>
|
||
<p>file-list</p>
|
||
<p>This style controls whether files completed using the standard builtin
|
||
mechanism are to be listed with a long list similar to ls -l. Note that
|
||
this feature uses the shell module zsh/stat for file information; this
|
||
loads the builtin stat this the following code can be included in an
|
||
initialization file:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zmodload -i zsh/stat
|
||
disable stat
|
||
</code></pre>
|
||
</div>
|
||
<p>The style may either be set to a ‘true’ value (or ‘all’), or one of the
|
||
values ‘insert’ or ‘list’, indicating that files are to be listed in
|
||
long format in all circumstances, or when attempting to insert a file
|
||
name, or when listing file names without attempting to insert one.</p>
|
||
<p>More generally, the value may be an array of any of the above values,
|
||
optionally followed by =<code>num</code>. If <code>num</code> is present it gives the maximum
|
||
number of matches for which long listing style will be used. For
|
||
example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' file-list list=20 insert=10
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that long format will be used when listing up to 20 files or
|
||
inserting a file with up to 10 matches (assuming a listing is to be
|
||
shown at all, for example on an ambiguous completion), else short format
|
||
will be used.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -e ':completion:*' file-list \
|
||
'(( ${+NUMERIC} )) && reply=(true)'
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that long format will be used any time a numeric argument is
|
||
supplied, else short format.</p>
|
||
<p><span id="index-file_002dpatterns_002c-completion-style"></span></p>
|
||
<p>file-patterns</p>
|
||
<p>This is used by the standard function for completing filenames, _files.
|
||
If the style is unset up to three tags are offered,
|
||
‘globbed-files’,‘directories’ and ‘all-files’, depending on the types of
|
||
files expected by the caller of _files. The first two (‘globbed-files’
|
||
and ‘directories’) are normally offered together to make it easier to
|
||
complete files in sub-directories.</p>
|
||
<p>The file-patterns style provides alternatives to the default tags, which
|
||
are not used. Its value consists of elements of the form
|
||
‘<code>pattern</code>:<code>tag</code>’; each string may contain any number of such
|
||
specifications separated by spaces.</p>
|
||
<p>The <code>pattern</code> is a pattern that is to be used to generate filenames. Any
|
||
occurrence of the sequence ‘%p’ is replaced by any pattern(s) passed by
|
||
the function calling _files. Colons in the pattern must be preceded by
|
||
a backslash to make them distinguishable from the colon before the
|
||
<code>tag</code>. If more than one pattern is needed, the patterns can be given
|
||
inside braces, separated by commas.</p>
|
||
<p>The <code>tag</code>s of all strings in the value will be offered by _files and
|
||
used when looking up other styles. Any <code>tag</code>s in the same word will be
|
||
offered at the same time and before later words. If no ‘:<code>tag</code>’ is given
|
||
the ‘files’ tag will be used.</p>
|
||
<p>The <code>tag</code> may also be followed by an optional second colon and a
|
||
description, which will be used for the ‘%d’ in the value of the format
|
||
style (if that is set) instead of the default description supplied by
|
||
the completion function. The inclusion of a description also gives
|
||
precedence to associated options such as for completion grouping so it
|
||
can be used where files should be separated.</p>
|
||
<p>For example, to make the rm command first complete only names of object
|
||
files and then the names of all files if there is no matching object
|
||
file:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:rm:*:*' file-patterns \
|
||
'*.o:object-files' '%p:all-files'
|
||
</code></pre>
|
||
</div>
|
||
<p>To alter the default behaviour of file completion — offer files matching
|
||
a pattern and directories on the first attempt, then all files — to
|
||
offer only matching files on the first attempt, then directories, and
|
||
finally all files:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' file-patterns \
|
||
'%p:globbed-files' '*(-/):directories' '*:all-files'
|
||
</code></pre>
|
||
</div>
|
||
<p>This works even where there is no special pattern: _files matches all
|
||
files using the pattern ‘*’ at the first step and stops when it sees
|
||
this pattern. Note also it will never try a pattern more than once for a
|
||
single completion attempt.</p>
|
||
<p>To separate directories into a separate group from the files but still
|
||
complete them at the first attempt, a description needs to be given.
|
||
Note that directories need to be explicitly excluded from the
|
||
globbed-files because ‘*’ will match directories. For grouping, it is
|
||
also necessary to set the group-name style.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' file-patterns \
|
||
'%p(^-/):globbed-files *(-/):directories:location'
|
||
</code></pre>
|
||
</div>
|
||
<p>During the execution of completion functions, the EXTENDED_GLOB option
|
||
is in effect, so the characters ‘#’, ‘~’ and ‘^’ have special meanings
|
||
in the patterns.</p>
|
||
<p><span id="index-file_002dsort_002c-completion-style"></span></p>
|
||
<p>file-sort</p>
|
||
<p>The standard filename completion function uses this style without a tag
|
||
to determine in which order the names should be listed; menu completion
|
||
will cycle through them in the same order. The possible values are:
|
||
‘size’ to sort by the size of the file; ‘links’ to sort by the number of
|
||
links to the file; ‘modification’ (or ‘time’ or ‘date’) to sort by the
|
||
last modification time; ‘access’ to sort by the last access time; and
|
||
‘inode’ (or ‘change’) to sort by the last inode change time. If the
|
||
style is set to any other value, or is unset, files will be sorted
|
||
alphabetically by name. If the value contains the string ‘reverse’,
|
||
sorting is done in the opposite order. If the value contains the string
|
||
‘follow’, timestamps are associated with the targets of symbolic links;
|
||
the default is to use the timestamps of the links themselves.</p>
|
||
<p><span id="index-file_002dsplit_002dchars_002c-completion-style"></span></p>
|
||
<p>file-split-chars</p>
|
||
<p>A set of characters that will cause <em>all</em> file completions for the given
|
||
context to be split at the point where any of the characters occurs. A
|
||
typical use is to set the style to :; then everything up to and
|
||
including the last : in the string so far is ignored when completing
|
||
files. As this is quite heavy-handed, it is usually preferable to update
|
||
completion functions for contexts where this behaviour is useful.</p>
|
||
<p><span id="index-filter_002c-completion-style"></span></p>
|
||
<p>filter</p>
|
||
<p>The ldap plugin of email address completion (see _email_addresses) uses
|
||
this style to specify the attributes to match against when filtering
|
||
entries. So for example, if the style is set to ‘sn’, matching is done
|
||
against surnames. Standard LDAP filtering is used so normal completion
|
||
matching is bypassed. If this style is not set, the LDAP plugin is
|
||
skipped. You may also need to set the command style to specify how to
|
||
connect to your LDAP server.</p>
|
||
<p><span id="index-force_002dlist_002c-completion-style"></span></p>
|
||
<p>force-list</p>
|
||
<p>This forces a list of completions to be shown at any point where listing
|
||
is done, even in cases where the list would usually be suppressed. For
|
||
example, normally the list is only shown if there are at least two
|
||
different matches. By setting this style to ‘always’, the list will
|
||
always be shown, even if there is only a single match that will
|
||
immediately be accepted. The style may also be set to a number. In this
|
||
case the list will be shown if there are at least that many matches,
|
||
even if they would all insert the same string.</p>
|
||
<p>This style is tested for the default tag as well as for each tag valid
|
||
for the current completion. Hence the listing can be forced only for
|
||
certain types of match.</p>
|
||
<p><span id="index-format_002c-completion-style"></span></p>
|
||
<p>format</p>
|
||
<p>If this is set for the descriptions tag, its value is used as a string
|
||
to display above matches in completion lists. The sequence ‘%d’ in this
|
||
string will be replaced with a short description of what these matches
|
||
are. This string may also contain the output attribute sequences
|
||
understood by compadd -X (see <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a>).</p>
|
||
<p>The style is tested with each tag valid for the current completion
|
||
before it is tested for the descriptions tag. Hence different format
|
||
strings can be defined for different types of match.</p>
|
||
<p>Note also that some completer functions define additional ‘%’-sequences.
|
||
These are described for the completer functions that make use of them.</p>
|
||
<p>Some completion functions display messages that may be customised by
|
||
setting this style for the messages tag. Here, the ‘%d’ is replaced with
|
||
a message given by the completion function.</p>
|
||
<p>Finally, the format string is looked up with the warnings tag, for use
|
||
when no matches could be generated at all. In this case the ‘%d’ is
|
||
replaced with the descriptions for the matches that were expected
|
||
separated by spaces. The sequence ‘%D’ is replaced with the same
|
||
descriptions separated by newlines.</p>
|
||
<p>It is possible to use printf-style field width specifiers with ‘%d’ and
|
||
similar escape sequences. This is handled by the zformat builtin command
|
||
from the zsh/zutil module, see <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>.</p>
|
||
<p><span id="index-gain_002dprivileges_002c-completion-style"></span></p>
|
||
<p>gain-privileges</p>
|
||
<p>If set to true, this style enables the use of commands like sudo or doas
|
||
to gain extra privileges when retrieving information for completion.
|
||
This is only done when a command such as sudo appears on the
|
||
command-line. To force the use of, e.g. sudo or to override any prefix
|
||
that might be added due to gain-privileges, the command style can be
|
||
used with a value that begins with a hyphen.</p>
|
||
<p><span id="index-glob_002c-completion-style"></span></p>
|
||
<p>glob</p>
|
||
<p>This is used by the _expand completer. If it is set to ‘true’ (the
|
||
default), globbing will be attempted on the words resulting from a
|
||
previous substitution (see the substitute style) or else the original
|
||
string from the line.</p>
|
||
<p><span id="index-global_002c-completion-style"></span></p>
|
||
<p>global</p>
|
||
<p>If this is set to ‘true’ (the default), the _expand_alias completer and
|
||
bindable command will try to expand global aliases.</p>
|
||
<p><span id="index-group_002dname_002c-completion-style"></span></p>
|
||
<p>group-name</p>
|
||
<p>The completion system can group different types of matches, which appear
|
||
in separate lists. This style can be used to give the names of groups
|
||
for particular tags. For example, in command position the completion
|
||
system generates names of builtin and external commands, names of
|
||
aliases, shell functions and parameters and reserved words as possible
|
||
completions. To have the external commands and shell functions listed
|
||
separately:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:-command-:*:commands' \
|
||
group-name commands
|
||
zstyle ':completion:*:*:-command-:*:functions' \
|
||
group-name functions
|
||
</code></pre>
|
||
</div>
|
||
<p>As a consequence, any match with the same tag will be displayed in the
|
||
same group.</p>
|
||
<p>If the name given is the empty string the name of the tag for the
|
||
matches will be used as the name of the group. So, to have all different
|
||
types of matches displayed separately, one can just set:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' group-name ''
|
||
</code></pre>
|
||
</div>
|
||
<p>All matches for which no group name is defined will be put in a group
|
||
named -default-.</p>
|
||
<p>To display the group name in the output, see the format style (q.v.)
|
||
under the descriptions tag.</p>
|
||
<p><span id="index-group_002dorder_002c-completion-style"></span></p>
|
||
<p>group-order</p>
|
||
<p>This style is additional to the group-name style to specify the order
|
||
for display of the groups defined by that style (compare tag-order,
|
||
which determines which completions appear at all). The groups named are
|
||
shown in the given order; any other groups are shown in the order
|
||
defined by the completion function.</p>
|
||
<p>For example, to have names of builtin commands, shell functions and
|
||
external commands appear in that order when completing in command
|
||
position:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:-command-:*:*' group-order \
|
||
builtins functions commands
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-groups_002c-completion-style"></span></p>
|
||
<p>groups</p>
|
||
<p>A list of names of UNIX groups. If this is not set, group names are
|
||
taken from the YP database or the file ‘/etc/group’.</p>
|
||
<p><span id="index-hidden_002c-completion-style"></span></p>
|
||
<p>hidden</p>
|
||
<p>If this is set to ‘true’, matches for the given context will not be
|
||
listed, although any description for the matches set with the format
|
||
style will be shown. If it is set to ‘all’, not even the description
|
||
will be displayed.</p>
|
||
<p>Note that the matches will still be completed; they are just not shown
|
||
in the list. To avoid having matches considered as possible completions
|
||
at all, the tag-order style can be modified as described below.</p>
|
||
<p><span id="index-hosts_002c-completion-style"></span></p>
|
||
<p>hosts</p>
|
||
<p>A list of names of hosts that should be completed. If this is not set,
|
||
hostnames are taken from the file ‘/etc/hosts’.</p>
|
||
<p><span id="index-hosts_002dports_002c-completion-style"></span></p>
|
||
<p>hosts-ports</p>
|
||
<p>This style is used by commands that need or accept hostnames and network
|
||
ports. The strings in the value should be of the form ‘<code>host</code>:<code>port</code>’.
|
||
Valid ports are determined by the presence of hostnames; multiple ports
|
||
for the same host may appear.</p>
|
||
<p><span id="index-ignore_002dline_002c-completion-style"></span></p>
|
||
<p>ignore-line</p>
|
||
<p>This is tested for each tag valid for the current completion. If it is
|
||
set to ‘true’, none of the words that are already on the line will be
|
||
considered as possible completions. If it is set to ‘current’, the word
|
||
the cursor is on will not be considered as a possible completion. The
|
||
value ‘current-shown’ is similar but only applies if the list of
|
||
completions is currently shown on the screen. Finally, if the style is
|
||
set to ‘other’, all words on the line except for the current one will be
|
||
excluded from the possible completions.</p>
|
||
<p>The values ‘current’ and ‘current-shown’ are a bit like the opposite of
|
||
the accept-exact style: only strings with missing characters will be
|
||
completed.</p>
|
||
<p>Note that you almost certainly don’t want to set this to ‘true’ or
|
||
‘other’ for a general context such as ‘:completion:*’. This is because
|
||
it would disallow completion of, for example, options multiple times
|
||
even if the command in question accepts the option more than once.</p>
|
||
<p><span id="index-ignore_002dparents_002c-completion-style"></span></p>
|
||
<p>ignore-parents</p>
|
||
<p>The style is tested without a tag by the function completing pathnames
|
||
in order to determine whether to ignore the names of directories already
|
||
mentioned in the current word, or the name of the current working
|
||
directory. The value must include one or both of the following strings:</p>
|
||
<p>parent<br />
|
||
The name of any directory whose path is already contained in the word on
|
||
the line is ignored. For example, when completing after foo/../, the
|
||
directory foo will not be considered a valid completion.</p>
|
||
<p>pwd<br />
|
||
The name of the current working directory will not be completed; hence,
|
||
for example, completion after ../ will not use the name of the current
|
||
directory.</p>
|
||
<p>In addition, the value may include one or both of:</p>
|
||
<p>..<br />
|
||
Ignore the specified directories only when the word on the line contains
|
||
the substring ‘../’.</p>
|
||
<p>directory<br />
|
||
Ignore the specified directories only when names of directories are
|
||
completed, not when completing names of files.</p>
|
||
<p>Excluded values act in a similar fashion to values of the
|
||
ignored-patterns style, so they can be restored to consideration by the
|
||
_ignored completer.</p>
|
||
<p><span id="index-ignored_002dpatterns_002c-completion-style"></span></p>
|
||
<p>ignored-patterns</p>
|
||
<p>A list of patterns; any trial completion matching one of the patterns
|
||
will be excluded from consideration. The _ignored completer can appear
|
||
in the list of completers to restore the ignored matches. This is a more
|
||
configurable version of the shell parameter $fignore.</p>
|
||
<p>Note that the EXTENDED_GLOB option is set during the execution of
|
||
completion functions, so the characters ‘#’, ‘~’ and ‘^’ have special
|
||
meanings in the patterns.</p>
|
||
<p><span id="index-insert_002c-completion-style"></span></p>
|
||
<p>insert</p>
|
||
<p>This style is used by the _all_matches completer to decide whether to
|
||
insert the list of all matches unconditionally instead of adding the
|
||
list as another match.</p>
|
||
<p><span id="index-insert_002dids_002c-completion-style"></span></p>
|
||
<p>insert-ids</p>
|
||
<p>When completing process IDs, for example as arguments to the kill and
|
||
wait builtins the name of a command may be converted to the appropriate
|
||
process ID. A problem arises when the process name typed is not unique.
|
||
By default (or if this style is set explicitly to ‘menu’) the name will
|
||
be converted immediately to a set of possible IDs, and menu completion
|
||
will be started to cycle through them.</p>
|
||
<p>If the value of the style is ‘single’, the shell will wait until the
|
||
user has typed enough to make the command unique before converting the
|
||
name to an ID; attempts at completion will be unsuccessful until that
|
||
point. If the value is any other string, menu completion will be started
|
||
when the string typed by the user is longer than the common prefix to
|
||
the corresponding IDs.</p>
|
||
<p><span id="index-insert_002dsections_002c-completion-style"></span></p>
|
||
<p>insert-sections</p>
|
||
<p>This style is used with tags of the form ‘manuals.<code>X</code>’ when completing
|
||
names of manual pages. If set and the <code>X</code> in the tag name matches the
|
||
section number of the page being completed, the section number is
|
||
inserted along with the page name. For example, given</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:manuals.*' insert-sections true
|
||
</code></pre>
|
||
</div>
|
||
<p>man ssh_<TAB> may be completed to man 5 ssh_config.</p>
|
||
<p>The value may also be set to one of ‘prepend’, or ‘suffix’. ‘prepend’
|
||
behaves the same as ‘true’ as in the above example, while ‘suffix’ would
|
||
complete man ssh_<TAB> as man ssh_config.5.</p>
|
||
<p>This is especially useful in conjunction with separate-sections, as it
|
||
ensures that the page requested of man corresponds to the one displayed
|
||
in the completion listing when there are multiple pages with the same
|
||
name (e.g., printf(1) and printf(3)).</p>
|
||
<p>The default for this style is ‘false’.</p>
|
||
<p><span id="index-insert_002dtab_002c-completion-style"></span></p>
|
||
<p>insert-tab</p>
|
||
<p>If this is set to ‘true’, the completion system will insert a TAB
|
||
character (assuming that was used to start completion) instead of
|
||
performing completion when there is no non-blank character to the left
|
||
of the cursor. If it is set to ‘false’, completion will be done even
|
||
there.</p>
|
||
<p>The value may also contain the substrings ‘pending’ or ‘pending=<code>val</code>’.
|
||
In this case, the typed character will be inserted instead of starting
|
||
completion when there is unprocessed input pending. If a <code>val</code> is given,
|
||
completion will not be done if there are at least that many characters
|
||
of unprocessed input. This is often useful when pasting characters into
|
||
a terminal. Note however, that it relies on the $PENDING special
|
||
parameter from the zsh/zle module being set properly which is not
|
||
guaranteed on all platforms.</p>
|
||
<p>The default value of this style is ‘true’ except for completion within
|
||
vared builtin command where it is ‘false’.</p>
|
||
<p><span id="index-insert_002dunambiguous_002c-completion-style"></span></p>
|
||
<p>insert-unambiguous</p>
|
||
<p>This is used by the _match and _approximate completers. These
|
||
completers are often used with menu completion since the word typed may
|
||
bear little resemblance to the final completion. However, if this style
|
||
is ‘true’, the completer will start menu completion only if it could
|
||
find no unambiguous initial string at least as long as the original
|
||
string typed by the user.</p>
|
||
<p>In the case of the _approximate completer, the completer field in the
|
||
context will already have been set to one of correct-<code>num</code> or
|
||
approximate-<code>num</code>, where <code>num</code> is the number of errors that were
|
||
accepted.</p>
|
||
<p>In the case of the _match completer, the style may also be set to the
|
||
string ‘pattern’. Then the pattern on the line is left unchanged if it
|
||
does not match unambiguously.</p>
|
||
<p><span id="index-keep_002dprefix_002c-completion-style"></span></p>
|
||
<p>keep-prefix</p>
|
||
<p>This style is used by the _expand completer. If it is ‘true’, the
|
||
completer will try to keep a prefix containing a tilde or parameter
|
||
expansion. Hence, for example, the string ‘~/f*’ would be expanded to
|
||
‘~/foo’ instead of ‘/home/user/foo’. If the style is set to ‘changed’
|
||
(the default), the prefix will only be left unchanged if there were
|
||
other changes between the expanded words and the original word from the
|
||
command line. Any other value forces the prefix to be expanded
|
||
unconditionally.</p>
|
||
<p>The behaviour of _expand when this style is ‘true’ is to cause _expand
|
||
to give up when a single expansion with the restored prefix is the same
|
||
as the original; hence any remaining completers may be called.</p>
|
||
<p><span id="index-known_002dhosts_002dfiles"></span></p>
|
||
<p>known-hosts-files</p>
|
||
<p>This style should contain a list of files to search for host names and
|
||
(if the use-ip style is set) IP addresses in a format compatible with
|
||
ssh known_hosts files. If it is not set, the files
|
||
/etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are used.</p>
|
||
<p><span id="index-last_002dprompt_002c-completion-style"></span></p>
|
||
<p>last-prompt</p>
|
||
<p>This is a more flexible form of the ALWAYS_LAST_PROMPT option. If it is
|
||
‘true’, the completion system will try to return the cursor to the
|
||
previous command line after displaying a completion list. It is tested
|
||
for all tags valid for the current completion, then the default tag. The
|
||
cursor will be moved back to the previous line if this style is ‘true’
|
||
for all types of match. Note that unlike the ALWAYS_LAST_PROMPT option
|
||
this is independent of the numeric argument.</p>
|
||
<p><span id="index-list_002c-completion-style"></span></p>
|
||
<p>list</p>
|
||
<p>This style is used by the _history_complete_word bindable command. If
|
||
it is set to ‘true’ it has no effect. If it is set to ‘false’ matches
|
||
will not be listed. This overrides the setting of the options
|
||
controlling listing behaviour, in particular AUTO_LIST. The context
|
||
always starts with ‘:completion:history-words’.</p>
|
||
<p><span id="index-list_002dcolors_002c-completion-style"></span></p>
|
||
<p>list-colors</p>
|
||
<p>If the zsh/complist module is loaded, this style can be used to set
|
||
color specifications. This mechanism replaces the use of the ZLS_COLORS
|
||
and ZLS_COLOURS parameters described in <a href="Zsh-Modules.html#The-zsh_002fcomplist-Module">The zsh/complist
|
||
Module</a>, but the syntax is
|
||
the same.</p>
|
||
<p>If this style is set for the default tag, the strings in the value are
|
||
taken as specifications that are to be used everywhere. If it is set for
|
||
other tags, the specifications are used only for matches of the type
|
||
described by the tag. For this to work best, the group-name style must
|
||
be set to an empty string.</p>
|
||
<p>In addition to setting styles for specific tags, it is also possible to
|
||
use group names specified explicitly by the group-name tag together with
|
||
the ‘(group)’ syntax allowed by the ZLS_COLORS and ZLS_COLOURS
|
||
parameters and simply using the default tag.</p>
|
||
<p>It is possible to use any color specifications already set up for the
|
||
GNU version of the ls command:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:default' list-colors \
|
||
${(s.:.)LS_COLORS}
|
||
</code></pre>
|
||
</div>
|
||
<p>The default colors are the same as for the GNU ls command and can be
|
||
obtained by setting the style to an empty string (i.e. ’’).</p>
|
||
<p><span id="index-list_002ddirs_002dfirst_002c-completion-style"></span></p>
|
||
<p>list-dirs-first</p>
|
||
<p>This is used by file completion and corresponds to a particular setting
|
||
of the file-patterns style. If set, the default directories to be
|
||
completed are listed separately from and before completion for other
|
||
files.</p>
|
||
<p><span id="index-list_002dgrouped_002c-completion-style"></span></p>
|
||
<p>list-grouped</p>
|
||
<p>If this style is ‘true’ (the default), the completion system will try to
|
||
make certain completion listings more compact by grouping matches. For
|
||
example, options for commands that have the same description (shown when
|
||
the verbose style is set to ‘true’) will appear as a single entry.
|
||
However, menu selection can be used to cycle through all the matches.</p>
|
||
<p><span id="index-list_002dpacked_002c-completion-style"></span></p>
|
||
<p>list-packed</p>
|
||
<p>This is tested for each tag valid in the current context as well as the
|
||
default tag. If it is set to ‘true’, the corresponding matches appear in
|
||
listings as if the LIST_PACKED option were set. If it is set to ‘false’,
|
||
they are listed normally.</p>
|
||
<p><span id="index-list_002dprompt_002c-completion-style"></span></p>
|
||
<p>list-prompt</p>
|
||
<p>If this style is set for the default tag, completion lists that don’t
|
||
fit on the screen can be scrolled (see <a href="Zsh-Modules.html#The-zsh_002fcomplist-Module">The zsh/complist
|
||
Module</a>). The value, if
|
||
not the empty string, will be displayed after every screenful and the
|
||
shell will prompt for a key press; if the style is set to the empty
|
||
string, a default prompt will be used.</p>
|
||
<p>The value may contain the escape sequences: ‘%l’ or ‘%L’, which will be
|
||
replaced by the number of the last line displayed and the total number
|
||
of lines; ‘%m’ or ‘%M’, the number of the last match shown and the total
|
||
number of matches; and ‘%p’ and ‘%P’, ‘Top’ when at the beginning of the
|
||
list, ‘Bottom’ when at the end and the position shown as a percentage of
|
||
the total length otherwise. In each case the form with the uppercase
|
||
letter will be replaced by a string of fixed width, padded to the right
|
||
with spaces, while the lowercase form will be replaced by a variable
|
||
width string. As in other prompt strings, the escape sequences ‘%S’,
|
||
‘%s’, ‘%B’, ‘%b’, ‘%U’, ‘%u’ for entering and leaving the display modes
|
||
standout, bold and underline, and ‘%F’, ‘%f’, ‘%K’, ‘%k’ for changing
|
||
the foreground background colour, are also available, as is the form
|
||
‘%{...%}’ for enclosing escape sequences which display with zero (or,
|
||
with a numeric argument, some other) width.</p>
|
||
<p>After deleting this prompt the variable LISTPROMPT should be unset for
|
||
the removal to take effect.</p>
|
||
<p><span id="index-list_002drows_002dfirst_002c-completion-style"></span></p>
|
||
<p>list-rows-first</p>
|
||
<p>This style is tested in the same way as the list-packed style and
|
||
determines whether matches are to be listed in a rows-first fashion as
|
||
if the LIST_ROWS_FIRST option were set.</p>
|
||
<p><span id="index-list_002dseparator_002c-completion-style"></span></p>
|
||
<p>list-separator</p>
|
||
<p>The value of this style is used in completion listing to separate the
|
||
string to complete from a description when possible (e.g. when
|
||
completing options). It defaults to ‘--’ (two hyphens).</p>
|
||
<p><span id="index-list_002dsuffixes_002c-completion-style"></span></p>
|
||
<p>list-suffixes</p>
|
||
<p>This style is used by the function that completes filenames. If it is
|
||
‘true’, and completion is attempted on a string containing multiple
|
||
partially typed pathname components, all ambiguous components will be
|
||
shown. Otherwise, completion stops at the first ambiguous component.</p>
|
||
<p><span id="index-local_002c-completion-style"></span></p>
|
||
<p>local</p>
|
||
<p>This is for use with functions that complete URLs for which the
|
||
corresponding files are available directly from the file system. Its
|
||
value should consist of three strings: a hostname, the path to the
|
||
default web pages for the server, and the directory name used by a user
|
||
placing web pages within their home area.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' local toast \
|
||
/var/http/public/toast public_html
|
||
</code></pre>
|
||
</div>
|
||
<p>Completion after ‘http://toast/stuff/’ will look for files in the
|
||
directory /var/http/public/toast/stuff, while completion after
|
||
‘http://toast/~yousir/’ will look for files in the directory
|
||
~yousir/public_html.</p>
|
||
<p><span id="index-mail_002ddirectory_002c-completion-style"></span></p>
|
||
<p>mail-directory</p>
|
||
<p>If set, zsh will assume that mailbox files can be found in the directory
|
||
specified. It defaults to ‘~/Mail’.</p>
|
||
<p><span id="index-match_002doriginal_002c-completion-style"></span></p>
|
||
<p>match-original</p>
|
||
<p>This is used by the _match completer. If it is set to only, _match
|
||
will try to generate matches without inserting a ‘*’ at the cursor
|
||
position. If set to any other non-empty value, it will first try to
|
||
generate matches without inserting the ‘*’ and if that yields no
|
||
matches, it will try again with the ‘*’ inserted. If it is unset or set
|
||
to the empty string, matching will only be performed with the ‘*’
|
||
inserted.</p>
|
||
<p><span id="index-matcher_002c-completion-style"></span></p>
|
||
<p>matcher</p>
|
||
<p>This style is tested separately for each tag valid in the current
|
||
context. Its value is placed before any match specifications given by
|
||
the matcher-list style so can override them via the use of an x:
|
||
specification. The value should be in the form described in <a href="Completion-Widgets.html#Completion-Matching-Control">Completion
|
||
Matching Control</a>.
|
||
For examples of this, see the description of the tag-order style.</p>
|
||
<p>For notes comparing the use of this and the matcher-list style, see
|
||
under the description of the tag-order style.</p>
|
||
<p><span id="index-matcher_002dlist_002c-completion-style"></span></p>
|
||
<p>matcher-list</p>
|
||
<p>This style can be set to a list of match specifications that are to be
|
||
applied everywhere. Match specifications are described in <a href="Completion-Widgets.html#Completion-Matching-Control">Completion
|
||
Matching Control</a>.
|
||
The completion system will try them one after another for each completer
|
||
selected. For example, to try first simple completion and, if that
|
||
generates no matches, case-insensitive completion:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'
|
||
</code></pre>
|
||
</div>
|
||
<p>By default each specification replaces the previous one; however, if a
|
||
specification is prefixed with +, it is added to the existing list.
|
||
Hence it is possible to create increasingly general specifications
|
||
without repetition:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' matcher-list \
|
||
'' '+m:{a-z}={A-Z}' '+m:{A-Z}={a-z}'
|
||
</code></pre>
|
||
</div>
|
||
<p>It is possible to create match specifications valid for particular
|
||
completers by using the third field of the context. This applies only to
|
||
completers that override the global matcher-list, which as of this
|
||
writing includes only _prefix and _ignored. For example, to use the
|
||
completers _complete and _prefix but allow case-insensitive completion
|
||
only with _complete:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer _complete _prefix
|
||
zstyle ':completion:*:complete:*:*:*' matcher-list \
|
||
'' 'm:{a-zA-Z}={A-Za-z}'
|
||
</code></pre>
|
||
</div>
|
||
<p>User-defined names, as explained for the completer style, are available.
|
||
This makes it possible to try the same completer more than once with
|
||
different match specifications each time. For example, to try normal
|
||
completion without a match specification, then normal completion with
|
||
case-insensitive matching, then correction, and finally partial-word
|
||
completion:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer \
|
||
_complete _correct _complete:foo
|
||
zstyle ':completion:*:complete:*:*:*' matcher-list \
|
||
'' 'm:{a-zA-Z}={A-Za-z}'
|
||
zstyle ':completion:*:foo:*:*:*' matcher-list \
|
||
'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'
|
||
</code></pre>
|
||
</div>
|
||
<p>If the style is unset in any context no match specification is applied.
|
||
Note also that some completers such as _correct and _approximate do
|
||
not use the match specifications at all, though these completers will
|
||
only ever be called once even if the matcher-list contains more than one
|
||
element.</p>
|
||
<p>Where multiple specifications are useful, note that the <em>entire</em>
|
||
completion is done for each element of matcher-list, which can quickly
|
||
reduce the shell’s performance. As a rough rule of thumb, hand, putting
|
||
multiple space-separated values into the same string does not have an
|
||
appreciable impact on performance.</p>
|
||
<p>If there is no current matcher or it is empty, and the option
|
||
NO_CASE_GLOB is in effect, the matching for files is performed
|
||
case-insensitively in any case. However, any matcher must explicitly
|
||
specify case-insensitive matching if that is required.</p>
|
||
<p>For notes comparing the use of this and the matcher style, see under the
|
||
description of the tag-order style.</p>
|
||
<p><span id="index-max_002derrors_002c-completion-style"></span></p>
|
||
<p>max-errors</p>
|
||
<p>This is used by the _approximate and _correct completer functions to
|
||
determine the maximum number of errors to allow. The completer will try
|
||
to generate completions by first allowing one error, then two errors,
|
||
and so on, until either a match or matches were found or the maximum
|
||
number of errors given by this style has been reached.</p>
|
||
<p>If the value for this style contains the string ‘numeric’, the completer
|
||
function will take any numeric argument as the maximum number of errors
|
||
allowed. For example, with</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:approximate:::' max-errors 2 numeric
|
||
</code></pre>
|
||
</div>
|
||
<p>two errors are allowed if no numeric argument is given, but with a
|
||
numeric argument of six (as in ‘ESC-6 TAB’), up to six errors are
|
||
accepted. Hence with a value of ‘0 numeric’, no correcting completion
|
||
will be attempted unless a numeric argument is given.</p>
|
||
<p>If the value contains the string ‘not-numeric’, the completer will <em>not</em>
|
||
try to generate corrected completions when given a numeric argument, so
|
||
in this case the number given should be greater than zero. For example,
|
||
‘2 not-numeric’ specifies that correcting completion with two errors
|
||
will usually be performed, but if a numeric argument is given,
|
||
correcting completion will not be performed.</p>
|
||
<p>The default value for this style is ‘2 numeric’.</p>
|
||
<p><span id="index-max_002dmatches_002dwidth_002c-completion-style"></span></p>
|
||
<p>max-matches-width</p>
|
||
<p>This style is used to determine the trade off between the width of the
|
||
display used for matches and the width used for their descriptions when
|
||
the verbose style is in effect. The value gives the number of display
|
||
columns to reserve for the matches. The default is half the width of the
|
||
screen.</p>
|
||
<p>This has the most impact when several matches have the same description
|
||
and so will be grouped together. Increasing the style will allow more
|
||
matches to be grouped together; decreasing it will allow more of the
|
||
description to be visible.</p>
|
||
<p><span id="index-menu_002c-completion-style"></span></p>
|
||
<p>menu</p>
|
||
<p>If this is ‘true’ in the context of any of the tags defined for the
|
||
current completion menu completion will be used. The value for a
|
||
specific tag will take precedence over that for the ‘default’ tag.</p>
|
||
<p>If none of the values found in this way is ‘true’ but at least one is
|
||
set to ‘auto’, the shell behaves as if the AUTO_MENU option is set.</p>
|
||
<p>If one of the values is explicitly set to ‘false’, menu completion will
|
||
be explicitly turned off, overriding the MENU_COMPLETE option and other
|
||
settings.</p>
|
||
<p>In the form ‘yes=<code>num</code>’, where ‘yes’ may be any of the ‘true’ values
|
||
(‘yes’, ‘true’, ‘on’ and ‘1’), menu completion will be turned on if
|
||
there are at least <code>num</code> matches. In the form ‘yes=long’, menu
|
||
completion will be turned on if the list does not fit on the screen.
|
||
This does not activate menu completion if the widget normally only lists
|
||
completions, but menu completion can be activated in that case with the
|
||
value ‘yes=long-list’ (Typically, the value ‘select=long-list’ described
|
||
later is more useful as it provides control over scrolling.)</p>
|
||
<p>Similarly, with any of the ‘false’ values (as in ‘no=10’), menu
|
||
completion will <em>not</em> be used if there are <code>num</code> or more matches.</p>
|
||
<p>The value of this widget also controls menu selection, as implemented by
|
||
the zsh/complist module. The following values may appear either
|
||
alongside or instead of the values above.</p>
|
||
<p>If the value contains the string ‘select’, menu selection will be
|
||
started unconditionally.</p>
|
||
<p>In the form ‘select=<code>num</code>’, menu selection will only be started if there
|
||
are at least <code>num</code> matches. If the values for more than one tag provide
|
||
a number, the smallest number is taken.</p>
|
||
<p>Menu selection can be turned off explicitly by defining a value
|
||
containing the string‘no-select’.</p>
|
||
<p>It is also possible to start menu selection only if the list of matches
|
||
does not fit on the screen by using the value ‘select=long’. To start
|
||
menu selection even if the current widget only performs listing, use the
|
||
value ‘select=long-list’.</p>
|
||
<p>To turn on menu completion or menu selection when there are a certain
|
||
number of matches <em>or</em> the list of matches does not fit on the screen,
|
||
both of ‘yes=’ and ‘select=’ may be given twice, once with a number and
|
||
once with ‘long’ or ‘long-list’.</p>
|
||
<p>Finally, it is possible to activate two special modes of menu selection.
|
||
The word ‘interactive’ in the value causes interactive mode to be
|
||
entered immediately when menu selection is started; see <a href="Zsh-Modules.html#The-zsh_002fcomplist-Module">The
|
||
zsh/complist Module</a> for a
|
||
description of interactive mode. Including the string ‘search’ does the
|
||
same for incremental search mode. To select backward incremental search,
|
||
include the string ‘search-backward’.</p>
|
||
<p><span id="index-muttrc_002c-completion-style"></span></p>
|
||
<p>muttrc</p>
|
||
<p>If set, gives the location of the mutt configuration file. It defaults
|
||
to ‘~/.muttrc’.</p>
|
||
<p><span id="index-numbers_002c-completion-style"></span></p>
|
||
<p>numbers</p>
|
||
<p>This is used with the jobs tag. If it is ‘true’, the shell will complete
|
||
job numbers instead of the shortest unambiguous prefix of the job
|
||
command text. If the value is a number, job numbers will only be used if
|
||
that many words from the job descriptions are required to resolve
|
||
ambiguities. For example, if the value is ‘1’, strings will only be used
|
||
if all jobs differ in the first word on their command lines.</p>
|
||
<p><span id="index-old_002dlist_002c-completion-style"></span></p>
|
||
<p>old-list</p>
|
||
<p>This is used by the _oldlist completer. If it is set to ‘always’, then
|
||
standard widgets which perform listing will retain the current list of
|
||
matches, however they were generated; this can be turned off explicitly
|
||
with the value ‘never’, giving the behaviour without the _oldlist
|
||
completer. If the style is unset, or any other value, then the existing
|
||
list of completions is displayed if it is not already; otherwise, the
|
||
standard completion list is generated; this is the default behaviour of
|
||
_oldlist. However, if there is an old list and this style contains the
|
||
name of the completer function that generated the list, then the old
|
||
list will be used even if it was generated by a widget which does not do
|
||
listing.</p>
|
||
<p>For example, suppose you type ^Xc to use the _correct_word widget,
|
||
which generates a list of corrections for the word under the cursor.
|
||
Usually, typing ^D would generate a standard list of completions for the
|
||
word on the command line, and show that. With _oldlist, it will instead
|
||
show the list of corrections already generated.</p>
|
||
<p>As another example consider the _match completer: with the
|
||
insert-unambiguous style set to ‘true’ it inserts only a common prefix
|
||
string, if there is any. However, this may remove parts of the original
|
||
pattern, so that further completion could produce more matches than on
|
||
the first attempt. By using the _oldlist completer and setting this
|
||
style to _match, the list of matches generated on the first attempt
|
||
will be used again.</p>
|
||
<p><span id="index-old_002dmatches_002c-completion-style"></span></p>
|
||
<p>old-matches</p>
|
||
<p>This is used by the _all_matches completer to decide if an old list of
|
||
matches should be used if one exists. This is selected by one of the
|
||
‘true’ values or by the string ‘only’. If the value is ‘only’,
|
||
_all_matches will only use an old list and won’t have any effect on the
|
||
list of matches currently being generated.</p>
|
||
<p>If this style is set it is generally unwise to call the _all_matches
|
||
completer unconditionally. One possible use is for either this style or
|
||
the completer style to be defined with the -e option to zstyle to make
|
||
the style conditional.</p>
|
||
<p><span id="index-old_002dmenu_002c-completion-style"></span></p>
|
||
<p>old-menu</p>
|
||
<p>This is used by the _oldlist completer. It controls how menu completion
|
||
behaves when a completion has already been inserted and the user types a
|
||
standard completion key such as TAB. The default behaviour of _oldlist
|
||
is that menu completion always continues with the existing list of
|
||
completions. If this style is set to ‘false’, however, a new completion
|
||
is started if the old list was generated by a different completion
|
||
command; this is the behaviour without the _oldlist completer.</p>
|
||
<p>For example, suppose you type ^Xc to generate a list of corrections, and
|
||
menu completion is started in one of the usual ways. Usually, or with
|
||
this style set to ‘false’, typing TAB at this point would start trying
|
||
to complete the line as it now appears. With _oldlist, it instead
|
||
continues to cycle through the list of corrections.</p>
|
||
<p><span id="index-original_002c-completion-style"></span></p>
|
||
<p>original</p>
|
||
<p>This is used by the _approximate and _correct completers to decide if
|
||
the original string should be added as a possible completion. Normally,
|
||
this is done only if there are at least two possible corrections, but if
|
||
this style is set to ‘true’, it is always added. Note that the style
|
||
will be examined with the completer field in the context name set to
|
||
correct-<code>num</code> or approximate-<code>num</code>, where <code>num</code> is the number of errors
|
||
that were accepted.</p>
|
||
<p><span id="index-packageset_002c-completion-style"></span></p>
|
||
<p>packageset</p>
|
||
<p>This style is used when completing arguments of the Debian ‘dpkg’
|
||
program. It contains an override for the default package set for a given
|
||
context. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:complete:dpkg:option--status-1:*' \
|
||
packageset avail
|
||
</code></pre>
|
||
</div>
|
||
<p>causes available packages, rather than only installed packages, to be
|
||
completed for ‘dpkg --status’.</p>
|
||
<p><span id="index-path_002c-completion-style"></span></p>
|
||
<p>path</p>
|
||
<p>The function that completes color names uses this style with the colors
|
||
tag. The value should be the pathname of a file containing color names
|
||
in the format of an X11 rgb.txt file. If the style is not set but this
|
||
file is found in one of various standard locations it will be used as
|
||
the default.</p>
|
||
<p><span id="index-path_002dcompletion_002c-completion-style"></span></p>
|
||
<p>path-completion</p>
|
||
<p>This is used by filename completion. By default, filename completion
|
||
examines all components of a path to see if there are completions of
|
||
that component. For example, /u/b/z can be completed to /usr/bin/zsh.
|
||
Explicitly setting this style to ‘false’ inhibits this behaviour for
|
||
path components up to the / before the cursor; this overrides the
|
||
setting of accept-exact-dirs.</p>
|
||
<p>Even with the style set to ‘false’, it is still possible to complete
|
||
multiple paths by setting the option COMPLETE_IN_WORD and moving the
|
||
cursor back to the first component in the path to be completed. For
|
||
example, /u/b/z can be completed to /usr/bin/zsh if the cursor is after
|
||
the /u.</p>
|
||
<p><span id="index-pine_002ddirectory_002c-completion-style"></span></p>
|
||
<p>pine-directory</p>
|
||
<p>If set, specifies the directory containing PINE mailbox files. There is
|
||
no default, since recursively searching this directory is inconvenient
|
||
for anyone who doesn’t use PINE.</p>
|
||
<p><span id="index-ports_002c-completion-style"></span></p>
|
||
<p>ports</p>
|
||
<p>A list of Internet service names (network ports) to complete. If this is
|
||
not set, service names are taken from the file ‘/etc/services’.</p>
|
||
<p><span id="index-prefix_002dhidden_002c-completion-style"></span></p>
|
||
<p>prefix-hidden</p>
|
||
<p>This is used for certain completions which share a common prefix, for
|
||
example command options beginning with dashes. If it is ‘true’, the
|
||
prefix will not be shown in the list of matches.</p>
|
||
<p>The default value for this style is ‘false’.</p>
|
||
<p><span id="index-prefix_002dneeded_002c-completion-style"></span></p>
|
||
<p>prefix-needed</p>
|
||
<p>This style is also relevant for matches with a common prefix. If it is
|
||
set to ‘true’ this common prefix must be typed by the user to generate
|
||
the matches.</p>
|
||
<p>The style is applicable to the options, signals, jobs, functions, and
|
||
parameters completion tags.</p>
|
||
<p>For command options, this means that the initial ‘-’, ‘+’, or ‘--’ must
|
||
be typed explicitly before option names will be completed.</p>
|
||
<p>For signals, an initial ‘-’ is required before signal names will be
|
||
completed.</p>
|
||
<p>For jobs, an initial ‘%’ is required before job names will be completed.</p>
|
||
<p>For function and parameter names, an initial ‘_’ or ‘.’ is required
|
||
before function or parameter names starting with those characters will
|
||
be completed.</p>
|
||
<p>The default value for this style is ‘false’ for function and parameter
|
||
completions, and ‘true’ otherwise.</p>
|
||
<p><span id="index-preserve_002dprefix_002c-completion-style"></span></p>
|
||
<p>preserve-prefix</p>
|
||
<p>This style is used when completing path names. Its value should be a
|
||
pattern matching an initial prefix of the word to complete that should
|
||
be left unchanged under all circumstances. For example, on some Unices
|
||
an initial ‘//’ (double slash) has a special meaning; setting this style
|
||
to the string ‘//’ will preserve it. As another example, setting this
|
||
style to ‘?:/’ under Cygwin would allow completion after ‘a:/...’ and so
|
||
on.</p>
|
||
<p><span id="index-range_002c-completion-style"></span></p>
|
||
<p>range</p>
|
||
<p>This is used by the _history completer and the _history_complete_word
|
||
bindable command to decide which words should be completed.</p>
|
||
<p>If it is a single number, only the last <code>N</code> words from the history will
|
||
be completed.</p>
|
||
<p>If it is a range of the form ‘<code>max</code>:<code>slice</code>’, the last <code>slice</code> words
|
||
will be completed; then if that yields no matches, the <code>slice</code> words
|
||
before those will be tried and so on. This process stops either when at
|
||
least one match has been found, or <code>max</code> words have been tried.</p>
|
||
<p>The default is to complete all words from the history at once.</p>
|
||
<p><span id="index-recursive_002dfiles_002c-completion-style"></span></p>
|
||
<p>recursive-files</p>
|
||
<p>If this style is set, its value is an array of patterns to be tested
|
||
against ‘$PWD/’: note the trailing slash, which allows directories in
|
||
the pattern to be delimited unambiguously by including slashes on both
|
||
sides. If an ordinary file completion fails and the word on the command
|
||
line does not yet have a directory part to its name, the style is
|
||
retrieved using the same tag as for the completion just attempted, then
|
||
the elements tested against $PWD/ in turn. If one matches, then the
|
||
shell reattempts completion by prepending the word on the command line
|
||
with each directory in the expansion of **/*(/) in turn. Typically
|
||
the elements of the style will be set to restrict the number of
|
||
directories beneath the current one to a manageable number, for example
|
||
‘*/.git/*’.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' recursive-files '*/zsh/*'
|
||
</code></pre>
|
||
</div>
|
||
<p>If the current directory is /home/pws/zsh/Src, then zle_tr<TAB> can be
|
||
completed to Zle/zle_tricky.c.</p>
|
||
<p><span id="index-regular_002c-completion-style"></span></p>
|
||
<p>regular</p>
|
||
<p>This style is used by the _expand_alias completer and bindable command.
|
||
If set to ‘true’ (the default), regular aliases will be expanded but
|
||
only in command position. If it is set to ‘false’, regular aliases will
|
||
never be expanded. If it is set to ‘always’, regular aliases will be
|
||
expanded even if not in command position.</p>
|
||
<p><span id="index-rehash_002c-completion-style"></span></p>
|
||
<p>rehash</p>
|
||
<p>If this is set when completing external commands, the internal list
|
||
(hash) of commands will be updated for each search by issuing the rehash
|
||
command. There is a speed penalty for this which is only likely to be
|
||
noticeable when directories in the path have slow file access.</p>
|
||
<p><span id="index-remote_002daccess_002c-completion-style"></span></p>
|
||
<p>remote-access</p>
|
||
<p>If set to ‘false’, certain commands will be prevented from making
|
||
Internet connections to retrieve remote information. This includes the
|
||
completion for the CVS command.</p>
|
||
<p>It is not always possible to know if connections are in fact to a remote
|
||
site, so some may be prevented unnecessarily.</p>
|
||
<p><span id="index-remove_002dall_002ddups_002c-completion-style"></span></p>
|
||
<p>remove-all-dups</p>
|
||
<p>The _history_complete_word bindable command and the _history completer
|
||
use this to decide if all duplicate matches should be removed, rather
|
||
than just consecutive duplicates.</p>
|
||
<p><span id="index-select_002dprompt_002c-completion-style"></span></p>
|
||
<p>select-prompt</p>
|
||
<p>If this is set for the default tag, its value will be displayed during
|
||
menu selection (see the menu style above) when the completion list does
|
||
not fit on the screen as a whole. The same escapes as for the
|
||
list-prompt style are understood, except that the numbers refer to the
|
||
match or line the mark is on. A default prompt is used when the value is
|
||
the empty string.</p>
|
||
<p><span id="index-select_002dscroll_002c-completion-style"></span></p>
|
||
<p>select-scroll</p>
|
||
<p>This style is tested for the default tag and determines how a completion
|
||
list is scrolled during a menu selection (see the menu style above) when
|
||
the completion list does not fit on the screen as a whole. If the value
|
||
is ‘0’ (zero), the list is scrolled by half-screenfuls; if it is a
|
||
positive integer, the list is scrolled by the given number of lines; if
|
||
it is a negative number, the list is scrolled by a screenful minus the
|
||
absolute value of the given number of lines. The default is to scroll by
|
||
single lines.</p>
|
||
<p><span id="index-separate_002dsections_002c-completion-style"></span></p>
|
||
<p>separate-sections</p>
|
||
<p>This style is used with the manuals tag when completing names of manual
|
||
pages. If it is ‘true’, entries for different sections are added
|
||
separately using tag names of the form ‘manuals.<code>X</code>’, where <code>X</code> is the
|
||
section number. When the group-name style is also in effect, pages from
|
||
different sections will appear separately. This style is also used
|
||
similarly with the words style when completing words for the dict
|
||
command. It allows words from different dictionary databases to be added
|
||
separately. See also insert-sections.</p>
|
||
<p>The default for this style is ‘false’.</p>
|
||
<p><span id="index-show_002dambiguity_002c-completion-style"></span></p>
|
||
<p>show-ambiguity</p>
|
||
<p>If the zsh/complist module is loaded, this style can be used to
|
||
highlight the first ambiguous character in completion lists. The value
|
||
is either a color indication such as those supported by the list-colors
|
||
style or, with a value of ‘true’, a default of underlining is selected.
|
||
The highlighting is only applied if the completion display strings
|
||
correspond to the actual matches.</p>
|
||
<p><span id="index-show_002dcompleter_002c-completion-style"></span></p>
|
||
<p>show-completer</p>
|
||
<p>Tested whenever a new completer is tried. If it is ‘true’, the
|
||
completion system outputs a progress message in the listing area showing
|
||
what completer is being tried. The message will be overwritten by any
|
||
output when completions are found and is removed after completion is
|
||
finished.</p>
|
||
<p><span id="index-single_002dignored_002c-completion-style"></span></p>
|
||
<p>single-ignored</p>
|
||
<p>This is used by the _ignored completer when there is only one match. If
|
||
its value is ‘show’, the single match will be displayed but not
|
||
inserted. If the value is ‘menu’, then the single match and the original
|
||
string are both added as matches and menu completion is started, making
|
||
it easy to select either of them.</p>
|
||
<p><span id="index-sort_002c-completion-style"></span></p>
|
||
<p>sort</p>
|
||
<p>This allows the standard ordering of matches to be overridden.</p>
|
||
<p>If its value is ‘true’ or ‘false’, sorting is enabled or disabled.
|
||
Additionally the values associated with the ‘-o’ option to compadd can
|
||
also be listed: match, nosort, numeric, reverse. If it is not set for
|
||
the context, the standard behaviour of the calling widget is used.</p>
|
||
<p>The style is tested first against the full context including the tag,
|
||
and if that fails to produce a value against the context without the
|
||
tag.</p>
|
||
<p>In many cases where a calling widget explicitly selects a particular
|
||
ordering in lieu of the default, a value of ‘true’ is not honoured. An
|
||
example of where this is not the case is for command history where the
|
||
default of sorting matches chronologically may be overridden by setting
|
||
the style to ‘true’.</p>
|
||
<p>In the _expand completer, if it is set to ‘true’, the expansions
|
||
generated will always be sorted. If it is set to ‘menu’, then the
|
||
expansions are only sorted when they are offered as single strings but
|
||
not in the string containing all possible expansions.</p>
|
||
<p><span id="index-special_002ddirs_002c-completion-style"></span></p>
|
||
<p>special-dirs</p>
|
||
<p>Normally, the completion code will not produce the directory names ‘.’
|
||
and ‘..’ as possible completions. If this style is set to ‘true’, it
|
||
will add both ‘.’ and ‘..’ as possible completions; if it is set to
|
||
‘..’, only ‘..’ will be added.</p>
|
||
<p>The following example sets special-dirs to ‘..’ when the current prefix
|
||
is empty, is a single ‘.’, or consists only of a path beginning with
|
||
‘../’. Otherwise the value is ‘false’.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -e ':completion:*' special-dirs \
|
||
'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-squeeze_002dslashes_002c-completion-style"></span></p>
|
||
<p>squeeze-slashes</p>
|
||
<p>If set to ‘true’, sequences of slashes in filename paths (for example in
|
||
‘foo//bar’) will be treated as a single slash. This is the usual
|
||
behaviour of UNIX paths. However, by default the file completion
|
||
function behaves as if there were a ‘*’ between the slashes.</p>
|
||
<p><span id="index-stop_002c-completion-style"></span></p>
|
||
<p>stop</p>
|
||
<p>If set to ‘true’, the _history_complete_word bindable command will stop
|
||
once when reaching the beginning or end of the history. Invoking
|
||
_history_complete_word will then wrap around to the opposite end of the
|
||
history. If this style is set to ‘false’ (the default),
|
||
_history_complete_word will loop immediately as in a menu completion.</p>
|
||
<p><span id="index-strip_002dcomments_002c-completion-style"></span></p>
|
||
<p>strip-comments</p>
|
||
<p>If set to ‘true’, this style causes non-essential comment text to be
|
||
removed from completion matches. Currently it is only used when
|
||
completing e-mail addresses where it removes any display name from the
|
||
addresses, cutting them down to plain <code>user@host</code> form.</p>
|
||
<p><span id="index-subst_002dglobs_002donly_002c-completion-style"></span></p>
|
||
<p>subst-globs-only</p>
|
||
<p>This is used by the _expand completer. If it is set to ‘true’, the
|
||
expansion will only be used if it resulted from globbing; hence, if
|
||
expansions resulted from the use of the substitute style described
|
||
below, but these were not further changed by globbing, the expansions
|
||
will be rejected.</p>
|
||
<p>The default for this style is ‘false’.</p>
|
||
<p><span id="index-substitute_002c-completion-style"></span></p>
|
||
<p>substitute</p>
|
||
<p>This boolean style controls whether the _expand completer will first
|
||
try to expand all substitutions in the string (such as ‘$(<code>...</code>)’ and
|
||
‘${<code>...</code>}’).</p>
|
||
<p>The default is ‘true’.</p>
|
||
<p><span id="index-suffix_002c-completion-style"></span></p>
|
||
<p>suffix</p>
|
||
<p>This is used by the _expand completer if the word starts with a tilde
|
||
or contains a parameter expansion. If it is set to ‘true’, the word will
|
||
only be expanded if it doesn’t have a suffix, i.e. if it is something
|
||
like ‘~foo’ or ‘$foo’ rather than ‘~foo/’ or ‘$foo/bar’, unless that
|
||
suffix itself contains characters eligible for expansion. The default
|
||
for this style is ‘true’.</p>
|
||
<p><span id="index-tag_002dorder_002c-completion-style"></span></p>
|
||
<p>tag-order</p>
|
||
<p>This provides a mechanism for sorting how the tags available in a
|
||
particular context will be used.</p>
|
||
<p>The values for the style are sets of space-separated lists of tags. The
|
||
tags in each value will be tried at the same time; if no match is found,
|
||
the next value is used. (See the file-patterns style for an exception to
|
||
this behavior.)</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:complete:-command-:*:*' tag-order \
|
||
'commands functions'
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that completion in command position first offers external
|
||
commands and shell functions. Remaining tags will be tried if no
|
||
completions are found.</p>
|
||
<p>In addition to tag names, each string in the value may take one of the
|
||
following forms:</p>
|
||
<p>-<br />
|
||
If any value consists of only a hyphen, then <em>only</em> the tags specified
|
||
in the other values are generated. Normally all tags not explicitly
|
||
selected are tried last if the specified tags fail to generate any
|
||
matches. This means that a single value consisting only of a single
|
||
hyphen turns off completion.</p>
|
||
<p>! <code>tags</code>...<br />
|
||
A string starting with an exclamation mark specifies names of tags that
|
||
are <em>not</em> to be used. The effect is the same as if all other possible
|
||
tags for the context had been listed.</p>
|
||
<p><code>tag</code>:<code>label</code> ...<br />
|
||
Here, <code>tag</code> is one of the standard tags and <code>label</code> is an arbitrary
|
||
name. Matches are generated as normal but the name <code>label</code> is used in
|
||
contexts instead of <code>tag</code>. This is not useful in words starting with !.</p>
|
||
<p>If the <code>label</code> starts with a hyphen, the <code>tag</code> is prepended to the
|
||
<code>label</code> to form the name used for lookup. This can be used to make the
|
||
completion system try a certain tag more than once, supplying different
|
||
style settings for each attempt; see below for an example.</p>
|
||
<p><code>tag</code>:<code>label</code>:<code>description</code><br />
|
||
As before, but description will replace the ‘%d’ in the value of the
|
||
format style instead of the default description supplied by the
|
||
completion function. Spaces in the description must be quoted with a
|
||
backslash. A ‘%d’ appearing in <code>description</code> is replaced with the
|
||
description given by the completion function.</p>
|
||
<p>In any of the forms above the tag may be a pattern or several patterns
|
||
in the form ‘{<code>pat1</code>,<code>pat2...</code>}’. In this case all matching tags will be
|
||
used except for any given explicitly in the same string.</p>
|
||
<p>One use of these features is to try one tag more than once, setting
|
||
other styles differently on each attempt, but still to use all the other
|
||
tags without having to repeat them all. For example, to make completion
|
||
of function names in command position ignore all the completion
|
||
functions starting with an underscore the first time completion is
|
||
tried:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:-command-:*:*' tag-order \
|
||
'functions:-non-comp *' functions
|
||
zstyle ':completion:*:functions-non-comp' \
|
||
ignored-patterns '_*'
|
||
</code></pre>
|
||
</div>
|
||
<p>On the first attempt, all tags will be offered but the functions tag
|
||
will be replaced by functions-non-comp. The ignored-patterns style is
|
||
set for this tag to exclude functions starting with an underscore. If
|
||
there are no matches, the second value of the tag-order style is used
|
||
which completes functions using the default tag, this time presumably
|
||
including all function names.</p>
|
||
<p>The matches for one tag can be split into different groups. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' tag-order \
|
||
'options:-long:long\ options
|
||
options:-short:short\ options
|
||
options:-single-letter:single\ letter\ options'
|
||
zstyle ':completion:*:options-long' \
|
||
ignored-patterns '[-+](|-|[^-]*)'
|
||
zstyle ':completion:*:options-short' \
|
||
ignored-patterns '--*' '[-+]?'
|
||
zstyle ':completion:*:options-single-letter' \
|
||
ignored-patterns '???*'
|
||
</code></pre>
|
||
</div>
|
||
<p>With the group-names style set, options beginning with ‘--’, options
|
||
beginning with a single ‘-’ or ‘+’ but containing multiple characters,
|
||
and single-letter options will be displayed in separate groups with
|
||
different descriptions.</p>
|
||
<p>Another use of patterns is to try multiple match specifications one
|
||
after another. The matcher-list style offers something similar, but it
|
||
is tested very early in the completion system and hence can’t be set for
|
||
single commands nor for more specific contexts. Here is how to try
|
||
normal completion without any match specification and, if that generates
|
||
no matches, try again with case-insensitive matching, restricting the
|
||
effect to arguments of the command foo:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:*:foo:*:*' tag-order '*' '*:-case'
|
||
zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'
|
||
</code></pre>
|
||
</div>
|
||
<p>First, all the tags offered when completing after foo are tried using
|
||
the normal tag name. If that generates no matches, the second value of
|
||
tag-order is used, which tries all tags again except that this time each
|
||
has -case appended to its name for lookup of styles. Hence this time the
|
||
value for the matcher style from the second call to zstyle in the
|
||
example is used to make completion case-insensitive.</p>
|
||
<p>It is possible to use the -e option of the zstyle builtin command to
|
||
specify conditions for the use of particular tags. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -e '*:-command-:*' tag-order '
|
||
if [[ -n $PREFIX$SUFFIX ]]; then
|
||
reply=( )
|
||
else
|
||
reply=( - )
|
||
fi'
|
||
</code></pre>
|
||
</div>
|
||
<p>Completion in command position will be attempted only if the string
|
||
typed so far is not empty. This is tested using the PREFIX special
|
||
parameter; see <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a> for a description
|
||
of parameters which are special inside completion widgets. Setting reply
|
||
to an empty array provides the default behaviour of trying all tags at
|
||
once; setting it to an array containing only a hyphen disables the use
|
||
of all tags and hence of all completions.</p>
|
||
<p>If no tag-order style has been defined for a context, the strings
|
||
‘(|*-)argument-* (|*-)option-* values’ and ‘options’ plus all tags
|
||
offered by the completion function will be used to provide a sensible
|
||
default behavior that causes arguments (whether normal command arguments
|
||
or arguments of options) to be completed before option names for most
|
||
commands.</p>
|
||
<p><span id="index-urls_002c-completion-style"></span></p>
|
||
<p>urls</p>
|
||
<p>This is used together with the urls tag by functions completing URLs.</p>
|
||
<p>If the value consists of more than one string, or if the only string
|
||
does not name a file or directory, the strings are used as the URLs to
|
||
complete.</p>
|
||
<p>If the value contains only one string which is the name of a normal file
|
||
the URLs are taken from that file (where the URLs may be separated by
|
||
white space or newlines).</p>
|
||
<p>Finally, if the only string in the value names a directory, the
|
||
directory hierarchy rooted at this directory gives the completions. The
|
||
top level directory should be the file access method, such as ‘http’,
|
||
‘ftp’, ‘bookmark’ and so on. In many cases the next level of directories
|
||
will be a filename. The directory hierarchy can descend as deep as
|
||
necessary.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' urls ~/.urls
|
||
mkdir -p ~/.urls/ftp/ftp.zsh.org/pub
|
||
</code></pre>
|
||
</div>
|
||
<p>allows completion of all the components of the URL ‘netscape’ or ‘lynx’.
|
||
Note, however, that access methods and files are completed separately,
|
||
so if the hosts style is set hosts can be completed without reference to
|
||
the urls style.</p>
|
||
<p>See the description in the function _urls itself for more information
|
||
(e.g. ‘more $^fpath/_urls(N)’).</p>
|
||
<p><span id="index-use_002dcache_002c-completion-style"></span></p>
|
||
<p>use-cache</p>
|
||
<p>If this is set, the completion caching layer is activated for any
|
||
completions which use it (via the _store_cache, _retrieve_cache, and
|
||
_cache_invalid functions). The directory containing the cache files can
|
||
be changed with the cache-path style.</p>
|
||
<p><span id="index-use_002dcompctl_002c-completion-style"></span></p>
|
||
<p>use-compctl</p>
|
||
<p>If this style is set to a string <em>not</em> equal to false, 0, no, and off,
|
||
the completion system may use any completion specifications defined with
|
||
the compctl builtin command. If the style is unset, this is done only if
|
||
the zsh/compctl module is loaded. The string may also contain the
|
||
substring ‘first’ to use completions defined with ‘compctl -T’, and the
|
||
substring ‘default’ to use the completion defined with ‘compctl -D’.</p>
|
||
<p>Note that this is only intended to smooth the transition from compctl to
|
||
the new completion system and may disappear in the future.</p>
|
||
<p>Note also that the definitions from compctl will only be used if there
|
||
is no specific completion function for the command in question. For
|
||
example, if there is a function _foo to complete arguments to the
|
||
command foo, compctl will never be invoked for foo. However, the compctl
|
||
version will be tried if foo only uses default completion.</p>
|
||
<p><span id="index-use_002dip_002c-completion-style"></span></p>
|
||
<p>use-ip</p>
|
||
<p>By default, the function _hosts that completes host names strips IP
|
||
addresses from entries read from host databases such as NIS and ssh
|
||
files. If this style is ‘true’, the corresponding IP addresses can be
|
||
completed as well. This style is not use in any context where the hosts
|
||
style is set; note also it must be set before the cache of host names is
|
||
generated (typically the first completion attempt).</p>
|
||
<p><span id="index-users_002c-completion-style"></span></p>
|
||
<p>users</p>
|
||
<p>This may be set to a list of usernames to be completed. If it is not set
|
||
all usernames will be completed. Note that if it is set only that list
|
||
of users will be completed; this is because on some systems querying all
|
||
users can take a prohibitive amount of time.</p>
|
||
<p><span id="index-users_002dhosts_002c-completion-style"></span></p>
|
||
<p>users-hosts</p>
|
||
<p>The values of this style should be of the form ‘<code>user</code>@<code>host</code>’ or
|
||
‘<code>user</code>:<code>host</code>’. It is used for commands that need pairs of user- and
|
||
hostnames. These commands will complete usernames from this style
|
||
(only), and will restrict subsequent hostname completion to hosts paired
|
||
with that user in one of the values of the style.</p>
|
||
<p>It is possible to group values for sets of commands which allow a remote
|
||
login, such as rlogin and ssh, by using the my-accounts tag. Similarly,
|
||
values for sets of commands which usually refer to the accounts of other
|
||
people, such as talk and finger, can be grouped by using the
|
||
other-accounts tag. More ambivalent commands may use the accounts tag.</p>
|
||
<p><span id="index-users_002dhosts_002dports_002c-completion-style"></span></p>
|
||
<p>users-hosts-ports</p>
|
||
<p>Like users-hosts but used for commands like telnet and containing
|
||
strings of the form ‘<code>user</code>@<code>host</code>:<code>port</code>’.</p>
|
||
<p><span id="index-verbose_002c-completion-style"></span></p>
|
||
<p>verbose</p>
|
||
<p>If set, as it is by default, the completion listing is more verbose. In
|
||
particular many commands show descriptions for options if this style is
|
||
‘true’.</p>
|
||
<p><span id="index-word_002c-completion-style"></span></p>
|
||
<p>word</p>
|
||
<p>This is used by the _list completer, which prevents the insertion of
|
||
completions until a second completion attempt when the line has not
|
||
changed. The normal way of finding out if the line has changed is to
|
||
compare its entire contents between the two occasions. If this style is
|
||
‘true’, the comparison is instead performed only on the current word.
|
||
Hence if completion is performed on another word with the same contents,
|
||
completion will not be delayed.</p>
|
||
<hr />
|
||
<p><span id="Control-Functions"></span> <span
|
||
id="Control-Functions-1"></span></p>
|
||
<h2 id="204-control-functions"><a class="header" href="#204-control-functions">20.4 Control Functions</a></h2>
|
||
<p><span id="index-completion-system_002c-choosing-completers"></span></p>
|
||
<p>The initialization script compinit redefines all the widgets which
|
||
perform completion to call the supplied widget function _main_complete.
|
||
This function acts as a wrapper calling the so-called ‘completer’
|
||
functions that generate matches. If _main_complete is called with
|
||
arguments, these are taken as the names of completer functions to be
|
||
called in the order given. If no arguments are given, the set of
|
||
functions to try is taken from the completer style. For example, to use
|
||
normal completion and correction if that doesn’t generate any matches:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer _complete _correct
|
||
</code></pre>
|
||
</div>
|
||
<p>after calling compinit. The default value for this style is ‘_complete
|
||
_ignored’, i.e. normally only ordinary completion is tried, first with
|
||
the effect of the ignored-patterns style and then without it. The
|
||
_main_complete function uses the return status of the completer
|
||
functions to decide if other completers should be called. If the return
|
||
status is zero, no other completers are tried and the _main_complete
|
||
function returns.</p>
|
||
<p>If the first argument to _main_complete is a single hyphen, the
|
||
arguments will not be taken as names of completers. Instead, the second
|
||
argument gives a name to use in the <code>completer</code> field of the context and
|
||
the other arguments give a command name and arguments to call to
|
||
generate the matches.</p>
|
||
<p>The following completer functions are contained in the distribution,
|
||
although users may write their own. Note that in contexts the leading
|
||
underscore is stripped, for example basic completion is performed in the
|
||
context ‘:completion::complete:<code>...</code>’.</p>
|
||
<p><span id="index-completion-system_002c-completers"></span></p>
|
||
<p><span id="index-_005fall_005fmatches"></span></p>
|
||
<p>_all_matches</p>
|
||
<p>This completer can be used to add a string consisting of all other
|
||
matches. As it influences later completers it must appear as the first
|
||
completer in the list. The list of all matches is affected by the
|
||
avoid-completer and old-matches styles described above.</p>
|
||
<p>It may be useful to use the _generic function described below to bind
|
||
_all_matches to its own keystroke, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zle -C all-matches complete-word _generic
|
||
bindkey '^Xa' all-matches
|
||
zstyle ':completion:all-matches:*' old-matches only
|
||
zstyle ':completion:all-matches::::' completer _all_matches
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that this does not generate completions by itself: first use any of
|
||
the standard ways of generating a list of completions, then use ^Xa to
|
||
show all matches. It is possible instead to add a standard completer to
|
||
the list and request that the list of all matches should be directly
|
||
inserted:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:all-matches::::' completer \
|
||
_all_matches _complete
|
||
zstyle ':completion:all-matches:*' insert true
|
||
</code></pre>
|
||
</div>
|
||
<p>In this case the old-matches style should not be set.</p>
|
||
<p><span id="index-_005fapproximate"></span></p>
|
||
<p>_approximate</p>
|
||
<p>This is similar to the basic _complete completer but allows the
|
||
completions to undergo corrections. The maximum number of errors can be
|
||
specified by the max-errors style; see the description of approximate
|
||
matching in <a href="Expansion.html#Filename-Generation">Filename Generation</a>
|
||
for how errors are counted. Normally this completer will only be tried
|
||
after the normal _complete completer:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer _complete _approximate
|
||
</code></pre>
|
||
</div>
|
||
<p>This will give correcting completion if and only if normal completion
|
||
yields no possible completions. When corrected completions are found,
|
||
the completer will normally start menu completion allowing you to cycle
|
||
through these strings.</p>
|
||
<p>This completer uses the tags corrections and original when generating
|
||
the possible corrections and the original string. The format style for
|
||
the former may contain the additional sequences ‘%e’ and ‘%o’ which will
|
||
be replaced by the number of errors accepted to generate the corrections
|
||
and the original string, respectively.</p>
|
||
<p>The completer progressively increases the number of errors allowed up to
|
||
the limit by the max-errors style, hence if a completion is found with
|
||
one error, no completions with two errors will be shown, and so on. It
|
||
modifies the completer name in the context to indicate the number of
|
||
errors being tried: on the first try the completer field contains
|
||
‘approximate-1’, on the second try ‘approximate-2’, and so on.</p>
|
||
<p>When _approximate is called from another function, the number of errors
|
||
to accept may be passed with the -a option. The argument is in the same
|
||
format as the max-errors style, all in one string.</p>
|
||
<p>Note that this completer (and the _correct completer mentioned below)
|
||
can be quite expensive to call, especially when a large number of errors
|
||
are allowed. One way to avoid this is to set up the completer style
|
||
using the -e option to zstyle so that some completers are only used when
|
||
completion is attempted a second time on the same string, e.g.:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -e ':completion:*' completer '
|
||
if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
|
||
_last_try="$HISTNO$BUFFER$CURSOR"
|
||
reply=(_complete _match _prefix)
|
||
else
|
||
reply=(_ignored _correct _approximate)
|
||
fi'
|
||
</code></pre>
|
||
</div>
|
||
<p>This uses the HISTNO parameter and the BUFFER and CURSOR special
|
||
parameters that are available inside zle and completion widgets to find
|
||
out if the command line hasn’t changed since the last time completion
|
||
was tried. Only then are the _ignored, _correct and _approximate
|
||
completers called.</p>
|
||
<p><span id="index-_005fcanonical_005fpaths"></span></p>
|
||
<p>_canonical_paths [ -A <code>var</code> ] [ -N ] [ -MJV12nfX ] <code>tag</code> <code>descr</code>
|
||
[ <code>paths</code> ... ]</p>
|
||
<p>This completion function completes all paths given to it, and also tries
|
||
to offer completions which point to the same file as one of the paths
|
||
given (relative path when an absolute path is given, and vice versa;
|
||
when ..’s are present in the word to be completed; and some paths got
|
||
from symlinks).</p>
|
||
<p>-A, if specified, takes the paths from the array variable specified.
|
||
Paths can also be specified on the command line as shown above. -N, if
|
||
specified, prevents canonicalizing the paths given before using them for
|
||
completion, in case they are already so. The options -M, -J, -V, -1, -2,
|
||
-n, -F, -X are passed to compadd.</p>
|
||
<p>See _description for a description of <code>tag</code> and <code>descr</code>.</p>
|
||
<p><span id="index-_005fcmdambivalent"></span></p>
|
||
<p>_cmdambivalent</p>
|
||
<p>Completes the remaining positional arguments as an external command. The
|
||
external command and its arguments are completed as separate arguments
|
||
(in a manner appropriate for completing /usr/bin/env) if there are two
|
||
or more remaining positional arguments on the command line, and as a
|
||
quoted command string (in the manner of system(...)) otherwise. See also
|
||
_cmdstring and _precommand.</p>
|
||
<p>This function takes no arguments.</p>
|
||
<p><span id="index-_005fcmdstring"></span></p>
|
||
<p>_cmdstring</p>
|
||
<p>Completes an external command as a single argument, as for system(...).</p>
|
||
<p><span id="index-_005fcomplete"></span></p>
|
||
<p>_complete</p>
|
||
<p>This completer generates all possible completions in a context-sensitive
|
||
manner, i.e. using the settings defined with the compdef function
|
||
explained above and the current settings of all special parameters. This
|
||
gives the normal completion behaviour.</p>
|
||
<p>To complete arguments of commands, _complete uses the utility function
|
||
_normal, which is in turn responsible for finding the particular
|
||
function; it is described below. Various contexts of the form
|
||
-<code>context</code>- are handled specifically. These are all mentioned above as
|
||
possible arguments to the #compdef tag.</p>
|
||
<p>Before trying to find a function for a specific context, _complete
|
||
checks if the parameter ‘compcontext’ is set. Setting ‘compcontext’
|
||
allows the usual completion dispatching to be overridden which is useful
|
||
in places such as a function that uses vared for input. If it is set to
|
||
an array, the elements are taken to be the possible matches which will
|
||
be completed using the tag ‘values’ and the description ‘value’. If it
|
||
is set to an associative array, the keys are used as the possible
|
||
completions and the values (if non-empty) are used as descriptions for
|
||
the matches. If ‘compcontext’ is set to a string containing colons, it
|
||
should be of the form ‘<code>tag</code>:<code>descr</code>:<code>action</code>’. In this case the <code>tag</code>
|
||
and <code>descr</code> give the tag and description to use and the <code>action</code>
|
||
indicates what should be completed in one of the forms accepted by the
|
||
_arguments utility function described below.</p>
|
||
<p>Finally, if ‘compcontext’ is set to a string without colons, the value
|
||
is taken as the name of the context to use and the function defined for
|
||
that context will be called. For this purpose, there is a special
|
||
context named -command-line- that completes whole command lines
|
||
(commands and their arguments). This is not used by the completion
|
||
system itself but is nonetheless handled when explicitly called.</p>
|
||
<p><span id="index-_005fcorrect"></span></p>
|
||
<p>_correct</p>
|
||
<p>Generate corrections, but not completions, for the current word; this is
|
||
similar to _approximate but will not allow any number of extra
|
||
characters at the cursor as that completer does. The effect is similar
|
||
to spell-checking. It is based on _approximate, but the completer field
|
||
in the context name is correct.</p>
|
||
<p>For example, with:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:::::' completer \
|
||
_complete _correct _approximate
|
||
zstyle ':completion:*:correct:::' max-errors 2 not-numeric
|
||
zstyle ':completion:*:approximate:::' max-errors 3 numeric
|
||
</code></pre>
|
||
</div>
|
||
<p>correction will accept up to two errors. If a numeric argument is given,
|
||
correction will not be performed, but correcting completion will be, and
|
||
will accept as many errors as given by the numeric argument. Without a
|
||
numeric argument, first correction and then correcting completion will
|
||
be tried, with the first one accepting two errors and the second one
|
||
accepting three errors.</p>
|
||
<p>When _correct is called as a function, the number of errors to accept
|
||
may be given following the -a option. The argument is in the same form a
|
||
values to the accept style, all in one string.</p>
|
||
<p>This completer function is intended to be used without the _approximate
|
||
completer or, as in the example, just before it. Using it after the
|
||
_approximate completer is useless since _approximate will at least
|
||
generate the corrected strings generated by the _correct completer —
|
||
and probably more.</p>
|
||
<p><span id="index-_005fexpand"></span></p>
|
||
<p>_expand</p>
|
||
<p>This completer function does not really perform completion, but instead
|
||
checks if the word on the command line is eligible for expansion and, if
|
||
it is, gives detailed control over how this expansion is done. For this
|
||
to happen, the completion system needs to be invoked with complete-word,
|
||
not expand-or-complete (the default binding for TAB), as otherwise the
|
||
string will be expanded by the shell’s internal mechanism before the
|
||
completion system is started. Note also this completer should be called
|
||
before the _complete completer function.</p>
|
||
<p>The tags used when generating expansions are all-expansions for the
|
||
string containing all possible expansions, expansions when adding the
|
||
possible expansions as single matches and original when adding the
|
||
original string from the line. The order in which these strings are
|
||
generated, if at all, can be controlled by the group-order and tag-order
|
||
styles, as usual.</p>
|
||
<p>The format string for all-expansions and for expansions may contain the
|
||
sequence ‘%o’ which will be replaced by the original string from the
|
||
line.</p>
|
||
<p>The kind of expansion to be tried is controlled by the substitute, glob
|
||
and subst-globs-only styles.</p>
|
||
<p>It is also possible to call _expand as a function, in which case the
|
||
different modes may be selected with options: -s for substitute, -g for
|
||
glob and -o for subst-globs-only.</p>
|
||
<p><span id="index-_005fexpand_005falias"></span></p>
|
||
<p>_expand_alias</p>
|
||
<p>If the word the cursor is on is an alias, it is expanded and no other
|
||
completers are called. The types of aliases which are to be expanded can
|
||
be controlled with the styles regular, global and disabled.</p>
|
||
<p>This function is also a bindable command, see <a href="#Bindable-Commands">Bindable
|
||
Commands</a>.</p>
|
||
<p><span id="index-_005fextensions"></span></p>
|
||
<p>_extensions</p>
|
||
<p>If the cursor follows the string ‘*.’, filename extensions are
|
||
completed. The extensions are taken from files in current directory or a
|
||
directory specified at the beginning of the current word. For exact
|
||
matches, completion continues to allow other completers such as _expand
|
||
to expand the pattern. The standard add-space and prefix-hidden styles
|
||
are observed.</p>
|
||
<p><span id="index-_005fexternal_005fpwds"></span></p>
|
||
<p>_external_pwds</p>
|
||
<p>Completes current directories of other zsh processes belonging to the
|
||
current user.</p>
|
||
<p>This is intended to be used via _generic, bound to a custom key
|
||
combination. Note that pattern matching is enabled so matching is
|
||
performed similar to how it works with the _match completer.</p>
|
||
<p><span id="index-_005fhistory"></span></p>
|
||
<p>_history</p>
|
||
<p>Complete words from the shell’s command history. This completer can be
|
||
controlled by the remove-all-dups, and sort styles as for the
|
||
_history_complete_word bindable command, see <a href="#Bindable-Commands">Bindable
|
||
Commands</a> and <a href="#Completion-System-Configuration">Completion System
|
||
Configuration</a>.</p>
|
||
<p><span id="index-_005fignored"></span></p>
|
||
<p>_ignored</p>
|
||
<p>The ignored-patterns style can be set to a list of patterns which are
|
||
compared against possible completions; matching ones are removed. With
|
||
this completer those matches can be reinstated, as if no
|
||
ignored-patterns style were set. The completer actually generates its
|
||
own list of matches; which completers are invoked is determined in the
|
||
same way as for the _prefix completer. The single-ignored style is also
|
||
available as described above.</p>
|
||
<p><span id="index-_005flist"></span></p>
|
||
<p>_list</p>
|
||
<p>This completer allows the insertion of matches to be delayed until
|
||
completion is attempted a second time without the word on the line being
|
||
changed. On the first attempt, only the list of matches will be shown.
|
||
It is affected by the styles condition and word, see <a href="#Completion-System-Configuration">Completion System
|
||
Configuration</a>.</p>
|
||
<p><span id="index-_005fmatch"></span></p>
|
||
<p>_match</p>
|
||
<p>This completer is intended to be used after the _complete completer. It
|
||
behaves similarly but the string on the command line may be a pattern to
|
||
match against trial completions. This gives the effect of the
|
||
GLOB_COMPLETE option.</p>
|
||
<p>Normally completion will be performed by taking the pattern from the
|
||
line, inserting a ‘*’ at the cursor position and comparing the
|
||
resulting pattern with the possible completions generated. This can be
|
||
modified with the match-original style described above.</p>
|
||
<p>The generated matches will be offered in a menu completion unless the
|
||
insert-unambiguous style is set to ‘true’; see the description above for
|
||
other options for this style.</p>
|
||
<p>Note that matcher specifications defined globally or used by the
|
||
completion functions (the styles matcher-list and matcher) will not be
|
||
used.</p>
|
||
<p><span id="index-_005fmenu"></span></p>
|
||
<p>_menu</p>
|
||
<p>This completer was written as simple example function to show how menu
|
||
effect of disabling menu selection which can be useful with _generic
|
||
based widgets. It should be used as the first completer in the list.
|
||
Note that this is independent of the setting of the MENU_COMPLETE option
|
||
and does not work with the other menu completion widgets such as
|
||
reverse-menu-complete, or accept-and-menu-complete.</p>
|
||
<p><span id="index-_005foldlist"></span></p>
|
||
<p>_oldlist</p>
|
||
<p>This completer controls how the standard completion widgets behave when
|
||
there is an existing list of completions which may have been generated
|
||
by a special completion (i.e. a separately-bound completion command). It
|
||
allows the ordinary completion keys to continue to use the list of
|
||
completions thus generated, instead of producing a new list of ordinary
|
||
contextual completions. It should appear in the list of completers
|
||
before any of the widgets which generate matches. It uses two styles:
|
||
old-list and old-menu, see <a href="#Completion-System-Configuration">Completion System
|
||
Configuration</a>.</p>
|
||
<p><span id="index-_005fprecommand"></span></p>
|
||
<p>_precommand</p>
|
||
<p>Complete an external command in word-separated arguments, as for exec
|
||
and /usr/bin/env.</p>
|
||
<p><span id="index-_005fprefix"></span></p>
|
||
<p>_prefix</p>
|
||
<p>This completer can be used to try completion with the suffix (everything
|
||
after the cursor) ignored. In other words, the suffix will not be
|
||
considered to be part of the word to complete. The effect is similar to
|
||
the expand-or-complete-prefix command.</p>
|
||
<p>The completer style is used to decide which other completers are to be
|
||
called to generate matches. If this style is unset, the list of
|
||
completers set for the current context is used — except, of course, the
|
||
_prefix completer itself. Furthermore, if this completer appears more
|
||
than once in the list of completers only those completers not already
|
||
tried by the last invocation of _prefix will be called.</p>
|
||
<p>For example, consider this global completer style:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer \
|
||
_complete _prefix _correct _prefix:foo
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, the _prefix completer tries normal completion but ignoring the
|
||
suffix. If that doesn’t generate any matches, and neither does the call
|
||
to the _correct completer after it, _prefix will be called a second
|
||
time and, now only trying correction with the suffix ignored. On the
|
||
second invocation the completer part of the context appears as ‘foo’.</p>
|
||
<p>To use _prefix as the last resort and try only normal completion when
|
||
it is invoked:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*' completer _complete ... _prefix
|
||
zstyle ':completion::prefix:*' completer _complete
|
||
</code></pre>
|
||
</div>
|
||
<p>The add-space style is also respected. If it is set to ‘true’ then
|
||
_prefix will insert a space between the matches generated (if any) and
|
||
the suffix.</p>
|
||
<p>Note that this completer is only useful if the COMPLETE_IN_WORD option
|
||
is set; otherwise, the cursor will be moved to the end of the current
|
||
word before the completion code is called and hence there will be no
|
||
suffix.</p>
|
||
<p><span id="index-_005fuser_005fexpand"></span></p>
|
||
<p>_user_expand</p>
|
||
<p>This completer behaves similarly to the _expand completer but instead
|
||
performs expansions defined by users. The styles add-space and sort
|
||
styles specific to the _expand completer are usable with _user_expand
|
||
in addition to other styles handled more generally by the completion
|
||
system. The tag all-expansions is also available.</p>
|
||
<p>The expansion depends on the array style user-expand being defined for
|
||
the current context; remember that the context for completers is less
|
||
specific than that for contextual completion as the full context has not
|
||
yet been determined. Elements of the array may have one of the following
|
||
forms:</p>
|
||
<p>$<code>hash</code><br />
|
||
<code>hash</code> is the name of an associative array. Note this is not a full
|
||
parameter expression, merely a $, suitably quoted to prevent immediate
|
||
expansion, followed by the name of an associative array. If the trial
|
||
expansion word matches a key in <code>hash</code>, the resulting expansion is the
|
||
corresponding value.</p>
|
||
<p><code>_func</code><br />
|
||
<code>_func</code> is the name of a shell function whose name must begin with _
|
||
but is not otherwise special to the completion system. The function is
|
||
called with the trial word as an argument. If the word is to be
|
||
expanded, the function should set the array reply to a list of
|
||
expansions. Optionally, it can set REPLY to a word that will be used as
|
||
a description for the set of expansions. The return status of the
|
||
function is irrelevant.</p>
|
||
<hr />
|
||
<p><span id="Bindable-Commands"></span> <span
|
||
id="Bindable-Commands-1"></span></p>
|
||
<h2 id="205-bindable-commands"><a class="header" href="#205-bindable-commands">20.5 Bindable Commands</a></h2>
|
||
<p><span id="index-completion-system_002c-bindable-commands"></span></p>
|
||
<p>In addition to the context-dependent completions provided, which are
|
||
expected to work in an intuitively obvious way, there are a few widgets
|
||
implementing special behaviour which can be bound separately to keys.
|
||
The following is a list of these and their default bindings.</p>
|
||
<p><span id="index-_005fbash_005fcompletions"></span></p>
|
||
<p>_bash_completions</p>
|
||
<p>This function is used by two widgets, _bash_complete-word and
|
||
_bash_list-choices. It exists to provide compatibility with completion
|
||
bindings in bash. The last character of the binding determines what is
|
||
completed: ‘!’, command names; ‘$’, environment variables; ‘@’, host
|
||
names; ‘/’, file names; ‘~’ user names. In bash, the binding preceded
|
||
by ‘\e’ gives completion, and preceded by ‘^X’ lists options. As some
|
||
of these bindings clash with standard zsh bindings, only ‘\e~’ and
|
||
‘^X~’ are bound by default. To add the rest, the following should be
|
||
added to .zshrc after compinit has been run:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">for key in '!' '$' '@' '/' '~'; do
|
||
bindkey "\e$key" _bash_complete-word
|
||
bindkey "^X$key" _bash_list-choices
|
||
done
|
||
</code></pre>
|
||
</div>
|
||
<p>This includes the bindings for ‘~’ in case they were already bound to
|
||
something else; the completion code does not override user bindings.</p>
|
||
<p><span id="index-_005fcorrect_005ffilename-_0028_005eXC_0029"></span></p>
|
||
<p>_correct_filename (^XC)</p>
|
||
<p>Correct the filename path at the cursor position. Allows up to six
|
||
errors in the name. Can also be called with an argument to correct a
|
||
filename path, independently of zle; the correction is printed on
|
||
standard output.</p>
|
||
<p><span id="index-_005fcorrect_005fword-_0028_005eXc_0029"></span></p>
|
||
<p>_correct_word (^Xc)</p>
|
||
<p>Performs correction of the current argument using the usual contextual
|
||
completions as possible choices. This stores the string ‘correct-word’
|
||
in the <code>function</code> field of the context name and then calls the _correct
|
||
completer.</p>
|
||
<p><span id="index-_005fexpand_005falias-_0028_005eXa_0029"></span></p>
|
||
<p>_expand_alias (^Xa)</p>
|
||
<p>This function can be used as a completer and as a bindable command. It
|
||
expands the word the cursor is on if it is an alias. The types of alias
|
||
expanded can be controlled with the styles regular, global and disabled.</p>
|
||
<p>When used as a bindable command there is one additional feature that can
|
||
be selected by setting the complete style to ‘true’. In this case, if
|
||
the word is not the name of an alias, _expand_alias tries to complete
|
||
the word to a full alias name without expanding it. It leaves the cursor
|
||
directly after the completed word so that invoking _expand_alias once
|
||
more will expand the now-complete alias name.</p>
|
||
<p><span id="index-_005fexpand_005fword-_0028_005eXe_0029"></span></p>
|
||
<p>_expand_word (^Xe)</p>
|
||
<p>Performs expansion on the current word: equivalent to the standard
|
||
expand-word command, but using the _expand completer. Before calling
|
||
it, the <code>function</code> field of the context is set to ‘expand-word’.</p>
|
||
<p><span id="index-_005fgeneric"></span></p>
|
||
<p>_generic</p>
|
||
<p>This function is not defined as a widget and not bound by default.
|
||
However, it can be used to define a widget and will then store the name
|
||
of the widget in the <code>function</code> field of the context and call the
|
||
completion system. This allows custom completion widgets with their own
|
||
set of style settings to be defined easily. For example, to define a
|
||
widget that performs normal completion and starts menu selection:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zle -C foo complete-word _generic
|
||
bindkey '...' foo
|
||
zstyle ':completion:foo:*' menu yes select=1
|
||
</code></pre>
|
||
</div>
|
||
<p>Note in particular that the completer style may be set for the context
|
||
in order to change the set of functions used to generate possible
|
||
matches. If _generic is called with arguments, those are passed through
|
||
to _main_complete as the list of completers in place of those defined
|
||
by the completer style.</p>
|
||
<p><span
|
||
id="index-_005fhistory_005fcomplete_005fword-_0028_005ce_002f_0029"></span></p>
|
||
<p>_history_complete_word (\e/)</p>
|
||
<p>Complete words from the shell’s command history. This uses the list,
|
||
remove-all-dups, sort, and stop styles.</p>
|
||
<p><span id="index-_005fmost_005frecent_005ffile-_0028_005eXm_0029"></span></p>
|
||
<p>_most_recent_file (^Xm)</p>
|
||
<p>Complete the name of the most recently modified file matching the
|
||
pattern on the command line (which may be blank). If given a numeric
|
||
argument <code>N</code>, complete the <code>N</code>th most recently modified file. Note the
|
||
completion, if any, is always unique.</p>
|
||
<p><span id="index-_005fnext_005ftags-_0028_005eXn_0029"></span></p>
|
||
<p>_next_tags (^Xn)</p>
|
||
<p>This command alters the set of matches used to that for the next tag, or
|
||
set of tags, either as given by the tag-order style or as set by
|
||
default; these matches would otherwise not be available. Successive
|
||
invocations of the command cycle through all possible sets of tags.</p>
|
||
<p><span id="index-_005fread_005fcomp-_0028_005eX_005eR_0029"></span></p>
|
||
<p>_read_comp (^X^R)</p>
|
||
<p>Prompt the user for a string, and use that to perform completion on the
|
||
current word. There are two possibilities for the string. First, it can
|
||
be a set of words beginning ‘_’, for example ‘_files -/’, in which
|
||
case the function with any arguments will be called to generate the
|
||
completions. Unambiguous parts of the function name will be completed
|
||
automatically (normal completion is not available at this point) until a
|
||
space is typed.</p>
|
||
<p>Second, any other string will be passed as a set of arguments to compadd
|
||
and should hence be an expression specifying what should be completed.</p>
|
||
<p>A very restricted set of editing commands is available when reading the
|
||
string: ‘DEL’ and ‘^H’ delete the last character; ‘^U’ deletes the line,
|
||
and ‘^C’ and ‘^G’ abort the function, while ‘RET’ accepts the
|
||
completion. Note the string is used verbatim as a command line, so
|
||
arguments must be quoted in accordance with standard shell rules.</p>
|
||
<p>Once a string has been read, the next call to _read_comp will use the
|
||
existing string instead of reading a new one. To force a new string to
|
||
be read, call _read_comp with a numeric argument.</p>
|
||
<p><span id="index-_005fcomplete_005fdebug-_0028_005eX_003f_0029"></span></p>
|
||
<p>_complete_debug (^X?)</p>
|
||
<p>This widget performs ordinary completion, but captures in a temporary
|
||
file a trace of the shell commands executed by the completion system.
|
||
Each completion attempt gets its own file. A command to view each of
|
||
these files is pushed onto the editor buffer stack.</p>
|
||
<p><span id="index-_005fcomplete_005fhelp-_0028_005eXh_0029"></span></p>
|
||
<p>_complete_help (^Xh)</p>
|
||
<p>This widget displays information about the context names, the tags, and
|
||
the completion functions used when completing at the current cursor
|
||
position. If given a numeric argument other than 1 (as in ‘ESC-2 ^Xh’),
|
||
then the styles used and the contexts for which they are used will be
|
||
shown, too.</p>
|
||
<p>Note that the information about styles may be incomplete; it depends on
|
||
the information available from the completion functions called, which in
|
||
turn is determined by the user’s own styles and other settings.</p>
|
||
<p><span id="index-_005fcomplete_005fhelp_005fgeneric"></span></p>
|
||
<p>_complete_help_generic</p>
|
||
<p>Unlike other commands listed here, this must be created as a normal ZLE
|
||
widget rather than a completion widget (i.e. with zle -N). It is used
|
||
for generating help with a widget bound to the _generic widget that is
|
||
described above.</p>
|
||
<p>If this widget is created using the name of the function, as it is by
|
||
default, then when executed it will read a key sequence. This is
|
||
expected to be bound to a call to a completion function that uses the
|
||
_generic widget. That widget will be executed, and information provided
|
||
in the same format that the _complete_help widget displays for
|
||
contextual completion.</p>
|
||
<p>If the widget’s name contains debug, for example if it is created as
|
||
‘zle -N _complete_debug_generic _complete_help_generic’, it will read
|
||
and execute the keystring for a generic widget as before, but then
|
||
generate debugging information as done by _complete_debug for
|
||
contextual completion.</p>
|
||
<p>If the widget’s name contains noread, it will not read a keystring but
|
||
instead arrange that the next use of a generic widget run in the same
|
||
shell will have the effect as described above.</p>
|
||
<p>The widget works by setting the shell parameter ZSH_TRACE_GENERIC_WIDGET
|
||
which is read by _generic. Unsetting the parameter cancels any pending
|
||
effect of the noread form.</p>
|
||
<p>For example, after executing the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zle -N _complete_debug_generic _complete_help_generic
|
||
bindkey '^x:' _complete_debug_generic
|
||
</code></pre>
|
||
</div>
|
||
<p>typing ‘C-x :’ followed by the key sequence for a generic widget will
|
||
cause trace output for that widget to be saved to a file.</p>
|
||
<p><span id="index-_005fcomplete_005ftag-_0028_005eXt_0029"></span></p>
|
||
<p>_complete_tag (^Xt)</p>
|
||
<p>This widget completes symbol tags created by the etags or ctags
|
||
programmes (note there is no connection with the completion system’s
|
||
tags) stored in a file TAGS, in the format used by etags, or tags, in
|
||
the format created by ctags. It will look back up the path hierarchy for
|
||
the first occurrence of either file; if both exist, the file TAGS is
|
||
preferred. You can specify the full path to a TAGS or tags file by
|
||
setting the parameter $TAGSFILE or $tagsfile respectively. The
|
||
corresponding completion tags used are etags and vtags, after emacs and
|
||
vi respectively.</p>
|
||
<hr />
|
||
<p><span id="Completion-Functions"></span> <span
|
||
id="Utility-Functions-1"></span></p>
|
||
<h2 id="206-utility-functions"><a class="header" href="#206-utility-functions">20.6 Utility Functions</a></h2>
|
||
<p><span id="index-completion-system_002c-utility-functions"></span></p>
|
||
<p>Descriptions follow for utility functions that may be useful when
|
||
writing completion functions. If functions are installed in
|
||
subdirectories, most of these reside in the Base subdirectory. Like the
|
||
example functions for commands in the distribution, the utility
|
||
functions generating matches all follow the convention of returning
|
||
status zero if they generated completions and non-zero if no matching
|
||
completions could be added.</p>
|
||
<p><span id="index-_005fabsolute_005fcommand_005fpaths"></span></p>
|
||
<p>_absolute_command_paths</p>
|
||
<p>This function completes external commands as absolute paths (unlike
|
||
_command_names -e which completes their basenames). It takes no
|
||
arguments.</p>
|
||
<p><span id="index-_005fall_005flabels"></span></p>
|
||
<p>_all_labels [ -x ] [ -12VJ ] <code>tag</code> <code>name</code> <code>descr</code> [ <code>command</code>
|
||
<code>arg</code> ... ]</p>
|
||
<p>This is a convenient interface to the _next_label function below,
|
||
implementing the loop shown in the _next_label example. The <code>command</code>
|
||
and its arguments are called to generate the matches. The options stored
|
||
in the parameter <code>name</code> will automatically be inserted into the <code>arg</code>s
|
||
passed to the <code>command</code>. Normally, they are put directly after the
|
||
<code>command</code>, but if one of the <code>arg</code>s is a single hyphen, they are
|
||
inserted directly before that. If the hyphen is the last argument, it
|
||
will be removed from the argument list before the <code>command</code> is called.
|
||
This allows _all_labels to be used in almost all cases where the
|
||
matches can be generated by a single call to the compadd builtin command
|
||
or by a call to one of the utility functions.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local expl
|
||
...
|
||
if _requested foo; then
|
||
...
|
||
_all_labels foo expl '...' compadd ... - $matches
|
||
fi
|
||
</code></pre>
|
||
</div>
|
||
<p>Will complete the strings from the matches parameter, using compadd with
|
||
additional options which will take precedence over those generated by
|
||
_all_labels.</p>
|
||
<p><span id="index-_005falternative"></span></p>
|
||
<p>_alternative [ -O <code>name</code> ] [ -C <code>name</code> ] <code>spec</code> ...</p>
|
||
<p>This function is useful in simple cases where multiple tags are
|
||
available. Essentially it implements a loop like the one described for
|
||
the _tags function below.</p>
|
||
<p>The tags to use and the action to perform if a tag is requested are
|
||
described using the <code>spec</code>s which are of the form:
|
||
‘<code>tag</code>:<code>descr</code>:<code>action</code>’. The <code>tag</code>s are offered using _tags and if the
|
||
tag is requested, the <code>action</code> is executed with the given description
|
||
<code>descr</code>. The <code>action</code>s are those accepted by the _arguments function
|
||
(described below), with the following exceptions:</p>
|
||
<ul>
|
||
<li>The ‘-><code>state</code>’ and ‘=<code>...</code>’ forms are not supported.</li>
|
||
<li>The ‘((a\:bar b\:baz))’ form does not need the colon to be
|
||
escaped, since the <code>spec</code>s have no colon-separated fields after the
|
||
<code>action</code>.</li>
|
||
</ul>
|
||
<p>For example, the <code>action</code> may be a simple function call:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_alternative \
|
||
'users:user:_users' \
|
||
'hosts:host:_hosts'
|
||
</code></pre>
|
||
</div>
|
||
<p>offers usernames and hostnames as possible matches, generated by the
|
||
_users and _hosts functions respectively.</p>
|
||
<p>Like _arguments, this function uses _all_labels to execute the
|
||
actions, which will loop over all sets of tags. Special handling is only
|
||
required if there is an additional valid tag, for example inside a
|
||
function called from _alternative.</p>
|
||
<p>The option ‘-O <code>name</code>’ is used in the same way as by the _arguments
|
||
function. In other words, the elements of the <code>name</code> array will be
|
||
passed to compadd when executing an action.</p>
|
||
<p>Like _tags this function supports the -C option to give a different
|
||
name for the argument context field.</p>
|
||
<p><span id="index-_005farguments"></span></p>
|
||
<p>_arguments [ -nswWCRS ] [ -A <code>pat</code> ] [ -O <code>name</code> ] [ -M
|
||
<code>matchspec</code> ]</p>
|
||
<p> [ : ] <code>spec</code> ...</p>
|
||
<p>_arguments [ <code>opt</code> ... ] -- [ -l ] [ -i <code>pats</code> ] [ -s <code>pair</code> ]</p>
|
||
<p> [ <code>helpspec</code> ...]</p>
|
||
<p>This function can be used to give a complete specification for
|
||
completion for a command whose arguments follow standard UNIX option and
|
||
argument conventions.</p>
|
||
<p><em>Options Overview</em></p>
|
||
<p>Options to _arguments itself must be in separate words, i.e. -s -w, not
|
||
-sw. The options are followed by <code>spec</code>s that describe options and
|
||
arguments of the analyzed command. To avoid ambiguity, all options to
|
||
_arguments itself may be separated from the <code>spec</code> forms by a single
|
||
colon.</p>
|
||
<p>The ‘--’ form is used to intuit <code>spec</code> forms from the help output of the
|
||
command being analyzed, and is described in detail below. The <code>opts</code> for
|
||
the ‘--’ form are otherwise the same options as the first form. Note
|
||
that ‘-s’ following ‘--’ has a distinct meaning from ‘-s’ preceding
|
||
‘--’, and both may appear.</p>
|
||
<p>The option switches -s, -S, -A, -w, and -W affect how _arguments parses
|
||
the analyzed command line’s options. These switches are useful for
|
||
commands with standard argument parsing.</p>
|
||
<p>The options of _arguments have the following meanings:</p>
|
||
<p>-n<br />
|
||
With this option, _arguments sets the parameter NORMARG to the position
|
||
of the first normal argument in the $words array, i.e. the position
|
||
after the end of the options. If that argument has not been reached,
|
||
NORMARG is set to -1. The caller should declare ‘integer NORMARG’ if the
|
||
-n option is passed; otherwise the parameter is not used.</p>
|
||
<p>-s<br />
|
||
Enable <em>option stacking</em> for single-letter options, whereby multiple
|
||
single-letter options may be combined into a single word. For example,
|
||
the two options ‘-x’ and ‘-y’ may be combined into a single word ‘-xy’.
|
||
By default, every word corresponds to a single option name (‘-xy’ is a
|
||
single option named ‘xy’).</p>
|
||
<p>Options beginning with a single hyphen or plus sign are eligible for
|
||
stacking; words beginning with two hyphens are not.</p>
|
||
<p>Note that -s after -- has a different meaning, which is documented in
|
||
the segment entitled ‘Deriving <code>spec</code> forms from the help output’.</p>
|
||
<p>-w<br />
|
||
In combination with -s, allow option stacking even if one or more of the
|
||
options take arguments. For example, if -x takes an argument, with no
|
||
-s, ‘-xy’ is considered as a single (unhandled) option; with -s, -xy is
|
||
an option with the argument ‘y’; with both -s and -w, -xy is the option
|
||
-x and the option -y with arguments to -x (and to -y, if it takes
|
||
arguments) still to come in subsequent words.</p>
|
||
<p>-W<br />
|
||
This option takes -w a stage further: it is possible to complete
|
||
single-letter options even after an argument that occurs in the same
|
||
word. However, it depends on the action performed whether options will
|
||
really be completed at this point. For more control, use a utility
|
||
function like _guard as part of the action.</p>
|
||
<p>-C<br />
|
||
Modify the curcontext parameter for an action of the form ‘-><code>state</code>’.
|
||
This is discussed in detail below.</p>
|
||
<p>-R<br />
|
||
Return status 300 instead of zero when a $state is to be handled, in the
|
||
‘-><code>string</code>’ syntax.</p>
|
||
<p>-S<br />
|
||
Do not complete options after a ‘--’ appearing on the line, and ignore
|
||
the ‘--’. For example, with -S, in the line</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">foobar -x -- -y
|
||
</code></pre>
|
||
</div>
|
||
<p>the ‘-x’ is considered an option, the ‘-y’ is considered an argument,
|
||
and the ‘--’ is considered to be neither.</p>
|
||
<p>-A <code>pat</code><br />
|
||
Do not complete options after the first non-option argument on the line.
|
||
<code>pat</code> is a pattern matching all strings which are not to be taken as
|
||
arguments. For example, to make _arguments stop completing options
|
||
after the first normal argument, but ignoring all strings starting with
|
||
a hyphen even if they are not described by one of the <code>optspec</code>s, the
|
||
form is ‘-A "-*"’.</p>
|
||
<p>-O <code>name</code><br />
|
||
Pass the elements of the array <code>name</code> as arguments to functions called
|
||
to execute <code>action</code>s. This is discussed in detail below.</p>
|
||
<p>-M <code>matchspec</code><br />
|
||
Use the match specification <code>matchspec</code> for completing option names and
|
||
values. The default <code>matchspec</code> allows partial word completion after
|
||
‘_’ and ‘-’, such as completing ‘-f-b’ to ‘-foo-bar’. The default
|
||
<code>matchspec</code> is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">r:|[_-]=* r:|=*
|
||
</code></pre>
|
||
</div>
|
||
<p>-0<br />
|
||
When populating values of the ‘opt_args’ associative array, don’t
|
||
backslash-escape colons and backslashes and use NUL rather than colon
|
||
for joining multiple values. This option is described in more detail
|
||
below, under the heading <em><code>spec</code>s: actions</em>.</p>
|
||
<p><em><code>spec</code>s: overview</em></p>
|
||
<p>Each of the following forms is a <code>spec</code> describing individual sets of
|
||
options or arguments on the command line being analyzed.</p>
|
||
<p><code>n</code>:<code>message</code>:<code>action</code><br />
|
||
<code>n</code>::<code>message</code>:<code>action</code><br />
|
||
This describes the <code>n</code>’th normal argument. The <code>message</code> will be printed
|
||
above the matches generated and the <code>action</code> indicates what can be
|
||
completed in this position (see below). If there are two colons before
|
||
the <code>message</code> the argument is optional. If the <code>message</code> contains only
|
||
white space, nothing will be printed above the matches unless the action
|
||
adds an explanation string itself.</p>
|
||
<p>:<code>message</code>:<code>action</code><br />
|
||
::<code>message</code>:<code>action</code><br />
|
||
Similar, but describes the <em>next</em> argument, whatever number that happens
|
||
to be. If all arguments are specified in this form in the correct order
|
||
the numbers are unnecessary.</p>
|
||
<p>*:<code>message</code>:<code>action</code><br />
|
||
*::<code>message</code>:<code>action</code><br />
|
||
*:::<code>message</code>:<code>action</code><br />
|
||
This describes how arguments (usually non-option arguments, those not
|
||
beginning with - or +) are to be completed when neither of the first two
|
||
forms was provided. Any number of arguments can be completed in this
|
||
fashion.</p>
|
||
<p>With two colons before the <code>message</code>, the words special array and the
|
||
CURRENT special parameter are modified to refer only to the normal
|
||
arguments when the <code>action</code> is executed or evaluated. With three colons
|
||
before the <code>message</code> they are modified to refer only to the normal
|
||
arguments covered by this description.</p>
|
||
<p><code>optspec</code><br />
|
||
<code>optspec</code>:<code>...</code><br />
|
||
This describes an option. The colon indicates handling for one or more
|
||
arguments to the option; if it is not present, the option is assumed to
|
||
take no arguments.</p>
|
||
<p>The following forms are available for the initial <code>optspec</code>, whether or
|
||
not the option has arguments.</p>
|
||
<p>*<code>optspec</code><br />
|
||
Here <code>optspec</code> is one of the remaining forms below. This indicates the
|
||
following <code>optspec</code> may be repeated. Otherwise if the corresponding
|
||
option is already present on the command line to the left of the cursor
|
||
it will not be offered again.</p>
|
||
<p>-<code>optname</code><br />
|
||
+<code>optname</code><br />
|
||
In the simplest form the <code>optspec</code> is just the option name beginning
|
||
with a minus or a plus sign, such as ‘-foo’. The first argument for the
|
||
option (if any) must follow as a <em>separate</em> word directly after the
|
||
option.</p>
|
||
<p>Either of ‘-+<code>optname</code>’ and ‘+-<code>optname</code>’ can be used to specify that
|
||
-<code>optname</code> and +<code>optname</code> are both valid.</p>
|
||
<p>In all the remaining forms, the leading ‘-’ may be replaced by or paired
|
||
with ‘+’ in this way.</p>
|
||
<p>-<code>optname</code>-<br />
|
||
The first argument of the option must come directly after the option
|
||
name <em>in the same word</em>. For example, ‘-foo-:<code>...</code>’ specifies that the
|
||
completed option and argument will look like ‘-foo<code>arg</code>’.</p>
|
||
<p>-<code>optname</code>+<br />
|
||
The first argument may appear immediately after <code>optname</code> in the same
|
||
word, or may appear as a separate word after the option. For example,
|
||
‘-foo+:<code>...</code>’ specifies that the completed option and argument will look
|
||
like either ‘-foo<code>arg</code>’ or ‘-foo <code>arg</code>’.</p>
|
||
<p>-<code>optname</code>=<br />
|
||
The argument may appear as the next word, or in same word as the option
|
||
name provided that it is separated from it by an equals sign, for
|
||
example ‘-foo=<code>arg</code>’ or ‘-foo <code>arg</code>’.</p>
|
||
<p>-<code>optname</code>=-<br />
|
||
The argument to the option must appear after an equals sign in the same
|
||
word, and may not be given in the next argument.</p>
|
||
<p><code>optspec</code>[<code>explanation</code>]<br />
|
||
An explanation string may be appended to any of the preceding forms of
|
||
<code>optspec</code> by enclosing it in brackets, as in ‘-q[query operation]’.</p>
|
||
<p>The verbose style is used to decide whether the explanation strings are
|
||
displayed with the option in a completion listing.</p>
|
||
<p>If no bracketed explanation string is given but the auto-description
|
||
style is set and only one argument is described for this <code>optspec</code>, the
|
||
value of the style is displayed, with any appearance of the sequence
|
||
‘%d’ in it replaced by the <code>message</code> of the first <code>optarg</code> that follows
|
||
the <code>optspec</code>; see below.</p>
|
||
<p>It is possible for options with a literal ‘+’ or ‘=’ to appear, but that
|
||
character must be quoted, for example ‘-\+’.</p>
|
||
<p>Each <code>optarg</code> following an <code>optspec</code> must take one of the following
|
||
forms:</p>
|
||
<p>:<code>message</code>:<code>action</code><br />
|
||
::<code>message</code>:<code>action</code><br />
|
||
An argument to the option; <code>message</code> and <code>action</code> are treated as for
|
||
ordinary arguments. In the first form, the argument is mandatory, and in
|
||
the second form it is optional.</p>
|
||
<p>This group may be repeated for options which take multiple arguments. In
|
||
other words, :<code>message1</code>:<code>action1</code>:<code>message2</code>:<code>action2</code> specifies that
|
||
the option takes two arguments.</p>
|
||
<p>:*<code>pattern</code>:<code>message</code>:<code>action</code><br />
|
||
:*<code>pattern</code>::<code>message</code>:<code>action</code><br />
|
||
:*<code>pattern</code>:::<code>message</code>:<code>action</code><br />
|
||
This describes multiple arguments. Only the last <code>optarg</code> for an option
|
||
taking multiple arguments may be given in this form. If the <code>pattern</code> is
|
||
empty (i.e. :*:), all the remaining words on the line are to be
|
||
completed as described by the <code>action</code>; otherwise, all the words up to
|
||
and including a word matching the <code>pattern</code> are to be completed using
|
||
the <code>action</code>.</p>
|
||
<p>Multiple colons are treated as for the ‘*:<code>...</code>’ forms for ordinary
|
||
arguments: when the <code>message</code> is preceded by two colons, the words
|
||
special array and the CURRENT special parameter are modified during the
|
||
execution or evaluation of the <code>action</code> to refer only to the words after
|
||
the option. When preceded by three colons, they are modified to refer
|
||
only to the words covered by this description.</p>
|
||
<p>Any literal colon in an <code>optname</code>, <code>message</code>, or <code>action</code> must be
|
||
preceded by a backslash, ‘\:’.</p>
|
||
<p>Each of the forms above may be preceded by a list in parentheses of
|
||
option names and argument numbers. If the given option is on the command
|
||
line, the options and arguments indicated in parentheses will not be
|
||
offered. For example, ‘(-two -three 1)-one:<code>...</code>’ completes the option
|
||
‘-one’; if this appears on the command line, the options -two and -three
|
||
and the first ordinary argument will not be completed after it.
|
||
‘(-foo):<code>...</code>’ specifies an ordinary argument completion; -foo will not
|
||
be completed if that argument is already present.</p>
|
||
<p>Other items may appear in the list of excluded options to indicate
|
||
various other items that should not be applied when the current
|
||
specification is matched: a single star (*) for the rest arguments
|
||
(i.e. a specification of the form ‘*:<code>...</code>’); a colon (:) for all
|
||
normal (non-option-) arguments; and a hyphen (-) for all options. For
|
||
example, if ‘(*)’ appears before an option and the option appears on
|
||
the command line, the list of remaining arguments completed.</p>
|
||
<p>To aid in reuse of specifications, it is possible to precede any of the
|
||
forms above with ‘!’; then the form will no longer be completed,
|
||
although if the option or argument appears on the command line they will
|
||
be skipped as normal. The main use for this is when the arguments are
|
||
given by an array, and _arguments is called repeatedly for more
|
||
specific contexts: on the first call ‘_arguments $global_options’ is
|
||
used, and on subsequent calls ‘_arguments !$^global_options’.</p>
|
||
<p><em><code>spec</code>s: actions</em></p>
|
||
<p>In each of the forms above the <code>action</code> determines how completions
|
||
should be generated. Except for the ‘-><code>string</code>’ form below, the
|
||
<code>action</code> will be executed by calling the _all_labels function to
|
||
process all tag labels. No special handling of tags is needed unless a
|
||
function call introduces a new one.</p>
|
||
<p>The functions called to execute <code>action</code>s will be called with the
|
||
elements of the array named by the ‘-O <code>name</code>’ option as arguments. This
|
||
can be used, for example, to pass the same set of options for the
|
||
compadd builtin to all <code>action</code>s.</p>
|
||
<p>The forms for <code>action</code> are as follows.</p>
|
||
<p> (single unquoted space)<br />
|
||
This is useful where an argument is required but it is not possible or
|
||
desirable to generate matches for it. The <code>message</code> will be displayed
|
||
but no completions listed. Note that even in this case the colon at the
|
||
end of the <code>message</code> is needed; it may only be omitted when neither a
|
||
<code>message</code> nor an <code>action</code> is given.</p>
|
||
<p>(<code>item1</code> <code>item2</code> <code>...</code>)<br />
|
||
One of a list of possible matches, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">:foo:(foo bar baz)
|
||
</code></pre>
|
||
</div>
|
||
<p>((<code>item1</code>\:<code>desc1</code> <code>...</code>))<br />
|
||
Similar to the above, but with descriptions for each possible match.
|
||
Note the backslash before the colon. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">:foo:((a\:bar b\:baz))
|
||
</code></pre>
|
||
</div>
|
||
<p>The matches will be listed together with their descriptions if the
|
||
description style is set with the values tag in the context.</p>
|
||
<p>-><code>string</code><br />
|
||
<span id="index-context_002c-use-of"></span> <span
|
||
id="index-line_002c-use-of"></span> <span
|
||
id="index-opt_005fargs_002c-use-of"></span></p>
|
||
<p>In this form, _arguments processes the arguments and options and then
|
||
returns control to the calling function with parameters set to indicate
|
||
the state of processing; the calling function then makes its own
|
||
arrangements for generating completions. For example, functions that
|
||
implement a state machine can use this type of action.</p>
|
||
<p>Where _arguments encounters <code>action</code> in the ‘-><code>string</code>’ format, it
|
||
will strip all leading and trailing whitespace from <code>string</code> and set the
|
||
array state to the set of all <code>string</code>s for which an action is to be
|
||
performed. The elements of the array state_descr are assigned the
|
||
corresponding <code>message</code> field from each <code>optarg</code> containing such an
|
||
<code>action</code>.</p>
|
||
<p>By default and in common with all other well behaved completion
|
||
functions, _arguments returns status zero if it was able to add matches
|
||
and non-zero otherwise. However, if the -R option is given, _arguments
|
||
will instead return a status of 300 to indicate that $state is to be
|
||
handled.</p>
|
||
<p>In addition to $state and $state_descr, _arguments also sets the global
|
||
parameters ‘context’, ‘line’ and ‘opt_args’ as described below, and does
|
||
not reset any changes made to the special parameters such as PREFIX and
|
||
words. This gives the calling function the choice of resetting these
|
||
parameters or propagating changes in them.</p>
|
||
<p>A function calling _arguments with at least one action containing a
|
||
‘-><code>string</code>’ must therefore declare appropriate local parameters:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local context state state_descr line
|
||
typeset -A opt_args
|
||
</code></pre>
|
||
</div>
|
||
<p>to prevent _arguments from altering the global environment.</p>
|
||
<p>{<code>eval-string</code>}<br />
|
||
<span id="index-expl_002c-use-of"></span></p>
|
||
<p>A string in braces is evaluated as shell code to generate matches. If
|
||
the <code>eval-string</code> itself does not begin with an opening parenthesis or
|
||
brace it is split into separate words before execution.</p>
|
||
<p>= <code>action</code><br />
|
||
If the <code>action</code> starts with ‘= ’ (an equals sign followed by a space),
|
||
_arguments will insert the contents of the <code>argument</code> field of the
|
||
current context as the new first element in the words special array and
|
||
increment the value of the CURRENT special parameter. This has the
|
||
effect of inserting a dummy word onto the completion command line while
|
||
not changing the point at which completion is taking place.</p>
|
||
<p>This is most useful with one of the specifiers that restrict the words
|
||
on the command line on which the <code>action</code> is to operate (the two- and
|
||
three-colon forms above). One particular use is when an <code>action</code> itself
|
||
causes _arguments on a restricted range; it is necessary to use this
|
||
trick to insert an appropriate command name into the range for the
|
||
second call to _arguments to be able to parse the line.</p>
|
||
<p><code> word...</code><br />
|
||
<code>word...</code><br />
|
||
This covers all forms other than those above. If the <code>action</code> starts
|
||
with a space, the remaining list of words will be invoked unchanged.</p>
|
||
<p>Otherwise it will be invoked with some extra strings placed after the
|
||
first word; these are to be passed down as options to the compadd
|
||
builtin. They ensure that the state specified by _arguments, in
|
||
particular the descriptions of options and arguments, is correctly
|
||
passed to the completion command. These additional arguments are taken
|
||
from the array parameter ‘expl’; this will be set up before executing
|
||
the <code>action</code> and hence may be referred to inside it, typically in an
|
||
expansion of the form ‘$expl[@]’ which preserves empty elements of the
|
||
array.</p>
|
||
<p>During the performance of the action the array ‘line’ will be set to the
|
||
normal arguments from the command line, i.e. the words from the command
|
||
line after the command name excluding all options and their arguments.
|
||
Options are stored in the associative array ‘opt_args’ with option names
|
||
as keys and their arguments as the values. By default, all colons and
|
||
backslashes in the value are escaped with backslashes, and if an option
|
||
has multiple arguments (for example, when using an <code>optspec</code> of the form
|
||
‘*<code>optspec</code>’), they are joined with (unescaped) colons. However, if the
|
||
-0 option was passed, no backslash escaping is performed, and multiple
|
||
values are joined with NUL bytes. For example, after ‘zsh -o foo:foo -o
|
||
bar:bar -o <TAB>’, the contents of ‘opt_args’ would be</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">typeset -A opt_args=( [-o]='foo\:foo:bar\:bar:' )
|
||
</code></pre>
|
||
</div>
|
||
<p>by default, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">typeset -A opt_args=( [-o]=$'foo:foo\x00bar:bar\x00' )
|
||
</code></pre>
|
||
</div>
|
||
<p>if _arguments had been called with the -0 option.</p>
|
||
<p>The parameter ‘context’ is set when returning to the calling function to
|
||
perform an action of the form ‘-><code>string</code>’. It is set to an array of
|
||
elements corresponding to the elements of $state. Each string of the
|
||
form ‘option<code>-opt</code>-<code>n</code>’ for the <code>n</code>’th argument of the option <code>-opt</code>, or
|
||
a string of the form ‘argument-<code>n</code>’ for the <code>n</code>’th argument. For ‘rest’
|
||
arguments, that is those in the list at the end not handled by position,
|
||
<code>n</code> is the string ‘rest’. For example, when completing the argument of
|
||
the -o option, the name is ‘option-o-1’, while for the second normal
|
||
(non-option-) argument it is ‘argument-2’.</p>
|
||
<p>Furthermore, during the evaluation of the <code>action</code> the context name in
|
||
the curcontext parameter is altered to append the same string that is
|
||
stored in the context parameter.</p>
|
||
<p>The option -C tells _arguments to modify the curcontext parameter for
|
||
an action of the form ‘-><code>state</code>’. This is the standard parameter used
|
||
to keep track of the current context. Here it (and not the context
|
||
array) should be made local to the calling function to avoid passing
|
||
back the modified value and should be initialised to the current value
|
||
at the start of the function:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local curcontext="$curcontext"
|
||
</code></pre>
|
||
</div>
|
||
<p>This is useful where it is not possible for multiple states to be valid
|
||
together.</p>
|
||
<p><em>Grouping Options</em></p>
|
||
<p>Options can be grouped to simplify exclusion lists. A group is
|
||
introduced with ‘+’ followed by a name for the group in the subsequent
|
||
word. Whole groups can then be referenced in an exclusion list or a
|
||
group name can be used to disambiguate between two forms of the same
|
||
option. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments \
|
||
'(group2--x)-a' \
|
||
+ group1 \
|
||
-m \
|
||
'(group2)-n' \
|
||
+ group2 \
|
||
-x -y
|
||
</code></pre>
|
||
</div>
|
||
<p>If the name of a group is specified in the form ‘(<code>name</code>)’ then only one
|
||
value from that group will ever be completed; more formally, all
|
||
specifications are mutually exclusive to all other specifications in
|
||
that group. This is useful for defining options that are aliases for
|
||
each other. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments \
|
||
-a -b \
|
||
+ '(operation)' \
|
||
{-c,--compress}'[compress]' \
|
||
{-d,--decompress}'[decompress]' \
|
||
{-l,--list}'[list]'
|
||
</code></pre>
|
||
</div>
|
||
<p>If an option in a group appears on the command line, it is stored in the
|
||
associative array ‘opt_args’ with ’<code>group</code>-<code>option</code>’ as a key. In the
|
||
example above, a key ‘operation–c’ is used if the option ‘-c’ is present
|
||
on the command line.</p>
|
||
<p><em>Specifying Multiple Sets of Arguments</em></p>
|
||
<p>It is possible to specify multiple sets of options and arguments with
|
||
the sets separated by single hyphens. This differs from groups in that
|
||
sets are considered to be mutually exclusive of each other.</p>
|
||
<p>Specifications before the first set and from any group are common to all
|
||
sets. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments \
|
||
-a \
|
||
- set1 \
|
||
-c \
|
||
- set2 \
|
||
-d \
|
||
':arg:(x2 y2)'
|
||
</code></pre>
|
||
</div>
|
||
<p>This defines two sets. When the command line contains the option ‘-c’,
|
||
the ‘-d’ option and the argument will not be considered possible
|
||
completions. When it contains ‘-d’ or an argument, the option ‘-c’ will
|
||
not be considered. However, after ‘-a’ both sets will still be
|
||
considered valid.</p>
|
||
<p>As for groups, the name of a set may appear in exclusion lists, either
|
||
alone or preceding a normal option or argument specification.</p>
|
||
<p>The completion code has to parse the command line separately for each
|
||
set. This can be slow so sets should only be used when necessary. A
|
||
useful alternative is often an option specification with rest-arguments
|
||
(as in ‘-foo:*:...’); here the option -foo swallows up all remaining
|
||
arguments as described by the <code>optarg</code> definitions.</p>
|
||
<p><em>Deriving <code>spec</code> forms from the help output</em></p>
|
||
<p>The option ‘--’ allows _arguments to work out the names of long options
|
||
that support the ‘--help’ option which is standard in many GNU commands.
|
||
The command word is called with the argument ‘--help’ and the output
|
||
examined for option names. Clearly, it can be dangerous to pass this to
|
||
commands which may not support this option as the behaviour of the
|
||
command is unspecified.</p>
|
||
<p>In addition to options, ‘_arguments --’ will try to deduce the types of
|
||
arguments available for options when the form ‘--<code>opt</code>=<code>val</code>’ is valid.
|
||
It is also possible to provide hints by examining the help text of the
|
||
command and adding <code>helpspec</code> of the form
|
||
‘<code>pattern</code>:<code>message</code>:<code>action</code>’; note that other _arguments <code>spec</code> forms
|
||
are not used. The <code>pattern</code> is matched against the help text for an
|
||
option, and if it matches the <code>message</code> and <code>action</code> are used as for
|
||
other argument specifiers. The special case of ‘*:’ means both
|
||
<code>message</code> and <code>action</code> are empty, which has the effect of causing
|
||
options having no description in the help output to be ordered in
|
||
listings ahead of options that have a description.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments -- '*\*:toggle:(yes no)' \
|
||
'*=FILE*:file:_files' \
|
||
'*=DIR*:directory:_files -/' \
|
||
'*=PATH*:directory:_files -/'
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, ‘yes’ and ‘no’ will be completed as the argument of options whose
|
||
description ends in a star; file names will be completed for options
|
||
that contain the substring ‘=FILE’ in the description; and directories
|
||
will be completed for options whose description contains ‘=DIR’ or
|
||
‘=PATH’. The last three are in fact the default and so need not be given
|
||
explicitly, although it is possible to override the use of these
|
||
patterns. A typical help text which uses this feature is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"> -C, --directory=DIR change to directory DIR
|
||
</code></pre>
|
||
</div>
|
||
<p>so that the above specifications will cause directories to be completed
|
||
after ‘--directory’, though not after ‘-C’.</p>
|
||
<p>Note also that _arguments tries to find out automatically if the
|
||
argument for an option is optional. This can be specified explicitly by
|
||
doubling the colon before the <code>message</code>.</p>
|
||
<p>If the <code>pattern</code> ends in ‘(-)’, this will be removed from the pattern
|
||
and the <code>action</code> will be used only directly after the ‘=’, not in the
|
||
next word. This is the behaviour of a normal specification defined with
|
||
the form ‘=-’.</p>
|
||
<p>By default, the command (with the option ‘–help’) is run after resetting
|
||
all the locale categories (except for LC_CTYPE) to ‘C’. If the localized
|
||
help output is known to work, the option ‘-l’ can be specified after the
|
||
‘_arguments --’ so that the command is run in the current locale.</p>
|
||
<p>The ‘_arguments --’ can be followed by the option ‘-i <code>patterns</code>’ to
|
||
give patterns for options which are not to be completed. The patterns
|
||
can be given as the name of an array parameter or as a literal list in
|
||
parentheses. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments -- -i \
|
||
"(--(en|dis)able-FEATURE*)"
|
||
</code></pre>
|
||
</div>
|
||
<p>will cause completion to ignore the options ‘--enable-FEATURE’ and
|
||
‘--disable-FEATURE’ (this example is useful with GNU configure).</p>
|
||
<p>The ‘_arguments --’ form can also be followed by the option ‘-s <code>pair</code>’
|
||
to describe option aliases. The <code>pair</code> consists of a list of alternating
|
||
patterns and corresponding replacements, enclosed in parens and quoted
|
||
so that it forms a single argument word in the _arguments call.</p>
|
||
<p>For example, some configure-script help output describes options only as
|
||
‘--enable-foo’, but the script also accepts the negated form
|
||
‘--disable-foo’. To allow completion of the second form:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments -- -s "((#s)--enable- --disable-)"
|
||
</code></pre>
|
||
</div>
|
||
<p><em>Miscellaneous notes</em></p>
|
||
<p>Finally, note that _arguments generally expects to be the primary
|
||
function handling any completion for which it is used. It may have side
|
||
effects which change the treatment of any matches added by other
|
||
functions called after it. To combine _arguments with other functions,
|
||
those functions should be called either before _arguments, as an
|
||
<code>action</code> within a <code>spec</code>, or in handlers for ‘-><code>state</code>’ actions.</p>
|
||
<p>Here is a more general example of the use of _arguments:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments '-l+:left border:' \
|
||
'-format:paper size:(letter A4)' \
|
||
'*-copy:output file:_files::resolution:(300 600)' \
|
||
':postscript file:_files -g \*.\(ps\|eps\)' \
|
||
'*:page number:'
|
||
</code></pre>
|
||
</div>
|
||
<p>This describes three options: ‘-l’, ‘-format’, and ‘-copy’. The first
|
||
takes one argument described as ‘<code>left border</code>’ for which no completion
|
||
will be offered because of the empty action. Its argument may come
|
||
directly after the ‘-l’ or it may be given as the next word on the line.</p>
|
||
<p>The ‘-format’ option takes one argument in the next word, described as
|
||
‘<code>paper size</code>’ for which only the strings ‘letter’ and ‘A4’ will be
|
||
completed.</p>
|
||
<p>The ‘-copy’ option may appear more than once on the command line and
|
||
takes two arguments. The first is mandatory and will be completed as a
|
||
filename. The second is optional (because of the second colon before the
|
||
description ‘<code>resolution</code>’) and will be completed from the strings ‘300’
|
||
and ‘600’.</p>
|
||
<p>The last two descriptions say what should be completed as arguments. The
|
||
first describes the first argument as a ‘<code>postscript file</code>’ and makes
|
||
files ending in ‘ps’ or ‘eps’ be completed. The last description gives
|
||
all other arguments the description ‘<code>page number</code>’ but does not offer
|
||
completions.</p>
|
||
<p><span id="index-_005fcache_005finvalid"></span></p>
|
||
<p>_cache_invalid <code>cache_identifier</code></p>
|
||
<p>This function returns status zero if the completions cache corresponding
|
||
to the given cache identifier needs rebuilding. It determines this by
|
||
looking up the cache-policy style for the current context. This should
|
||
provide a function name which is run with the full path to the relevant
|
||
cache file as the only argument.</p>
|
||
<p>Example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_example_caching_policy () {
|
||
# rebuild if cache is more than a week old
|
||
local -a oldp
|
||
oldp=( "$1"(Nm+7) )
|
||
(( $#oldp ))
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-_005fcall_005ffunction"></span></p>
|
||
<p>_call_function <code>return</code> <code>name</code> [ <code>arg</code> ... ]</p>
|
||
<p>If a function <code>name</code> exists, it is called with the arguments <code>arg</code>s. The
|
||
<code>return</code> argument gives the name of a parameter in which the return
|
||
status from the function <code>name</code> should be stored; if <code>return</code> is empty
|
||
or a single hyphen it is ignored.</p>
|
||
<p>The return status of _call_function itself is zero if the function
|
||
<code>name</code> exists and was called and non-zero otherwise.</p>
|
||
<p><span id="index-_005fcall_005fprogram"></span></p>
|
||
<p>_call_program [ -l ] [ -p ] <code>tag</code> <code>string</code> ...</p>
|
||
<p>This function provides a mechanism for the user to override the use of
|
||
an external command. It looks up the command style with the supplied
|
||
<code>tag</code>. If the style is set, its value is used as the command to execute.
|
||
The <code>string</code>s from the call to _call_program, or from the style if set,
|
||
are concatenated with spaces between them and the resulting string is
|
||
evaluated. The return status is the return status of the command called.</p>
|
||
<p>By default, the command is run in an environment where all the locale
|
||
categories (except for LC_CTYPE) are reset to ‘C’ by calling the utility
|
||
function _comp_locale (see below). If the option ‘-l’ is given, the
|
||
command is run with the current locale.</p>
|
||
<p>If the option ‘-p’ is supplied it indicates that the command output is
|
||
influenced by the permissions it is run with. If the gain-privileges
|
||
style is set to true, _call_program will make use of commands such as
|
||
sudo, if present on the command-line, to match the permissions to
|
||
whatever the final command is likely to run under. When looking up the
|
||
gain-privileges and command styles, the command component of the zstyle
|
||
context will end with a slash (‘/’) followed by the command that would
|
||
be used to gain privileges.</p>
|
||
<p><span id="index-_005fcombination"></span></p>
|
||
<p>_combination [ -s <code>pattern</code> ] <code>tag</code> <code>style</code> <code>spec</code> ... <code>field</code> <code>opts</code>
|
||
...</p>
|
||
<p>This function is used to complete combinations of values, for example
|
||
pairs of hostnames and usernames. The <code>style</code> argument gives the style
|
||
which defines the pairs; it is looked up in a context with the <code>tag</code>
|
||
specified.</p>
|
||
<p>The style name consists of field names separated by hyphens, for example
|
||
‘users-hosts-ports’. For each field for a value is already known, a
|
||
<code>spec</code> of the form ‘<code>field</code>=<code>pattern</code>’ is given. For example, if the
|
||
command line so far specifies a user ‘pws’, the argument ‘users=pws’
|
||
should appear.</p>
|
||
<p>The next argument with no equals sign is taken as the name of the field
|
||
for which completions should be generated (presumably not one of the
|
||
<code>field</code>s for which the value is known).</p>
|
||
<p>The matches generated will be taken from the value of the style. These
|
||
should contain the possible values for the combinations in the
|
||
appropriate order (users, hosts, ports in the example above). The values
|
||
for the different fields are separated by colons. This can be altered
|
||
with the option -s to _combination which specifies a pattern. Typically
|
||
this is a character class, as for example ‘-s "[:@]"’ in the case of
|
||
the users-hosts style. Each ‘<code>field</code>=<code>pattern</code>’ specification restricts
|
||
the completions which apply to elements of the style with appropriately
|
||
matching fields.</p>
|
||
<p>If no style with the given name is defined for the given tag, or if none
|
||
of the strings in style’s value match, but a function name of the
|
||
required field preceded by an underscore is defined, that function will
|
||
be called to generate the matches. For example, if there is no
|
||
‘users-hosts-ports’ or no matching hostname when a host is required, the
|
||
function ‘_hosts’ will automatically be called.</p>
|
||
<p>If the same name is used for more than one field, in both the
|
||
‘<code>field</code>=<code>pattern</code>’ and the argument that gives the name of the field to
|
||
be completed, the number of the field (starting with one) may be given
|
||
after the fieldname, separated from it by a colon.</p>
|
||
<p>All arguments after the required field name are passed to compadd when
|
||
generating matches from the style value, or to the functions for the
|
||
fields if they are called.</p>
|
||
<p><span id="index-_005fcommand_005fnames"></span></p>
|
||
<p>_command_names [ -e | - ]</p>
|
||
<p>This function completes words that are valid at command position: names
|
||
of aliases, builtins, hashed commands, functions, and so on. With the -e
|
||
flag, only hashed commands are completed. The - flag is ignored.</p>
|
||
<p><span id="index-_005fcomp_005flocale"></span></p>
|
||
<p>_comp_locale</p>
|
||
<p>This function resets all the locale categories other than LC_CTYPE to
|
||
‘C’ so that the output from external commands can be easily analyzed by
|
||
the completion system. LC_CTYPE retains the current value (taking LC_ALL
|
||
and LANG into account), ensuring that non-ASCII characters in file names
|
||
are still handled properly.</p>
|
||
<p>This function should normally be run only in a subshell, because the new
|
||
locale is exported to the environment. Typical usage would be
|
||
‘$(_comp_locale; <code>command</code> ...)’.</p>
|
||
<p><span id="index-_005fcompleters"></span></p>
|
||
<p>_completers [ -p ]</p>
|
||
<p>This function completes names of completers.</p>
|
||
<p>-p<br />
|
||
Include the leading underscore (‘_’) in the matches.</p>
|
||
<p><span id="index-_005fdefault"></span></p>
|
||
<p>_default</p>
|
||
<p>This function corresponds to the -default- special context which is
|
||
applied where no completion is defined. It is useful to call it under
|
||
certain error conditions such as completion after an unrecognised
|
||
subcommand. This applies the concept of graceful degradation to the
|
||
completion system, allowing it to fallback on basic completion of
|
||
commonly useful things like filenames.</p>
|
||
<p><span id="index-_005fdescribe"></span></p>
|
||
<p>_describe [-12JVx] [ -oO | -t <code>tag</code> ] <code>descr</code> <code>name1</code> [ <code>name2</code>
|
||
] [ <code>opt</code> ... ]</p>
|
||
<p> [ -- <code>name1</code> [ <code>name2</code> ] [ <code>opt</code> ... ] ... ]</p>
|
||
<p>This function associates completions with descriptions. Multiple groups
|
||
separated by -- can be supplied, potentially with different completion
|
||
options <code>opt</code>s.</p>
|
||
<p>The <code>descr</code> is taken as a string to display above the matches if the
|
||
format style for the descriptions tag is set. This is followed by one or
|
||
two names of arrays followed by options to pass to compadd. The array
|
||
<code>name1</code> contains the possible completions with their descriptions in the
|
||
form ‘<code>completion</code>:<code>description</code>’. Any literal colons in <code>completion</code>
|
||
must be quoted with a backslash. If a <code>name2</code> is given, it should have
|
||
the same number of elements as <code>name1</code>; in this case the corresponding
|
||
elements are added as possible completions instead of the <code>completion</code>
|
||
strings from <code>name1</code>. The completion list will retain the descriptions
|
||
from <code>name1</code>. Finally, a set of completion options can appear.</p>
|
||
<p>If the option ‘-o’ appears before the first argument, the matches added
|
||
will be treated as names of command options (N.B. not shell options),
|
||
typically following a ‘-’, ‘--’ or ‘+’ on the command line. In this case
|
||
_describe uses the prefix-hidden, prefix-needed and verbose styles to
|
||
find out if the strings should be added as completions and if the
|
||
descriptions should be shown. Without the ‘-o’ option, only the verbose
|
||
style is used to decide how descriptions are shown. If ‘-O’ is used
|
||
instead of ‘-o’, command options are completed as above but _describe
|
||
will not handle the prefix-needed style.</p>
|
||
<p>With the -t option a <code>tag</code> can be specified. The default is ‘values’ or,
|
||
if the -o option is given, ‘options’.</p>
|
||
<p>The options -1, -2, -J, -V, -x are passed to _next_label.</p>
|
||
<p>If selected by the list-grouped style, strings with the same description
|
||
will appear together in the list.</p>
|
||
<p>_describe uses the _all_labels function to generate the matches, so it
|
||
does not need to appear inside a loop over tag labels.</p>
|
||
<p><span id="index-_005fdescription"></span></p>
|
||
<p>_description [ -x ] [ -12VJ ] <code>tag</code> <code>name</code> <code>descr</code> [ <code>spec</code> ... ]</p>
|
||
<p>This function is not to be confused with the previous one; it is used as
|
||
a helper function for creating options to compadd. It is buried inside
|
||
many of the higher level completion functions and so often does not need
|
||
to be called directly.</p>
|
||
<p>The styles listed below are tested in the current context using the
|
||
given <code>tag</code>. The resulting options for compadd are put into the array
|
||
named <code>name</code> (this is traditionally ‘expl’, but this convention is not
|
||
enforced). The description for the corresponding set of matches is
|
||
passed to the function in <code>descr</code>.</p>
|
||
<p>The styles tested are: format, hidden, matcher, ignore-line,
|
||
ignored-patterns, group-name and sort. The format style is first tested
|
||
for the given <code>tag</code> and then for the descriptions tag if no value was
|
||
found, while the remainder are only tested for the tag given as the
|
||
first argument. The function also calls _setup which tests some more
|
||
styles.</p>
|
||
<p>The string returned by the format style (if any) will be modified so
|
||
that the sequence ‘%d’ is replaced by the <code>descr</code> given as the third
|
||
argument without any leading or trailing white space. If, after removing
|
||
the white space, the <code>descr</code> is the empty string, the format style will
|
||
not be used and the options put into the <code>name</code> array will not contain
|
||
an explanation string to be displayed above the matches.</p>
|
||
<p>If _description is called with more than three arguments, the
|
||
additional <code>spec</code>s should be of the form ‘<code>char</code>:<code>str</code>’. These supply
|
||
escape sequence replacements for the format style: every appearance of
|
||
‘%<code>char</code>’ will be replaced by <code>string</code>. If no additional <code>spec</code>s are
|
||
given but the description in <code>descr</code> conforms to a common form then
|
||
further escape sequences are set for elements of that description. These
|
||
elements correspond to a default (‘%r’) and the remaining initial part
|
||
of the description (‘%h’). The form the description takes consists of
|
||
specifying the units and range in parentheses and the default value in
|
||
square brackets, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_description times expl 'timeout (seconds) (0-60) [20]'
|
||
</code></pre>
|
||
</div>
|
||
<p>It is possible to use zformat conditional expressions when styling these
|
||
elements. So, for example, to add ‘default:’ as a tag but only when
|
||
there is a default value to show, the format style might include
|
||
‘%(o.default: %o.)’.</p>
|
||
<p>If the -x option is given, the description will be passed to compadd
|
||
using the -x option instead of the default -X. This means that the
|
||
description will be displayed even if there are no corresponding
|
||
matches.</p>
|
||
<p>The options placed in the array <code>name</code> take account of the group-name
|
||
style, so matches are placed in a separate group where necessary. The
|
||
group normally has its elements sorted (by passing the option -J to
|
||
compadd), but if an option starting with ‘-V’, ‘-J’, ‘-1’, or ‘-2’ is
|
||
passed to _description, that option will be included in the array.
|
||
Hence it is possible for the completion group to be unsorted by giving
|
||
the option ‘-V’, ‘-1V’, or ‘-2V’.</p>
|
||
<p>In most cases, the function will be used like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local expl
|
||
_description files expl file
|
||
compadd "$expl[@]" - "$files[@]"
|
||
</code></pre>
|
||
</div>
|
||
<p>Note the use of the parameter expl, the hyphen, and the list of matches.
|
||
Almost all calls to compadd within the completion system use a similar
|
||
format; this ensures that user-specified styles are correctly passed
|
||
down to the builtins which implement the internals of completion.</p>
|
||
<p><span id="index-_005fdir_005flist"></span></p>
|
||
<p>_dir_list [ -s <code>sep</code> ] [ -S ]</p>
|
||
<p>Complete a list of directory names separated by colons (the same format
|
||
as $PATH).</p>
|
||
<p>-s <code>sep</code><br />
|
||
Use <code>sep</code> as separator between items. <code>sep</code> defaults to a colon (‘:’).</p>
|
||
<p>-S<br />
|
||
Add <code>sep</code> instead of slash (‘/’) as an autoremoveable suffix.</p>
|
||
<p><span id="index-_005fdispatch"></span></p>
|
||
<p>_dispatch <code>context string</code> ...</p>
|
||
<p>This sets the current context to <code>context</code> and looks for completion
|
||
functions to handle this context by hunting through the list of command
|
||
names or special contexts (as described above for compdef) given as
|
||
<code>string</code>s. The first completion function to be defined for one of the
|
||
contexts in the list is used to generate matches. Typically, the last
|
||
<code>string</code> is -default- to cause the function for default completion to be
|
||
used as a fallback.</p>
|
||
<p>The function sets the parameter $service to the <code>string</code> being tried,
|
||
and sets the <code>context/command</code> field (the fourth) of the $curcontext
|
||
parameter to the <code>context</code> given as the first argument.</p>
|
||
<p><span id="index-_005femail_005faddresses"></span></p>
|
||
<p>_email_addresses [ -c ] [ -n <code>plugin</code> ]</p>
|
||
<p>Complete email addresses. Addresses are provided by plugins.</p>
|
||
<p>-c<br />
|
||
Complete bare localhost@domain.tld addresses, without a name part or a
|
||
comment. Without this option, RFC822 ‘<code>Firstname Lastname</code>
|
||
<<code>address</code>>’ strings are completed.</p>
|
||
<p>-n <code>plugin</code><br />
|
||
Complete aliases from <code>plugin</code>.</p>
|
||
<p>The following plugins are available by default: _email-ldap (see the
|
||
filter style), _email-local (completes <code>user</code>@<code>hostname</code> Unix
|
||
addresses), _email-mail (completes aliases from ~/.mailrc),
|
||
_email-mush, _email-mutt, and _email-pine.</p>
|
||
<p>Addresses from the _email-<code>foo</code> plugin are added under the tag
|
||
‘email-<code>foo</code>’.</p>
|
||
<p><em>Writing plugins</em></p>
|
||
<p>Plugins are written as separate functions with names starting with
|
||
‘_email-’. They are invoked with the -c option and compadd options.
|
||
They should either do their own completion or set the $reply array to a
|
||
list of ‘<code>alias</code>:<code>address</code>’ elements and return 300. New plugins will be
|
||
picked up and run automatically.</p>
|
||
<p><span id="index-_005ffiles"></span></p>
|
||
<p>_files</p>
|
||
<p>The function _files is a wrapper around _path_files. It supports all
|
||
of the same functionality, with some enhancements — notably, it respects
|
||
the list-dirs-first style, and it allows users to override the behaviour
|
||
of the -g and -/ options with the file-patterns style. _files should
|
||
therefore be preferred over _path_files in most cases.</p>
|
||
<p>This function accepts the full set of options allowed by _path_files,
|
||
described below.</p>
|
||
<p><span id="index-_005fgnu_005fgeneric"></span></p>
|
||
<p>_gnu_generic</p>
|
||
<p>This function is a simple wrapper around the _arguments function
|
||
described above. It can be used to determine automatically the long
|
||
options understood by commands that produce a list when passed the
|
||
option ‘--help’. It is intended to be used as a top-level completion
|
||
function in its own right. For example, to enable option completion for
|
||
the commands foo and bar, use</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">compdef _gnu_generic foo bar
|
||
</code></pre>
|
||
</div>
|
||
<p>after the call to compinit.</p>
|
||
<p>The completion system as supplied is conservative in its use of this
|
||
function, since it is important to be sure the command understands the
|
||
option ‘--help’.</p>
|
||
<p><span id="index-_005fguard"></span></p>
|
||
<p>_guard [ <code>options</code> ] <code>pattern descr</code></p>
|
||
<p>This function displays <code>descr</code> if <code>pattern</code> matches the string to be
|
||
completed. It is intended to be used in the <code>action</code> for the
|
||
specifications passed to _arguments and similar functions.</p>
|
||
<p>The return status is zero if the message was displayed and the word to
|
||
complete is not empty, and non-zero otherwise.</p>
|
||
<p>The <code>pattern</code> may be preceded by any of the options understood by
|
||
compadd that are passed down from _description, namely -M, -J, -V, -1,
|
||
-2, -n, -F and -X. All of these options will be ignored. This fits in
|
||
conveniently with the argument-passing conventions of actions for
|
||
_arguments.</p>
|
||
<p>As an example, consider a command taking the options -n and -none, where
|
||
-n must be followed by a numeric value in the same word. By using:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
|
||
</code></pre>
|
||
</div>
|
||
<p>_arguments can be made to both display the message ‘numeric value’ and
|
||
complete options after ‘-n<TAB>’. If the ‘-n’ is already followed by
|
||
one or more digits (the pattern passed to _guard) only the message will
|
||
be displayed; if the ‘-n’ is followed by another character, only options
|
||
are completed.</p>
|
||
<p><span id="index-_005fmessage"></span></p>
|
||
<p>_message [ -r12 ] [ -VJ <code>group</code> ] <code>descr</code></p>
|
||
<p>_message -e [ <code>tag</code> ] <code>descr</code></p>
|
||
<p>The <code>descr</code> is used in the same way as the third argument to the
|
||
_description function, except that the resulting string will always be
|
||
shown whether or not matches were generated. This is useful for
|
||
displaying a help message in places where no completions can be
|
||
generated.</p>
|
||
<p>The format style is examined with the messages tag to find a message;
|
||
the usual tag, descriptions, is used only if the style is not set with
|
||
the former.</p>
|
||
<p>If the -r option is given, no style is used; the <code>descr</code> is taken
|
||
literally as the string to display. This is most useful when the <code>descr</code>
|
||
comes from a pre-processed argument list which already contains an
|
||
expanded description. Note that this option does not disable the
|
||
‘%’-sequence parsing done by compadd.</p>
|
||
<p>The -12VJ options and the <code>group</code> are passed to compadd and hence
|
||
determine the group the message string is added to.</p>
|
||
<p>The second -e form gives a description for completions with the tag
|
||
<code>tag</code> to be shown even if there are no matches for that tag. This form
|
||
is called by _arguments in the event that there is no action for an
|
||
option specification. The tag can be omitted and if so the tag is taken
|
||
from the parameter $curtag; this is maintained by the completion system
|
||
and so is usually correct. Note that if there are no matches at the time
|
||
this function is called, compstate[insert] is cleared, so additional
|
||
matches generated later are not inserted on the command line.</p>
|
||
<p><span id="index-_005fmulti_005fparts"></span></p>
|
||
<p>_multi_parts [ -i ] <code>sep</code> <code>array</code></p>
|
||
<p>The argument <code>sep</code> is a separator character. The <code>array</code> may be either
|
||
the name of an array parameter or a literal array in the form ‘(foo
|
||
bar)’, a parenthesised list of words separated by whitespace. The
|
||
possible completions are the strings from the array. However, each chunk
|
||
delimited by <code>sep</code> will be completed separately. For example, the _tar
|
||
function uses ‘_multi_parts / <code>patharray</code>’ to complete partial file
|
||
paths from the given array of complete file paths.</p>
|
||
<p>The -i option causes _multi_parts to insert a unique match even if that
|
||
requires multiple separators to be inserted. This is not usually the
|
||
expected behaviour with filenames, but certain other types of
|
||
completion, for example those with a fixed set of possibilities, may be
|
||
more suited to this form.</p>
|
||
<p>Like other utility functions, this function accepts the ‘-V’, ‘-J’,
|
||
‘-1’, ‘-2’, ‘-n’, ‘-f’, ‘-X’, ‘-M’, ‘-P’, ‘-S’, ‘-r’, ‘-R’, and ‘-q’
|
||
options and passes them to the compadd builtin.</p>
|
||
<p><span id="index-_005fnext_005flabel"></span></p>
|
||
<p>_next_label [ -x ] [ -12VJ ] <code>tag</code> <code>name</code> <code>descr</code> [ <code>option</code> ...
|
||
]</p>
|
||
<p>This function is used to implement the loop over different tag labels
|
||
for a particular tag as described above for the tag-order style. On each
|
||
call it checks to see if there are any more tag labels; if there is it
|
||
returns status zero, otherwise non-zero. As this function requires a
|
||
current tag to be set, it must always follow a call to _tags or
|
||
_requested.</p>
|
||
<p>The -x12VJ options and the first three arguments are passed to the
|
||
_description function. Where appropriate the <code>tag</code> will be replaced by
|
||
a tag label in this call. Any description given in the tag-order style
|
||
is preferred to the <code>descr</code> passed to _next_label.</p>
|
||
<p>The <code>option</code>s given after the <code>descr</code> are set in the parameter given by
|
||
<code>name</code>, and hence are to be passed to compadd or whatever function is
|
||
called to add the matches.</p>
|
||
<p>Here is a typical use of this function for the tag foo. The call to
|
||
_requested determines if tag foo is required at all; the loop over
|
||
_next_label handles any labels defined for the tag in the tag-order
|
||
style.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local expl ret=1
|
||
...
|
||
if _requested foo; then
|
||
...
|
||
while _next_label foo expl '...'; do
|
||
compadd "$expl[@]" ... && ret=0
|
||
done
|
||
...
|
||
fi
|
||
return ret
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-_005fnormal"></span></p>
|
||
<p>_normal [ -P | -p <code>precommand</code> ]</p>
|
||
<p>This is the standard function called to handle completion outside any
|
||
special -<code>context</code>-. It is called both to complete the command word and
|
||
also the arguments for a command. In the second case, _normal looks for
|
||
a special completion for that command, and if there is none it uses the
|
||
completion for the -default- context.</p>
|
||
<p>A second use is to reexamine the command line specified by the $words
|
||
array and the $CURRENT parameter after those have been modified. For
|
||
example, the function _precommand, which completes after precommand
|
||
specifiers such as nohup, removes the first word from the words array,
|
||
decrements the CURRENT parameter, then calls ‘_normal -p $service’. The
|
||
effect is that ‘nohup <code>cmd ...</code>’ is treated in the same way as
|
||
‘<code>cmd ...</code>’.</p>
|
||
<p>-P<br />
|
||
Reset the list of precommands. This option should be used if completing
|
||
a command line which allows internal commands (e.g. builtins and
|
||
functions) regardless of prior precommands (e.g. ‘zsh -c’).</p>
|
||
<p>-p <code>precommand</code><br />
|
||
Append <code>precommand</code> to the list of precommands. This option should be
|
||
used in nearly all cases in which -P is not applicable.</p>
|
||
<p>If the command name matches one of the patterns given by one of the
|
||
options -p or -P to compdef, the corresponding completion function is
|
||
called and then the parameter _compskip is checked. If it is set
|
||
completion is terminated at that point even if no matches have been
|
||
found. This is the same effect as in the -first- context.</p>
|
||
<p><span id="index-_005fnumbers"></span></p>
|
||
<p>_numbers [ <code>option</code> ... ] [ <code>description</code> ] [ <code>suffix</code> ... ]</p>
|
||
<p>This can be used where a number is followed by a suffix to indicate the
|
||
units. The unit suffixes are completed and can also be included in the
|
||
description used when completion is invoked for the preceding number.</p>
|
||
<p>In addition to common compadd options, _numbers accepts the following
|
||
options:</p>
|
||
<p>-t <code>tag</code><br />
|
||
Specify a tag to use instead of the default of numbers.</p>
|
||
<p>-u <code>units</code><br />
|
||
Indicate the default units for the number, e.g. bytes.</p>
|
||
<p>-l <code>min</code><br />
|
||
Specify the lowest possible value for the number.</p>
|
||
<p>-m <code>max</code><br />
|
||
Specify the highest possible value for the number.</p>
|
||
<p>-d <code>default</code><br />
|
||
Specify the default value.</p>
|
||
<p>-N<br />
|
||
Allow negative numbers. This is implied if the range includes a
|
||
negative.</p>
|
||
<p>-f<br />
|
||
Allow decimal numbers.</p>
|
||
<p>Where a particular suffix represents the default units for a number, it
|
||
should be prefixed with a colon. Additionally, suffixes can be followed
|
||
by a colon and a description. So for example, the following allows the
|
||
age of something to be specified, either in seconds or with an optional
|
||
suffix with a longer unit of time:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_numbers -u seconds age :s:seconds m:minutes h:hours d:days
|
||
</code></pre>
|
||
</div>
|
||
<p>It is typically helpful for units to be presented in order of magnitude
|
||
when completed. To facilitate this, the order in which they are given is
|
||
preserved.</p>
|
||
<p>When the format style is looked up with the descriptions tag or the tag
|
||
specified with -t, the list of suffixes is available as a ‘%x’ escape
|
||
sequence. This is in addition to the usual sequences documented under
|
||
the format style. The form this list takes can also be configured. To
|
||
this end, the format style is first looked up with the tag
|
||
unit-suffixes. The retrieved format is applied to each suffix in turn
|
||
and the results are then concatenated to form the completed list. For
|
||
the unit-suffixes format, ‘%x’ expands to the individual suffix and ‘%X’
|
||
to its description. %d’ indicates a default suffix and can be used in a
|
||
condition. The index and reverse index are set in ‘%i’ and ‘%r’
|
||
respectively and are useful for text included only with the first and
|
||
last suffixes in the list. So for example, the following joins the
|
||
suffixes together as a comma-separated list:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':completion:*:unit-suffixes' format '%x%(r::,)'
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-_005foptions"></span></p>
|
||
<p>_options</p>
|
||
<p>This can be used to complete the names of shell options. It provides a
|
||
matcher specification that ignores a leading ‘no’, ignores underscores
|
||
and allows upper-case letters to match their lower-case counterparts
|
||
(for example, ‘glob’, ‘noglob’, ‘NO_GLOB’ are all completed). Any
|
||
arguments are propagated to the compadd builtin.</p>
|
||
<p><span id="index-_005foptions_005fset"></span> <span
|
||
id="index-_005foptions_005funset"></span></p>
|
||
<p>_options_set and _options_unset</p>
|
||
<p>These functions complete only set or unset options, with the same
|
||
matching specification used in the _options function.</p>
|
||
<p>Note that you need to uncomment a few lines in the _main_complete
|
||
function for these functions to work properly. The lines in question are
|
||
used to store the option settings in effect before the completion widget
|
||
locally sets the options it needs. Hence these functions are not
|
||
generally used by the completion system.</p>
|
||
<p><span id="index-_005fparameters"></span></p>
|
||
<p>_parameters</p>
|
||
<p>This is used to complete the names of shell parameters.</p>
|
||
<p>The option ‘-g <code>pattern</code>’ limits the completion to parameters whose type
|
||
matches the <code>pattern</code>. The type of a parameter is that shown by ‘print
|
||
${(t)<code>param</code>}’, hence judicious use of ‘*’ in <code>pattern</code> is probably
|
||
necessary.</p>
|
||
<p>All other arguments are passed to the compadd builtin.</p>
|
||
<p><span id="index-_005fpath_005ffiles"></span></p>
|
||
<p>_path_files</p>
|
||
<p>This function is used throughout the completion system to complete
|
||
filenames. It allows completion of partial paths. For example, the
|
||
string ‘/u/i/s/sig’ may be completed to ‘/usr/include/sys/signal.h’.</p>
|
||
<p>The options accepted by both _path_files and _files are:</p>
|
||
<p>-f<br />
|
||
Complete all filenames. This is the default.</p>
|
||
<p>-/<br />
|
||
Specifies that only directories should be completed.</p>
|
||
<p>-g <code>pattern</code><br />
|
||
Specifies that only files matching the <code>pattern</code> should be completed.</p>
|
||
<p>-W <code>paths</code><br />
|
||
Specifies path prefixes that are to be prepended to the string from the
|
||
command line to generate the filenames but that should not be inserted
|
||
as completions nor shown in completion listings. Here, <code>paths</code> may be
|
||
the name of an array parameter, a literal list of paths enclosed in
|
||
parentheses or an absolute pathname.</p>
|
||
<p>-F <code>ignored-files</code><br />
|
||
This behaves as for the corresponding option to the compadd builtin. It
|
||
gives direct control over which filenames should be ignored. If the
|
||
option is not present, the ignored-patterns style is used.</p>
|
||
<p>Both _path_files and _files also accept the following options which
|
||
are passed to compadd: ‘-J’, ‘-V’, ‘-1’, ‘-2’, ‘-n’, ‘-X’, ‘-M’, ‘-P’,
|
||
‘-S’, ‘-q’, ‘-r’, and ‘-R’.</p>
|
||
<p>Finally, the _path_files function uses the styles expand, ambiguous,
|
||
special-dirs, list-suffixes and file-sort described above.</p>
|
||
<p><span id="index-_005fpick_005fvariant"></span></p>
|
||
<p>_pick_variant [ -b <code>builtin-label</code> ] [ -c <code>command</code> ] [ -r <code>name</code>
|
||
]</p>
|
||
<p> <code>label</code>=<code>pattern</code> ... <code>label</code> [ <code>arg</code> ... ]</p>
|
||
<p>This function is used to resolve situations where a single command name
|
||
requires more than one type of handling, either because it has more than
|
||
one variant or because there is a name clash between two different
|
||
commands.</p>
|
||
<p>The command to run is taken from the first element of the array words
|
||
unless this is overridden by the option -c. This command is run and its
|
||
output is compared with a series of patterns. Arguments to be passed to
|
||
the command can be specified at the end after all the other arguments.
|
||
The patterns to try in order are given by the arguments
|
||
<code>label</code>=<code>pattern</code>; if the output of ‘<code>command</code> <code>arg</code> ...’ contains
|
||
<code>pattern</code>, then <code>label</code> is selected as the label for the command
|
||
variant. If none of the patterns match, the final command label is
|
||
selected and status 1 is returned.</p>
|
||
<p>If the ‘-b <code>builtin-label</code>’ is given, the command is tested to see if it
|
||
is provided as a shell builtin, possibly autoloaded; if so, the label
|
||
<code>builtin-label</code> is selected as the label for the variant.</p>
|
||
<p>If the ‘-r <code>name</code>’ is given, the <code>label</code> picked is stored in the
|
||
parameter named <code>name</code>.</p>
|
||
<p>The results are also cached in the _cmd_variant associative array
|
||
indexed by the name of the command run.</p>
|
||
<p><span id="index-_005fregex_005farguments"></span></p>
|
||
<p>_regex_arguments <code>name</code> <code>spec</code> ...</p>
|
||
<p>This function generates a completion function <code>name</code> which matches the
|
||
specifications <code>spec</code>s, a set of regular expressions as described below.
|
||
After running _regex_arguments, the function <code>name</code> should be called as
|
||
a normal completion function. The pattern to be matched is given by the
|
||
contents of the words array up to the current cursor position joined
|
||
together with null characters; no quotation is applied.</p>
|
||
<p>The arguments are grouped as sets of alternatives separated by ‘|’,
|
||
which are tried one after the other until one matches. Each alternative
|
||
consists of a one or more specifications which are tried left to right,
|
||
with each pattern matched being stripped in turn from the command line
|
||
being tested, until all of the group succeeds or until one fails; in the
|
||
latter case, the next alternative is tried. This structure can be
|
||
repeated to arbitrary depth by using parentheses; matching proceeds from
|
||
inside to outside.</p>
|
||
<p>A special procedure is applied if no test succeeds but the remaining
|
||
command line string contains no null character (implying the remaining
|
||
word is the one for which completions are to be generated). The
|
||
completion target is restricted to the remaining word and any <code>action</code>s
|
||
for the corresponding patterns are executed. In this case, nothing is
|
||
stripped from the command line string. The order of evaluation of the
|
||
<code>action</code>s can be determined by the tag-order style; the various formats
|
||
supported by _alternative can be used in <code>action</code>. The <code>descr</code> is used
|
||
for setting up the array parameter expl.</p>
|
||
<p>Specification arguments take one of following forms, in which
|
||
metacharacters such as ‘(’, ‘)’, ‘#’ and ‘|’ should be quoted.</p>
|
||
<p>/<code>pattern</code>/ [%<code>lookahead</code>%] [-<code>guard</code>] [:<code>tag</code>:<code>descr</code>:<code>action</code>]<br />
|
||
This is a single primitive component. The function tests whether the
|
||
combined pattern ‘(#b)((#B)<code>pattern</code>)<code>lookahead</code>*’ matches the command
|
||
line string. If so, ‘<code>guard</code>’ is evaluated and its return status is
|
||
examined to determine if the test has succeeded. The <code>pattern</code> string
|
||
‘[]’ is guaranteed never to match. The <code>lookahead</code> is not stripped
|
||
from the command line before the next pattern is examined.</p>
|
||
<p>The argument starting with : is used in the same manner as an argument
|
||
to _alternative.</p>
|
||
<p>A component is used as follows: <code>pattern</code> is tested to see if the
|
||
component already exists on the command line. If it does, any following
|
||
specifications are examined to find something to complete. If a
|
||
component is reached but no such pattern exists yet on the command line,
|
||
the string containing the <code>action</code> is used to generate matches to insert
|
||
at that point.</p>
|
||
<p>/<code>pattern</code>/+ [%<code>lookahead</code>%] [-<code>guard</code>] [:<code>tag</code>:<code>descr</code>:<code>action</code>]<br />
|
||
This is similar to ‘/<code>pattern</code>/ ...’ but the left part of the command
|
||
line string (i.e. the part already matched by previous patterns) is also
|
||
considered part of the completion target.</p>
|
||
<p>/<code>pattern</code>/- [%<code>lookahead</code>%] [-<code>guard</code>] [:<code>tag</code>:<code>descr</code>:<code>action</code>]<br />
|
||
This is similar to ‘/<code>pattern</code>/ ...’ but the <code>action</code>s of the current
|
||
and previously matched patterns are ignored even if the following
|
||
‘<code>pattern</code>’ matches the empty string.</p>
|
||
<p>( <code>spec</code> )<br />
|
||
Parentheses may be used to groups <code>spec</code>s; note each parenthesis is a
|
||
single argument to _regex_arguments.</p>
|
||
<p><code>spec</code> #<br />
|
||
This allows any number of repetitions of <code>spec</code>.</p>
|
||
<p><code>spec</code> <code>spec</code><br />
|
||
The two <code>spec</code>s are to be matched one after the other as described
|
||
above.</p>
|
||
<p><code>spec</code> | <code>spec</code><br />
|
||
Either of the two <code>spec</code>s can be matched.</p>
|
||
<p>The function _regex_words can be used as a helper function to generate
|
||
matches for a set of alternative words possibly with their own arguments
|
||
as a command line argument.</p>
|
||
<p>Examples:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_regex_arguments _tst /$'[^\0]#\0'/ \
|
||
/$'[^\0]#\0'/ :'compadd aaa'
|
||
</code></pre>
|
||
</div>
|
||
<p>This generates a function _tst that completes aaa as its only argument.
|
||
The <code>tag</code> and <code>description</code> for the action have been omitted for brevity
|
||
(this works but is not recommended in normal use). The first component
|
||
matches the command word, which is arbitrary; the second matches any
|
||
argument. As the argument is also arbitrary, any following component
|
||
would not depend on aaa being present.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_regex_arguments _tst /$'[^\0]#\0'/ \
|
||
/$'aaa\0'/ :'compadd aaa'
|
||
</code></pre>
|
||
</div>
|
||
<p>This is a more typical use; it is similar, but any following patterns
|
||
would only match if aaa was present as the first argument.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_regex_arguments _tst /$'[^\0]#\0'/ \( \
|
||
/$'aaa\0'/ :'compadd aaa' \
|
||
/$'bbb\0'/ :'compadd bbb' \) \#
|
||
</code></pre>
|
||
</div>
|
||
<p>In this example, an indefinite number of command arguments may be
|
||
completed. Odd arguments are completed as aaa and even arguments as bbb.
|
||
Completion fails unless the set of aaa and bbb arguments before the
|
||
current one is matched correctly.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_regex_arguments _tst /$'[^\0]#\0'/ \
|
||
\( /$'aaa\0'/ :'compadd aaa' \| \
|
||
/$'bbb\0'/ :'compadd bbb' \) \#
|
||
</code></pre>
|
||
</div>
|
||
<p>This is similar, but either aaa or bbb may be completed for any
|
||
argument. In this case _regex_words could be used to generate</p>
|
||
<p><span id="index-_005fregex_005fwords-_005b-_002dt-term-_005d"></span></p>
|
||
<p>_regex_words <code>tag</code> <code>description</code> <code>spec</code> ...</p>
|
||
<p>This function can be used to generate arguments for the
|
||
_regex_arguments command which may be inserted at any point where a set
|
||
of rules is expected. The <code>tag</code> and <code>description</code> give a standard tag
|
||
and description pertaining to the current context. Each <code>spec</code> contains
|
||
two or three arguments separated by a colon: note that there is no
|
||
leading colon in this case.</p>
|
||
<p>Each <code>spec</code> gives one of a set of words that may be completed at this
|
||
point, together with arguments. It is thus roughly equivalent to the
|
||
_arguments function when used in normal (non-regex) completion.</p>
|
||
<p>The part of the <code>spec</code> before the first colon is the word to be
|
||
completed. This may contain a *; the entire word, before and after the
|
||
* is completed, but only the text before the * is required for the
|
||
context to be matched, so that further arguments may be completed after
|
||
the abbreviated form.</p>
|
||
<p>The second part of <code>spec</code> is a description for the word being completed.</p>
|
||
<p>The optional third part of the <code>spec</code> describes how words following the
|
||
one being completed are themselves to be completed. It will be evaluated
|
||
in order to avoid problems with quoting. This means that typically it
|
||
contains a reference to an array containing previously generated regex
|
||
arguments.</p>
|
||
<p>The option -t <code>term</code> specifies a terminator for the word instead of the
|
||
usual space. This is handled as an auto-removable suffix in the manner
|
||
of the option -s <code>sep</code> to _values.</p>
|
||
<p>The result of the processing by _regex_words is placed in the array
|
||
reply, which should be made local to the calling function. If the set of
|
||
words and arguments may be matched repeatedly, a # should be appended to
|
||
the generated array at that point.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local -a reply
|
||
_regex_words mydb-commands 'mydb commands' \
|
||
'add:add an entry to mydb:$mydb_add_cmds' \
|
||
'show:show entries in mydb'
|
||
_regex_arguments _mydb "$reply[@]"
|
||
_mydb "$@"
|
||
</code></pre>
|
||
</div>
|
||
<p>This shows a completion function for a command mydb which takes two
|
||
command arguments, add and show. show takes no arguments, while the
|
||
arguments for add have already been prepared in an array mydb_add_cmds,
|
||
quite possibly by a previous call to _regex_words.</p>
|
||
<p><span id="index-_005frequested"></span></p>
|
||
<p>_requested [ -x ] [ -12VJ ] <code>tag</code> [ <code>name</code> <code>descr</code> [ <code>command</code> [
|
||
<code>arg</code> ... ] ]</p>
|
||
<p>This function is called to decide whether a tag already registered by a
|
||
call to _tags (see below) has been requested by the user and hence
|
||
completion should be performed for it. It returns status zero if the tag
|
||
is requested and non-zero otherwise. The function is typically used as
|
||
part of a loop over different tags as follows:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_tags foo bar baz
|
||
while _tags; do
|
||
if _requested foo; then
|
||
... # perform completion for foo
|
||
fi
|
||
... # test the tags bar and baz in the same way
|
||
... # exit loop if matches were generated
|
||
done
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that the test for whether matches were generated is not performed
|
||
until the end of the _tags loop. This is so that the user can set the
|
||
tag-order style to specify a set of tags to be completed at the same
|
||
time.</p>
|
||
<p>If <code>name</code> and <code>descr</code> are given, _requested calls the _description
|
||
function with these arguments together with the options passed to
|
||
_requested.</p>
|
||
<p>If <code>command</code> is given, the _all_labels function will be called
|
||
immediately with the same arguments. In simple cases this makes it
|
||
possible to perform the test for the tag and the matching in one go. For
|
||
example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local expl ret=1
|
||
_tags foo bar baz
|
||
while _tags; do
|
||
_requested foo expl 'description' \
|
||
compadd foobar foobaz && ret=0
|
||
...
|
||
(( ret )) || break
|
||
done
|
||
</code></pre>
|
||
</div>
|
||
<p>If the <code>command</code> is not compadd, it must nevertheless be prepared to
|
||
handle the same options.</p>
|
||
<p><span id="index-_005fretrieve_005fcache"></span></p>
|
||
<p>_retrieve_cache <code>cache_identifier</code></p>
|
||
<p>This function retrieves completion information from the file given by
|
||
<code>cache_identifier</code>, stored in a directory specified by the cache-path
|
||
style which defaults to ~/.zcompcache. The return status is zero if
|
||
retrieval was successful. It will only attempt retrieval if the
|
||
use-cache style is set, so you can call this function without worrying
|
||
about whether the user wanted to use the caching layer.</p>
|
||
<p>See _store_cache below for more details.</p>
|
||
<p><span id="index-_005fsep_005fparts"></span></p>
|
||
<p>_sep_parts</p>
|
||
<p>This function is passed alternating arrays and separators as arguments.
|
||
The arrays specify completions for parts of strings to be separated by
|
||
the separators. The arrays may be the names of array parameters or a
|
||
quoted list of words in parentheses. For example, with the array
|
||
‘hosts=(ftp news)’ the call ‘_sep_parts ’(foo bar)’ @ hosts’ will
|
||
complete the string ‘f’ to ‘foo’ and the string ‘b@n’ to ‘bar@news’.</p>
|
||
<p>This function accepts the compadd options ‘-V’, ‘-J’, ‘-1’, ‘-2’, ‘-n’,
|
||
‘-X’, ‘-M’, ‘-P’, ‘-S’, ‘-r’, ‘-R’, and ‘-q’ and passes them on to the
|
||
compadd builtin used to add the matches.</p>
|
||
<p><span id="index-_005fsequence"></span></p>
|
||
<p>_sequence [ -s <code>sep</code> ] [ -n <code>max</code> ] [ -d ] <code>function</code> [ - ] ...</p>
|
||
<p>This function is a wrapper to other functions for completing items in a
|
||
separated list. The same function is used to complete each item in the
|
||
list. The separator is specified with the -s option. If -s is omitted it
|
||
will use ‘,’. Duplicate values are not matched unless -d is specified.
|
||
If there is a fixed or maximum number of items in the list, this can be
|
||
specified with the -n option.</p>
|
||
<p>Common compadd options are passed on to the function. It is possible to
|
||
use compadd directly with _sequence, though _values may be more
|
||
appropriate in this situation.</p>
|
||
<p><span id="index-_005fsetup"></span></p>
|
||
<p>_setup <code>tag</code> [ <code>group</code> ]</p>
|
||
<p>This function sets up the special parameters used by the completion
|
||
system appropriately for the <code>tag</code> given as the first argument. It uses
|
||
the styles list-colors, list-packed, list-rows-first, last-prompt,
|
||
accept-exact, menu and force-list.</p>
|
||
<p>The optional <code>group</code> supplies the name of the group in which the matches
|
||
will be placed. If it is not given, the <code>tag</code> is used as the group name.</p>
|
||
<p>This function is called automatically from _description and hence is
|
||
not normally called explicitly.</p>
|
||
<p><span id="index-_005fstore_005fcache"></span></p>
|
||
<p>_store_cache <code>cache_identifier</code> <code>param</code> ...</p>
|
||
<p>This function, together with _retrieve_cache and _cache_invalid,
|
||
implements a caching layer which can be used in any completion function.
|
||
Data obtained by costly operations are stored in parameters; this
|
||
function then dumps the values of those parameters to a file. The data
|
||
can then be retrieved quickly from that file via _retrieve_cache, even
|
||
in different instances of the shell.</p>
|
||
<p>The <code>cache_identifier</code> specifies the file which the data should be
|
||
dumped to. The file is stored in a directory specified by the cache-path
|
||
style which defaults to ~/.zcompcache. The remaining <code>param</code>s arguments
|
||
are the parameters to dump to the file.</p>
|
||
<p>The return status is zero if storage was successful. The function will
|
||
only attempt storage if the use-cache style is set, so you can call this
|
||
function without worrying about whether the user wanted to use the
|
||
caching layer.</p>
|
||
<p>The completion function may avoid calling _retrieve_cache when it
|
||
already has the completion data available as parameters. However, in
|
||
that case it should call _cache_invalid to check whether the data in
|
||
the parameters and in the cache are still valid.</p>
|
||
<p>See the _perl_modules completion function for a simple example of the
|
||
usage of the caching layer.</p>
|
||
<p><span id="index-_005ftags"></span></p>
|
||
<p>_tags [ [ -C <code>name</code> ] <code>tag</code> ... ]</p>
|
||
<p>If called with arguments, these are taken to be the names of tags valid
|
||
for completions in the current context. These tags are stored internally
|
||
and sorted by using the tag-order style.</p>
|
||
<p>Next, _tags is called repeatedly without arguments from the same
|
||
completion function. This successively selects the first, second, etc.
|
||
set of tags requested by the user. The return status is zero if at least
|
||
one of the tags is requested and non-zero otherwise. To test if a
|
||
particular tag is to be tried, the _requested function should be called
|
||
(see above).</p>
|
||
<p>If ‘-C <code>name</code>’ is given, <code>name</code> is temporarily stored in the <code>argument</code>
|
||
field (the fifth) of the context in the curcontext parameter during the
|
||
call to _tags; the field is restored on exit. This allows _tags to use
|
||
a more specific context without having to change and reset the
|
||
curcontext parameter (which has the same effect).</p>
|
||
<p><span id="index-_005ftilde_005ffiles"></span></p>
|
||
<p>_tilde_files</p>
|
||
<p>Like _files, but resolve leading tildes according to the rules of
|
||
filename expansion, so the suggested completions don’t start with a ‘~’
|
||
even if the filename on the command-line does.</p>
|
||
<p><span id="index-_005fvalues"></span></p>
|
||
<p>_values [ -O <code>name</code> ] [ -s <code>sep</code> ] [ -S <code>sep</code> ] [ -wC ] <code>desc</code>
|
||
<code>spec</code> ...</p>
|
||
<p>This is used to complete arbitrary keywords (values) and their
|
||
arguments, or lists of such combinations.</p>
|
||
<p>If the first argument is the option ‘-O <code>name</code>’, it will be used in the
|
||
same way as by the _arguments function. In other words, the elements of
|
||
the <code>name</code> array will be passed to compadd when executing an action.</p>
|
||
<p>If the first argument (or the first argument after ‘-O <code>name</code>’) is ‘-s’,
|
||
the next argument is used as the character that separates multiple
|
||
values. This character is automatically added after each value in an
|
||
auto-removable fashion (see below); all values completed by ‘_values
|
||
-s’ appear in the same word on the command line, unlike completion using
|
||
_arguments. If this option is not present, only a single value will be
|
||
completed per word.</p>
|
||
<p>Normally, _values will only use the current word to determine which
|
||
values are already present on the command line and hence are not to be
|
||
completed again. If the -w option is given, other arguments are examined
|
||
as well.</p>
|
||
<p>The first non-option argument, <code>desc</code>, is used as a string to print as a
|
||
description before listing the values.</p>
|
||
<p>All other arguments describe the possible values and their arguments in
|
||
the same format used for the description of options by the _arguments
|
||
function (see above). The only differences are that no minus or plus
|
||
sign is required at the beginning, values can have only one argument,
|
||
and the forms of action beginning with an equal sign are not supported.</p>
|
||
<p>The character separating a value from its argument can be set using the
|
||
option -S (like -s, followed by the character to use as the separator in
|
||
the next argument). By default the equals sign will be used as the
|
||
separator between values and arguments.</p>
|
||
<p>Example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">_values -s , 'description' \
|
||
'*foo[bar]' \
|
||
'(two)*one[number]:first count:' \
|
||
'two[another number]::second count:(1 2 3)'
|
||
</code></pre>
|
||
</div>
|
||
<p>This describes three possible values: ‘foo’, ‘one’, and ‘two’. The first
|
||
is described as ‘bar’, takes no argument and may appear more than once.
|
||
The second is described as ‘number’, may appear more than once, and
|
||
takes one mandatory argument described as ‘first count’; no action is
|
||
specified, so it will not be completed. The ‘(two)’ at the beginning
|
||
says that if the value ‘one’ is on the line, the value ‘two’ will no
|
||
longer be considered a possible completion. Finally, the last value
|
||
(‘two’) is described as ‘another number’ and takes an optional argument
|
||
described as ‘second count’ for which the completions (to appear after
|
||
an ‘=’) are ‘1’, ‘2’, and ‘3’. The _values function will complete lists
|
||
of these values separated by commas.</p>
|
||
<p>Like _arguments, this function temporarily adds another context name
|
||
component to the arguments element (the fifth) of the current context
|
||
while executing the <code>action</code>. Here this name is just the name of the
|
||
value for which the argument is completed.</p>
|
||
<p>The style verbose is used to decide if the descriptions for the values
|
||
(but not those for the arguments) should be printed.</p>
|
||
<p>The associative array val_args is used to report values and their
|
||
arguments; this works similarly to the opt_args associative array used
|
||
by _arguments. Hence the function calling _values should declare the
|
||
local parameters state, state_descr, line, context and val_args:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local context state state_descr line
|
||
typeset -A val_args
|
||
</code></pre>
|
||
</div>
|
||
<p>when using an action of the form ‘-><code>string</code>’. With this function the
|
||
context parameter will be set to the name of the value whose argument is
|
||
to be completed. Note that for _values, the state and state_descr are
|
||
scalars rather than arrays. Only a single matching state is returned.</p>
|
||
<p>Note also that _values normally adds the character used as the
|
||
separator between values as an auto-removable suffix (similar to a ‘/’
|
||
after a directory). However, this is not possible for a ‘-><code>string</code>’
|
||
action as the matches for the argument are generated by the calling
|
||
function. To get the usual behaviour, the calling function can add the
|
||
separator <code>x</code> as a suffix by passing the options ‘-qS <code>x</code>’ either
|
||
directly or indirectly to compadd.</p>
|
||
<p>The option -C is treated in the same way as it is by _arguments. In
|
||
that case the parameter curcontext should be made local instead of
|
||
context (as described above).</p>
|
||
<p><span id="index-_005fwanted"></span></p>
|
||
<p>_wanted [ -x ] [ -C <code>name</code> ] [ -12VJ ] <code>tag</code> <code>name</code> <code>descr</code>
|
||
<code>command</code> [ <code>arg</code> ...]</p>
|
||
<p>In many contexts, completion can only generate one particular set of
|
||
matches, usually corresponding to a single tag. However, it is still
|
||
necessary to decide whether the user requires matches of this type. This
|
||
function is useful in such a case.</p>
|
||
<p>The arguments to _wanted are the same as those to _requested, i.e.
|
||
arguments to be passed to _description. However, in this case the
|
||
<code>command</code> is not optional; all the processing of tags, including the
|
||
loop over both tags and tag labels and the generation of matches, is
|
||
carried out automatically by _wanted.</p>
|
||
<p>Hence to offer only one tag and immediately add the corresponding
|
||
matches with the given description:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">local expl
|
||
_wanted tag expl 'description' \
|
||
compadd -- match1 match2...
|
||
</code></pre>
|
||
</div>
|
||
<p>See also the use of _wanted in the example function in <a href="Expansion.html#Dynamic-named-directories">Dynamic named
|
||
directories</a>.</p>
|
||
<p>Note that, as for _requested, the <code>command</code> must be able to accept
|
||
options to be passed down to compadd.</p>
|
||
<p>Like _tags this function supports the -C option to give a different
|
||
name for the argument context field. The -x option has the same meaning
|
||
as for _description.</p>
|
||
<p><span id="index-_005fwidgets"></span></p>
|
||
<p>_widgets [ -g <code>pattern</code> ]</p>
|
||
<p>This function completes names of zle widgets (see <a href="Zsh-Line-Editor.html#Zle-Widgets">Zle
|
||
Widgets</a>). The <code>pattern</code>, if present,
|
||
is matched against values of the $widgets special parameter, documented
|
||
in <a href="Zsh-Modules.html#The-zsh_002fzleparameter-Module">The zsh/zleparameter
|
||
Module</a>.</p>
|
||
<hr />
|
||
<p><span id="Completion-System-Variables"></span> <span
|
||
id="Completion-System-Variables-1"></span></p>
|
||
<h2 id="207-completion-system-variables"><a class="header" href="#207-completion-system-variables">20.7 Completion System Variables</a></h2>
|
||
<p><span id="index-completion-system_002c-variables"></span></p>
|
||
<p>There are some standard variables, initialised by the _main_complete
|
||
function and then used from other functions.</p>
|
||
<p>The standard variables are:</p>
|
||
<p>_comp_caller_options<br />
|
||
The completion system uses setopt to set a number of options. This
|
||
allows functions to be written without concern for compatibility with
|
||
every possible combination of user options. However, sometimes
|
||
completion needs to know what the user’s option preferences are. These
|
||
are saved in the _comp_caller_options associative array. Option names,
|
||
spelled in lowercase without underscores, are mapped to one or other of
|
||
the strings ‘on’ and ‘off’.</p>
|
||
<p>_comp_priv_prefix<br />
|
||
Completion functions such as _sudo can set the _comp_priv_prefix array
|
||
to a command prefix that may then be used by _call_program to match the
|
||
privileges when calling programs to generate matches.</p>
|
||
<p><span id="index-compprefuncs_002c-use-of"></span> <span
|
||
id="index-comppostfuncs_002c-use-of"></span></p>
|
||
<p>Two more features are offered by the _main_complete function. The
|
||
arrays compprefuncs and comppostfuncs may contain names of functions
|
||
that are to be called immediately before or after completion has been
|
||
tried. A function will only be called once unless it explicitly
|
||
reinserts itself into the array.</p>
|
||
<hr />
|
||
<p><span id="Completion-Directories"></span> <span
|
||
id="Completion-Directories-1"></span></p>
|
||
<h2 id="208-completion-directories"><a class="header" href="#208-completion-directories">20.8 Completion Directories</a></h2>
|
||
<p><span id="index-completion-system_002c-directory-structure"></span></p>
|
||
<p>In the source distribution, the files are contained in various
|
||
subdirectories of the Completion directory. They may have been installed
|
||
in the same structure, or into one single function directory. The
|
||
following is a description of the files found in the original directory
|
||
structure. If you wish to alter an installed file, you will need to copy
|
||
it to some directory which appears earlier in your fpath than the
|
||
standard directory where it appears.</p>
|
||
<p>Base<br />
|
||
The core functions and special completion widgets automatically bound to
|
||
keys. You will certainly need most of these, though will probably not
|
||
need to alter them. Many of these are documented above.</p>
|
||
<p>Zsh<br />
|
||
Functions for completing arguments of shell builtin commands and utility
|
||
functions for this. Some of these are also used by functions from the
|
||
Unix directory.</p>
|
||
<p>Unix<br />
|
||
Functions for completing arguments of external commands and suites of
|
||
commands. They may need modifying for your system, although in many
|
||
cases some attempt is made to decide which version of a command is
|
||
present. For example, completion for the mount command tries to
|
||
determine the system it is running on, while completion for many other
|
||
utilities try to decide whether the GNU version of the command is in
|
||
use, and hence whether the --help option is supported.</p>
|
||
<p>X, AIX, BSD, ...<br />
|
||
Completion and utility function for commands available only on some
|
||
systems. These are not arranged hierarchically, so, for example, both
|
||
the Linux and Debian directories, as well as the X directory, may be
|
||
useful on your system.</p>
|
||
<hr />
|
||
<p>This document was generated on <em>May 14, 2022</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html
|
||
5.0</em></a>.<br />
|
||
Zsh version 5.9, released on May 14, 2022.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="Completion-Widgets.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="Completion-Using-compctl.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="Completion-Widgets.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="Completion-Using-compctl.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">
|
||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
||
const socket = new WebSocket(wsAddress);
|
||
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>
|