4909 lines
291 KiB
HTML
4909 lines
291 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 -->
|
||
|
||
|
||
|
||
</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-_0026-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>
|
||
</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" name="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-3"></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 <code>compsys</code>. 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 <code>ls</code>
|
||
command the user may prefer to try <code>files</code> before <code>directories</code>, 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 <code>zstyle</code> 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
|
||
<code>how</code> 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 <code>_main_complete</code> 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 ‘<code>comp</code>’ are to be called directly; there are only a
|
||
few of these;</li>
|
||
<li>those beginning ‘<code>_</code>’ 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 <code>compinit</code> from your initialization file; see the next
|
||
section. However, the function <code>compinstall</code> can be run by a user to
|
||
configure various aspects of the completion system.</p>
|
||
<p>Usually, <code>compinstall</code> will insert code into <code>.zshrc</code>, although if
|
||
file’s location. Note that it is up to you to make sure that the lines
|
||
added to <code>.zshrc</code> are actually run; you may, for example, need to move
|
||
them to an earlier place in the file if <code>.zshrc</code> usually returns early.
|
||
So long as you keep them all together (including the comment lines at
|
||
the start and finish), you can rerun <code>compinstall</code> 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 <code>compinstall</code>,
|
||
although lines using the command ‘<code>zstyle</code>’ should be gracefully
|
||
handled.</p>
|
||
<p>The new code will take effect next time you start the shell, or run
|
||
<code>.zshrc</code> by hand; there is also an option to make them take effect
|
||
immediately. However, if <code>compinstall</code> has removed definitions, you will
|
||
need to restart the shell to see the changes.</p>
|
||
<p>To run <code>compinstall</code> you will need to make sure it is in a directory
|
||
mentioned in your <code>fpath</code> 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 <code>fpath</code>. Then it must be autoloaded
|
||
(‘<code>autoload -U compinstall</code>’ is recommended). You can abort the
|
||
installation any time you are being prompted for information, and your
|
||
<code>.zshrc</code> 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 <code>compinit</code> to initialize completion
|
||
for the current session when called directly; if you have run
|
||
<code>compinstall</code> it will be called automatically from your <code>.zshrc</code>.</p>
|
||
<p>To initialize the system, the function <code>compinit</code> should be in a
|
||
directory mentioned in the <code>fpath</code> parameter, and should be autoloaded
|
||
(‘<code>autoload -U compinit</code>’ is recommended), and then run simply as
|
||
‘<code>compinit</code>’. 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 <code>menu-select</code> widget, which is part of the <code>zsh/complist</code>
|
||
module, you should make sure that that module is loaded before the call
|
||
to <code>compinit</code> 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 <code>expand-or-complete</code>, <code>compinit</code>
|
||
will rebind it to <code>complete-word</code>; 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 ‘<code>.</code>’ in front of the widget
|
||
name, e.g. ‘<code>.expand-or-complete</code>’.</p>
|
||
<p>To speed up the running of <code>compinit</code>, 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 <code>compinit</code> with the option
|
||
<code>-D</code>. The dumped file is <code>.zcompdump</code> in the same directory as the
|
||
startup files (i.e. <code>$ZDOTDIR</code> or <code>$HOME</code>); alternatively, an explicit
|
||
file name can be given by ‘<code>compinit -d</code> <code>dumpfile</code>’. The next
|
||
invocation of <code>compinit</code> will read the dumped file instead of performing
|
||
a full initialization.</p>
|
||
<p>If the number of completion files changes, <code>compinit</code> 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 <code>#compdef</code> function (as described
|
||
below) change, it is easiest to delete the dump file by hand so that
|
||
<code>compinit</code> 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 <code>-C</code>. 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, <code>compdump</code>, but you
|
||
will only need to run this yourself if you change the configuration
|
||
(e.g. using <code>compdef</code>) 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 <code>_compdir</code> is set, <code>compinit</code> 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 <code>compinit</code> 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,
|
||
<code>compinit</code> 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 <code>-u</code>, and to make <code>compinit</code> silently ignore all insecure
|
||
files and directories use the option <code>-i</code>. This security check is
|
||
skipped entirely when the <code>-C</code> option is given.</p>
|
||
<p><span id="index-compaudit"></span></p>
|
||
<p>The security check can be retried at any time by running the function
|
||
<code>compaudit</code>. This is the same check used by <code>compinit</code>, but when it is
|
||
executed directly any changes to <code>fpath</code> 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, <code>compaudit</code> uses <code>fpath</code> and <code>_compdir</code> to
|
||
find completion system directories, adding missing ones to <code>fpath</code> as
|
||
necessary. To force a check of exactly the directories currently named
|
||
in <code>fpath</code>, set <code>_compdir</code> to an empty string before calling <code>compaudit</code>
|
||
or <code>compinit</code>.</p>
|
||
<p><span id="index-bashcompinit"></span></p>
|
||
<p>The function <code>bashcompinit</code> provides compatibility with bash’s
|
||
programmable completion system. When run it will define the functions,
|
||
<code>compgen</code> and <code>complete</code> 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 <code>fpath/FPATH</code>
|
||
parameter must contain the directory in which they are stored. If <code>zsh</code>
|
||
was properly installed on your system, then <code>fpath/FPATH</code> automatically
|
||
contains the required directories for the standard functions.</p>
|
||
<p>For incomplete installations, if <code>compinit</code> 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 <code>_compdir</code> to the search
|
||
path. If that directory has a subdirectory named <code>Base</code>, all
|
||
subdirectories will be added to the path. Furthermore, if the
|
||
subdirectory <code>Base</code> has a subdirectory named <code>Core</code>, <code>compinit</code> will add
|
||
all subdirectories of the subdirectories to the path: this allows the
|
||
functions to be in the same format as in the <code>zsh</code> source distribution.</p>
|
||
<p><span id="index-compdef_002c-use-of-by-compinit"></span></p>
|
||
<p>When <code>compinit</code> is run, it searches all such files accessible via
|
||
<code>fpath/FPATH</code> 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>
|
||
<ul>
|
||
<li>
|
||
<p><code>#compdef</code> <code>name</code> ... [ <code>-</code>{<code>p</code>|<code>P</code>} <code>pattern</code> ... [ <code>-N</code> <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``=``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 <code>$service</code> 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 <code>#compdef</code> line contains one of the options <code>-p</code> or <code>-P</code>, 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 <code>-p</code> and <code>-P</code> are used to
|
||
specify patterns to be tried before or after other completions
|
||
respectively. Hence <code>-P</code> may be used to specify default actions.</p>
|
||
<p>The option <code>-N</code> is used after a list following <code>-p</code> or <code>-P</code>; it
|
||
specifies that remaining words no longer define patterns. It is
|
||
possible to toggle between the three options as many times as
|
||
necessary.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>#compdef -k</code> <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 <code>complete-word</code>, <code>delete-char-or-list</code>, <code>expand-or-complete</code>,
|
||
<code>expand-or-complete-prefix</code>, <code>list-choices</code>, <code>menu-complete</code>,
|
||
<code>menu-expand-or-complete</code>, or <code>reverse-menu-complete</code>. If the
|
||
<code>zsh/complist</code> module is loaded (see <a href="Zsh-Modules.html#The-zsh_002fcomplist-Module">The zsh/complist
|
||
Module</a>) the widget
|
||
<code>menu-select</code> 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 <code>undefined-key</code>). The widget created has the same name as the
|
||
file and can be bound to any other keys using <code>bindkey</code> as usual.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>#compdef -K</code> <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 <code>-k</code> 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 ‘<code>_</code>’ 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-example">#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 <code>_foo_complete</code> for completion,
|
||
bound to ‘<code>^X^C</code>’, and a widget <code>_foo_list</code> for listing, bound to
|
||
‘<code>^X^D</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>#autoload</code> [ <code>options</code> ]<br />
|
||
Functions with the <code>#autoload</code> 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 <code>autoload</code> builtin; a typical use is <code>+X</code> to
|
||
force the function to be loaded immediately. Note that the <code>-U</code> and
|
||
<code>-z</code> flags are always added implicitly.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The <code>#</code> is part of the tag name and no white space is allowed after it.
|
||
The <code>#compdef</code> tags use the <code>compdef</code> 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><code>-array-value-</code></p>
|
||
<p>The right hand side of an array-assignment (‘<code>name``=(``...``)</code>’)</p>
|
||
<p><span id="index-_002dbrace_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p><code>-brace-parameter-</code></p>
|
||
<p>The name of a parameter expansion within braces (‘<code>${``...``}</code>’)</p>
|
||
<p><span id="index-_002dassign_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p><code>-assign-parameter-</code></p>
|
||
<p>The name of a parameter in an assignment, i.e. on the left hand side of
|
||
an ‘<code>=</code>’</p>
|
||
<p><span id="index-_002dcommand_002d_002c-completion-context"></span></p>
|
||
<p><code>-command-</code></p>
|
||
<p>A word in command position</p>
|
||
<p><span id="index-_002dcondition_002d_002c-completion-context"></span></p>
|
||
<p><code>-condition-</code></p>
|
||
<p>A word inside a condition (‘<code>[[``...``]]</code>’)</p>
|
||
<p><span id="index-_002ddefault_002d_002c-completion-context"></span></p>
|
||
<p><code>-default-</code></p>
|
||
<p>Any word for which no other completion is defined</p>
|
||
<p><span id="index-_002dequal_002d_002c-completion-context"></span></p>
|
||
<p><code>-equal-</code></p>
|
||
<p>A word beginning with an equals sign</p>
|
||
<p><span id="index-_002dfirst_002d_002c-completion-context"></span></p>
|
||
<p><code>-first-</code></p>
|
||
<p>This is tried before any other completion function. The function called
|
||
may set the <code>_compskip</code> parameter to one of various values: <code>all</code>: no
|
||
further completion is attempted; a string containing the substring
|
||
<code>patterns</code>: no pattern completion functions will be called; a string
|
||
containing <code>default</code>: the function for the ‘<code>-default-</code>’ 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><code>-math-</code></p>
|
||
<p>Inside mathematical contexts, such as ‘<code>((``...``))</code>’</p>
|
||
<p><span id="index-_002dparameter_002d_002c-completion-context"></span></p>
|
||
<p><code>-parameter-</code></p>
|
||
<p>The name of a parameter expansion (‘<code>$``...</code>’)</p>
|
||
<p><span id="index-_002dredirect_002d_002c-completion-context"></span></p>
|
||
<p><code>-redirect-</code></p>
|
||
<p>The word after a redirection operator.</p>
|
||
<p><span id="index-_002dsubscript_002d_002c-completion-context"></span></p>
|
||
<p><code>-subscript-</code></p>
|
||
<p>The contents of a parameter subscript.</p>
|
||
<p><span id="index-_002dtilde_002d_002c-completion-context"></span></p>
|
||
<p><code>-tilde-</code></p>
|
||
<p>After an initial tilde (‘<code>~</code>’), but before the first slash in the word.</p>
|
||
<p><span id="index-_002dvalue_002d_002c-completion-context"></span></p>
|
||
<p><code>-value-</code></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 ‘<code>-tilde-</code>’ and the
|
||
function ‘<code>_tilde</code>’).</p>
|
||
<p>The contexts <code>-redirect-</code> and <code>-value-</code> allow extra context-specific
|
||
information. (Internally, this is handled by the functions for each
|
||
context calling the function <code>_dispatch</code>.) The extra information is
|
||
added separated by commas.</p>
|
||
<p>For the <code>-redirect-</code> context, the extra information is in the form
|
||
‘<code>-redirect-,``op``,``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 <code>-value-</code> context, the form is ‘<code>-value-,``name``,``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
|
||
‘<code>assoc=(key <TAB></code>’, <code>name</code> is expanded to ‘<code>name``-``key</code>’. In certain
|
||
special contexts, such as completing after ‘<code>make CFLAGS=</code>’, the
|
||
<code>command</code> part gives the name of the command, here <code>make</code>; 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 ‘<code>-default-</code>’. For example, when completing
|
||
after ‘<code>foo=<TAB></code>’, <code>_value</code> will try the names ‘<code>-value-,foo,</code>’ (note
|
||
the empty <code>command</code> part), ‘<code>-value-,foo,-default-</code>’
|
||
and‘<code>-value-,-default-,-default-</code>’, 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-example">compdef '_files -g "*.log"' '-redirect-,2>,-default-'
|
||
</code></pre>
|
||
</div>
|
||
<p>completes files matching ‘<code>*.log</code>’ after ‘<code>2> <TAB></code>’ for any command
|
||
with no more specific handler defined.</p>
|
||
<p>Also:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compdef _foo -value-,-default-,-default-
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that <code>_foo</code> provides completions for the values of parameters
|
||
for which no special function has been defined. This is usually handled
|
||
by the function <code>_value</code> 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-example">zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'
|
||
</code></pre>
|
||
</div>
|
||
<p>is another way to make completion after ‘<code>2> <TAB></code>’ complete files
|
||
matching ‘<code>*.log</code>’.</p>
|
||
<hr />
|
||
<p><span id="Functions-4"></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 <code>compinit</code> and may be called
|
||
directly.</p>
|
||
<p><span id="index-compdef"></span>
|
||
<span id="index-completion-system_002c-adding-definitions"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>compdef</code> [ <code>-ane</code> ] <code>function name</code> ... [ <code>-</code>{<code>p</code>|<code>P</code>} <code>pattern</code>
|
||
... [ <code>-N</code> <code>name</code> ...]]<br />
|
||
<code>compdef -d</code> <code>name</code> ...<br />
|
||
<code>compdef -k</code> [ <code>-an</code> ] <code>function style key-sequence</code> [
|
||
<code>key-sequence</code> ... ]<br />
|
||
<code>compdef -K</code> [ <code>-an</code> ] <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 <code>#compdef</code> tag above.</p>
|
||
<p>Alternatively, all the arguments may have the form
|
||
‘<code>cmd``=``service</code>’. Here <code>service</code> should already have been
|
||
defined by ‘<code>cmd1``=``service</code>’ lines in <code>#compdef</code> 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 <code>-e</code> 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 <code>eval</code>
|
||
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 ‘<code>.h</code>’ as arguments to the command <code>foo</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compdef '_files -g "*.h"' foo
|
||
</code></pre>
|
||
</div>
|
||
<p>The option <code>-n</code> prevents any completions already defined for the
|
||
command or context from being overwritten.</p>
|
||
<p>The option <code>-d</code> deletes any completion defined for the command or
|
||
contexts listed.</p>
|
||
<p>The <code>name</code>s may also contain <code>-p</code>, <code>-P</code> and <code>-N</code> options as
|
||
described for the <code>#compdef</code> 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 <code>$_compskip</code> may be set by any function defined for a
|
||
pattern context. If it is set to a value containing the substring
|
||
‘<code>patterns</code>’ none of the pattern-functions will be called; if it
|
||
is set to a value containing the substring ‘<code>all</code>’, no other
|
||
function will be called. Setting <code>$_compskip</code> in this manner is of
|
||
particular utility when using the <code>-p</code> 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 <code>-k</code> 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 <code>#compdef -k</code> 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: <code>complete-word</code>, <code>delete-char-or-list</code>,
|
||
<code>expand-or-complete</code>, <code>expand-or-complete-prefix</code>, <code>list-choices</code>,
|
||
<code>menu-complete</code>, <code>menu-expand-or-complete</code>, and
|
||
<code>reverse-menu-complete</code>, as well as <code>menu-select</code> if the
|
||
<code>zsh/complist</code> module is loaded. The option <code>-n</code> prevents the key
|
||
being bound if it is already to bound to something other than
|
||
<code>undefined-key</code>.</p>
|
||
<p>The form with <code>-K</code> 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 <code>-k</code> and the first must be a unique widget name beginning
|
||
with an underscore.</p>
|
||
<p>Wherever applicable, the <code>-a</code> option makes the <code>function</code>
|
||
autoloadable, equivalent to <code> autoload -U ``function</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The function <code>compdef</code> can be used to associate existing completion
|
||
functions with new commands. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compdef _pids foo
|
||
</code></pre>
|
||
</div>
|
||
<p>uses the function <code>_pids</code> to complete process IDs for the command <code>foo</code>.</p>
|
||
<p>Note also the <code>_gnu_generic</code> function described below, which can be used
|
||
to complete options for commands that understand the ‘<code>-``-help</code>’
|
||
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-1"></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 ‘<code>grep</code>’ or
|
||
‘<code>zsh</code>’) and options to which the current word may be an argument
|
||
(such as the ‘<code>-o</code>’ option to <code>zsh</code> 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 <code>zstyle</code> 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
|
||
<code>:completion:``function``:``completer``:``command``:``argument``:``tag</code>.
|
||
These have the following meaning:</p>
|
||
<ul>
|
||
<li>The literal string <code>completion</code>, 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 <code>predict-on</code> and the
|
||
various functions in the <code>Widget</code> 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; ‘<code>complete</code>’ 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 <code>#compdef</code> tag or the <code>compdef</code> 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
|
||
<code>cvs</code> command sets this field to <code>cvs-add</code> when completing arguments
|
||
to the <code>add</code> 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 <code>argument-``n</code>, where <code>n</code> is the number of the argument, and
|
||
for arguments to options the form <code>option-``opt``-``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 <code>:completion:</code> 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-example">:completion::complete:dvips:option-o-1:files
|
||
</code></pre>
|
||
</div>
|
||
<p>says that normal completion was attempted as the first argument to the
|
||
option <code>-o</code> of the command <code>dvips</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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
|
||
<code>tag-order</code> style. Completion is then restricted to the list of given
|
||
tags in the given order.</p>
|
||
<p>The <code>_complete_help</code> bindable command shows all the contexts and tags
|
||
available for completion at a particular point. This provides an easy
|
||
way of finding information for <code>tag-order</code> 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) style pattern, and the name of the style itself, which must be
|
||
matched exactly. The following examples demonstrate that style 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 <code>verbose</code> 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-example">zstyle ':completion:*' verbose yes
|
||
</code></pre>
|
||
</div>
|
||
<p>in a startup file (probably <code>.zshrc</code>). This gives the <code>verbose</code> style
|
||
the value <code>yes</code> in every context inside the completion system, unless
|
||
that context has a more specific definition. It is best to avoid giving
|
||
the context as ‘<code>*</code>’ 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
|
||
<code>compinstall</code> function.</p>
|
||
<p>A more specific example of the use of the <code>verbose</code> style is by the
|
||
completion for the <code>kill</code> 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-example">zstyle ':completion:*:*:kill:*:*' verbose no
|
||
</code></pre>
|
||
</div>
|
||
<p>For even more control, the style can use one of the tags ‘<code>jobs</code>’ or
|
||
‘<code>processes</code>’. To turn off verbose display only for jobs:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*:*:kill:*:jobs' verbose no
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>-e</code> option to <code>zstyle</code> 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-example">zstyle -e ':completion:*' hosts 'reply=($myhosts)'
|
||
</code></pre>
|
||
</div>
|
||
<p>This forces the value of the <code>hosts</code> style to be read from the variable
|
||
<code>myhosts</code> each time a host name is needed; this is useful if the value
|
||
of <code>myhosts</code> can change dynamically. For another useful example, see the
|
||
example in the description of the <code>file-list</code> style below. This form can
|
||
be slow and should be avoided for commonly examined styles such as
|
||
<code>menu</code> and <code>list-rows-first</code>.</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. More precisely, strings are
|
||
preferred over patterns (for example, ‘<code>:completion::complete:::foo</code>’ is
|
||
more specific than ‘<code>:completion::complete:::*’</code>), and longer patterns
|
||
are preferred over shorter patterns.</p>
|
||
<p>A good rule of thumb is that any completion style pattern that needs to
|
||
include more than one wildcard (<code>*</code>) and that does not end in a tag
|
||
name, should include all six colons (<code>:</code>), possibly surrounding
|
||
additional wildcards.</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><code>accounts</code></p>
|
||
<p>used to look up the <code>users-hosts</code> style</p>
|
||
<p><span id="index-all_002dexpansions_002c-completion-tag"></span></p>
|
||
<p><code>all-expansions</code></p>
|
||
<p>used by the <code>_expand</code> completer when adding the single string containing
|
||
all possible expansions</p>
|
||
<p><span id="index-all_002dfiles_002c-completion-tag"></span></p>
|
||
<p><code>all-files</code></p>
|
||
<p>for the names of all files (as distinct from a particular subset, see
|
||
the <code>globbed-files</code> tag).</p>
|
||
<p><span id="index-arguments_002c-completion-tag"></span></p>
|
||
<p><code>arguments</code></p>
|
||
<p>for arguments to a command</p>
|
||
<p><span id="index-arrays_002c-completion-tag"></span></p>
|
||
<p><code>arrays</code></p>
|
||
<p>for names of array parameters</p>
|
||
<p><span id="index-association_002dkeys_002c-completion-tag"></span></p>
|
||
<p><code>association-keys</code></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><code>bookmarks</code></p>
|
||
<p>when completing bookmarks (e.g. for URLs and the <code>zftp</code> function suite)</p>
|
||
<p><span id="index-builtins_002c-completion-tag"></span></p>
|
||
<p><code>builtins</code></p>
|
||
<p>for names of builtin commands</p>
|
||
<p><span id="index-characters_002c-completion-tag"></span></p>
|
||
<p><code>characters</code></p>
|
||
<p>for single characters in arguments of commands such as <code>stty</code>. Also used
|
||
when completing character classes after an opening bracket</p>
|
||
<p><span id="index-colormapids_002c-completion-tag"></span></p>
|
||
<p><code>colormapids</code></p>
|
||
<p>for X colormap ids</p>
|
||
<p><span id="index-colors_002c-completion-tag"></span></p>
|
||
<p><code>colors</code></p>
|
||
<p>for color names</p>
|
||
<p><span id="index-commands_002c-completion-tag"></span></p>
|
||
<p><code>commands</code></p>
|
||
<p>for names of external commands. Also used by complex commands such as
|
||
<code>cvs</code> when completing names subcommands.</p>
|
||
<p><span id="index-contexts_002c-completion-tag"></span></p>
|
||
<p><code>contexts</code></p>
|
||
<p>for contexts in arguments to the <code>zstyle</code> builtin command</p>
|
||
<p><span id="index-corrections_002c-completion-tag"></span></p>
|
||
<p><code>corrections</code></p>
|
||
<p>used by the <code>_approximate</code> and <code>_correct</code> completers for possible
|
||
corrections</p>
|
||
<p><span id="index-cursors_002c-completion-tag"></span></p>
|
||
<p><code>cursors</code></p>
|
||
<p>for cursor names used by X programs</p>
|
||
<p><span id="index-default_002c-completion-tag"></span></p>
|
||
<p><code>default</code></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><code>descriptions</code></p>
|
||
<p>used when looking up the value of the <code>format</code> style to generate
|
||
descriptions for types of matches</p>
|
||
<p><span id="index-devices_002c-completion-tag"></span></p>
|
||
<p><code>devices</code></p>
|
||
<p>for names of device special files</p>
|
||
<p><span id="index-directories_002c-completion-tag"></span></p>
|
||
<p><code>directories</code></p>
|
||
<p>for names of directories — <code>local-directories</code> is used instead when
|
||
completing arguments of <code>cd</code> and related builtin commands when the
|
||
<code>cdpath</code> array is set</p>
|
||
<p><span id="index-directory_002dstack_002c-completion-tag"></span></p>
|
||
<p><code>directory-stack</code></p>
|
||
<p>for entries in the directory stack</p>
|
||
<p><span id="index-displays_002c-completion-tag"></span></p>
|
||
<p><code>displays</code></p>
|
||
<p>for X display names</p>
|
||
<p><span id="index-domains_002c-completion-tag"></span></p>
|
||
<p><code>domains</code></p>
|
||
<p>for network domains</p>
|
||
<p><span id="index-email_002d_002a_002c-completion-tag"></span></p>
|
||
<p><code>email-``plugin</code></p>
|
||
<p>for email addresses from the ‘<code>_email-``plugin</code>’ backend of
|
||
<code>_email_addresses</code></p>
|
||
<p><span id="index-expansions_002c-completion-tag"></span></p>
|
||
<p><code>expansions</code></p>
|
||
<p>used by the <code>_expand</code> 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><code>extensions</code></p>
|
||
<p>for X server extensions</p>
|
||
<p><span id="index-file_002ddescriptors_002c-completion-tag"></span></p>
|
||
<p><code>file-descriptors</code></p>
|
||
<p>for numbers of open file descriptors</p>
|
||
<p><span id="index-files_002c-completion-tag"></span></p>
|
||
<p><code>files</code></p>
|
||
<p>the generic file-matching tag used by functions completing filenames</p>
|
||
<p><span id="index-fonts_002c-completion-tag"></span></p>
|
||
<p><code>fonts</code></p>
|
||
<p>for X font names</p>
|
||
<p><span id="index-fstypes_002c-completion-tag"></span></p>
|
||
<p><code>fstypes</code></p>
|
||
<p>for file system types (e.g. for the <code>mount</code> command)</p>
|
||
<p><span id="index-functions_002c-completion-tag"></span></p>
|
||
<p><code>functions</code></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><code>globbed-files</code></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><code>groups</code></p>
|
||
<p>for names of user groups</p>
|
||
<p><span id="index-history_002dwords_002c-completion-tag"></span></p>
|
||
<p><code>history-words</code></p>
|
||
<p>for words from the history</p>
|
||
<p><span id="index-hosts_002c-completion-tag"></span></p>
|
||
<p><code>hosts</code></p>
|
||
<p>for hostnames</p>
|
||
<p><span id="index-indexes_002c-completion-tag"></span></p>
|
||
<p><code>indexes</code></p>
|
||
<p>for array indexes</p>
|
||
<p><span id="index-jobs_002c-completion-tag"></span></p>
|
||
<p><code>jobs</code></p>
|
||
<p>for jobs (as listed by the ‘<code>jobs</code>’ builtin)</p>
|
||
<p><span id="index-interfaces_002c-completion-tag"></span></p>
|
||
<p><code>interfaces</code></p>
|
||
<p>for network interfaces</p>
|
||
<p><span id="index-keymaps_002c-completion-tag"></span></p>
|
||
<p><code>keymaps</code></p>
|
||
<p>for names of zsh keymaps</p>
|
||
<p><span id="index-keysyms_002c-completion-tag"></span></p>
|
||
<p><code>keysyms</code></p>
|
||
<p>for names of X keysyms</p>
|
||
<p><span id="index-libraries_002c-completion-tag"></span></p>
|
||
<p><code>libraries</code></p>
|
||
<p>for names of system libraries</p>
|
||
<p><span id="index-limits_002c-completion-tag"></span></p>
|
||
<p><code>limits</code></p>
|
||
<p>for system limits</p>
|
||
<p><span id="index-local_002ddirectories_002c-completion-tag"></span></p>
|
||
<p><code>local-directories</code></p>
|
||
<p>for names of directories that are subdirectories of the current working
|
||
directory when completing arguments of <code>cd</code> and related builtin commands
|
||
(compare <code>path-directories</code>) — when the <code>cdpath</code> array is unset,
|
||
<code>directories</code> is used instead</p>
|
||
<p><span id="index-manuals_002c-completion-tag"></span></p>
|
||
<p><code>manuals</code></p>
|
||
<p>for names of manual pages</p>
|
||
<p><span id="index-mailboxes_002c-completion-tag"></span></p>
|
||
<p><code>mailboxes</code></p>
|
||
<p>for e-mail folders</p>
|
||
<p><span id="index-maps_002c-completion-tag"></span></p>
|
||
<p><code>maps</code></p>
|
||
<p>for map names (e.g. NIS maps)</p>
|
||
<p><span id="index-messages_002c-completion-tag"></span></p>
|
||
<p><code>messages</code></p>
|
||
<p>used to look up the <code>format</code> style for messages</p>
|
||
<p><span id="index-modifiers_002c-completion-tag"></span></p>
|
||
<p><code>modifiers</code></p>
|
||
<p>for names of X modifiers</p>
|
||
<p><span id="index-modules_002c-completion-tag"></span></p>
|
||
<p><code>modules</code></p>
|
||
<p>for modules (e.g. <code>zsh</code> modules)</p>
|
||
<p><span id="index-my_002daccounts_002c-completion-tag"></span></p>
|
||
<p><code>my-accounts</code></p>
|
||
<p>used to look up the <code>users-hosts</code> style</p>
|
||
<p><span id="index-named_002ddirectories_002c-completion-tag"></span></p>
|
||
<p><code>named-directories</code></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><code>names</code></p>
|
||
<p>for all kinds of names</p>
|
||
<p><span id="index-newsgroups_002c-completion-tag"></span></p>
|
||
<p><code>newsgroups</code></p>
|
||
<p>for USENET groups</p>
|
||
<p><span id="index-nicknames_002c-completion-tag"></span></p>
|
||
<p><code>nicknames</code></p>
|
||
<p>for nicknames of NIS maps</p>
|
||
<p><span id="index-options_002c-completion-tag"></span></p>
|
||
<p><code>options</code></p>
|
||
<p>for command options</p>
|
||
<p><span id="index-original_002c-completion-tag"></span></p>
|
||
<p><code>original</code></p>
|
||
<p>used by the <code>_approximate</code>, <code>_correct</code> and <code>_expand</code> completers when
|
||
offering the original string as a match</p>
|
||
<p><span id="index-other_002daccounts_002c-completion-tag"></span></p>
|
||
<p><code>other-accounts</code></p>
|
||
<p>used to look up the <code>users-hosts</code> style</p>
|
||
<p><span id="index-other_002dfiles_002c-completion-tag"></span></p>
|
||
<p><code>other-files</code></p>
|
||
<p>for the names of any non-directory files. This is used instead of
|
||
<code>all-files</code> when the <code>list-dirs-first</code> style is in effect.</p>
|
||
<p><span id="index-packages_002c-completion-tag"></span></p>
|
||
<p><code>packages</code></p>
|
||
<p>for packages (e.g. <code>rpm</code> or installed <code>Debian</code> packages)</p>
|
||
<p><span id="index-parameters_002c-completion-tag"></span></p>
|
||
<p><code>parameters</code></p>
|
||
<p>for names of parameters</p>
|
||
<p><span id="index-path_002ddirectories_002c-completion-tag"></span></p>
|
||
<p><code>path-directories</code></p>
|
||
<p>for names of directories found by searching the <code>cdpath</code> array when
|
||
completing arguments of <code>cd</code> and related builtin commands (compare
|
||
<code>local-directories</code>)</p>
|
||
<p><span id="index-paths_002c-completion-tag"></span></p>
|
||
<p><code>paths</code></p>
|
||
<p>used to look up the values of the <code>expand</code>, <code>ambiguous</code> and
|
||
<code>special-dirs</code> styles</p>
|
||
<p><span id="index-pods_002c-completion-tag"></span></p>
|
||
<p><code>pods</code></p>
|
||
<p>for perl pods (documentation files)</p>
|
||
<p><span id="index-ports_002c-completion-tag"></span></p>
|
||
<p><code>ports</code></p>
|
||
<p>for communication ports</p>
|
||
<p><span id="index-prefixes_002c-completion-tag"></span></p>
|
||
<p><code>prefixes</code></p>
|
||
<p>for prefixes (like those of a URL)</p>
|
||
<p><span id="index-printers_002c-completion-tag"></span></p>
|
||
<p><code>printers</code></p>
|
||
<p>for print queue names</p>
|
||
<p><span id="index-processes_002c-completion-tag"></span></p>
|
||
<p><code>processes</code></p>
|
||
<p>for process identifiers</p>
|
||
<p><span id="index-processes_002dnames_002c-completion-tag"></span></p>
|
||
<p><code>processes-names</code></p>
|
||
<p>used to look up the <code>command</code> style when generating the names of
|
||
processes for <code>killall</code></p>
|
||
<p><span id="index-sequences_002c-completion-tag"></span></p>
|
||
<p><code>sequences</code></p>
|
||
<p>for sequences (e.g. <code>mh</code> sequences)</p>
|
||
<p><span id="index-sessions_002c-completion-tag"></span></p>
|
||
<p><code>sessions</code></p>
|
||
<p>for sessions in the <code>zftp</code> function suite</p>
|
||
<p><span id="index-signals_002c-completion-tag"></span></p>
|
||
<p><code>signals</code></p>
|
||
<p>for signal names</p>
|
||
<p><span id="index-strings_002c-completion-tag"></span></p>
|
||
<p><code>strings</code></p>
|
||
<p>for strings (e.g. the replacement strings for the <code>cd</code> builtin command)</p>
|
||
<p><span id="index-styles_002c-completion-tag"></span></p>
|
||
<p><code>styles</code></p>
|
||
<p>for styles used by the zstyle builtin command</p>
|
||
<p><span id="index-suffixes_002c-completion-tag"></span></p>
|
||
<p><code>suffixes</code></p>
|
||
<p>for filename extensions</p>
|
||
<p><span id="index-tags_002c-completion-tag"></span></p>
|
||
<p><code>tags</code></p>
|
||
<p>for tags (e.g. <code>rpm</code> tags)</p>
|
||
<p><span id="index-targets_002c-completion-tag"></span></p>
|
||
<p><code>targets</code></p>
|
||
<p>for makefile targets</p>
|
||
<p><span id="index-time_002dzones_002c-completion-tag"></span></p>
|
||
<p><code>time-zones</code></p>
|
||
<p>for time zones (e.g. when setting the <code>TZ</code> parameter)</p>
|
||
<p><span id="index-types_002c-completion-tag"></span></p>
|
||
<p><code>types</code></p>
|
||
<p>for types of whatever (e.g. address types for the <code>xhost</code> command)</p>
|
||
<p><span id="index-urls_002c-completion-tag"></span></p>
|
||
<p><code>urls</code></p>
|
||
<p>used to look up the <code>urls</code> and <code>local</code> styles when completing URLs</p>
|
||
<p><span id="index-users_002c-completion-tag"></span></p>
|
||
<p><code>users</code></p>
|
||
<p>for usernames</p>
|
||
<p><span id="index-values_002c-completion-tag"></span></p>
|
||
<p><code>values</code></p>
|
||
<p>for one of a set of values in certain lists</p>
|
||
<p><span id="index-variant_002c-completion-tag"></span></p>
|
||
<p><code>variant</code></p>
|
||
<p>used by <code>_pick_variant</code> 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><code>visuals</code></p>
|
||
<p>for X visuals</p>
|
||
<p><span id="index-warnings_002c-completion-tag"></span></p>
|
||
<p><code>warnings</code></p>
|
||
<p>used to look up the <code>format</code> style for warnings</p>
|
||
<p><span id="index-widgets_002c-completion-tag"></span></p>
|
||
<p><code>widgets</code></p>
|
||
<p>for zsh widget names</p>
|
||
<p><span id="index-windows_002c-completion-tag"></span></p>
|
||
<p><code>windows</code></p>
|
||
<p>for IDs of X windows</p>
|
||
<p><span id="index-zsh_002doptions_002c-completion-tag"></span></p>
|
||
<p><code>zsh-options</code></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 ‘<code>true</code>’, ‘<code>on</code>’, ‘<code>yes</code>’, and ‘<code>1</code>’ can be
|
||
used for the value ‘true’ and any of the strings ‘<code>false</code>’, ‘<code>off</code>’,
|
||
‘<code>no</code>’, and ‘<code>0</code>’ 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
|
||
<code>list-colors</code> and styles controlling completion listing such as
|
||
<code>list-packed</code> and <code>last-prompt</code>. When tested for the <code>default</code> tag, only
|
||
the <code>function</code> field of the context will be set so that a style using
|
||
the <code>default</code> tag will normally be defined along the lines of:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*:default' menu ...
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-accept_002dexact_002c-completion-style"></span></p>
|
||
<p><code>accept-exact</code></p>
|
||
<p>This is tested for the <code>default</code> 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 ‘<code>paths</code>’) 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 <code>_expand</code> completer to decide if words
|
||
beginning with a tilde or parameter expansion should be expanded. For
|
||
example, if there are parameters <code>foo</code> and <code>foobar</code>, the string ‘<code>$foo</code>’
|
||
will only be expanded if <code>accept-exact</code> is set to ‘true’; otherwise the
|
||
completion system will be allowed to complete <code>$foo</code> to <code>$foobar</code>. If
|
||
the style is set to ‘<code>continue</code>’, <code>_expand</code> 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><code>accept-exact-dirs</code></p>
|
||
<p>This is used by filename completion. Unlike <code>accept-exact</code> 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 <code>/usr/bin/</code>, the function examines possible completions to <code>/usr</code>.</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 <code>/usr/bin/</code> 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 <code>.zfs</code> directories or
|
||
NetApp <code>.snapshot</code> 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
|
||
<code>path-completion</code> style (see below) to ‘false’.</p>
|
||
<p><span id="index-add_002dspace_002c-completion-style"></span></p>
|
||
<p><code>add-space</code></p>
|
||
<p>This style is used by the <code>_expand</code> 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
|
||
‘<code>file</code>’, the completer will only add a space to names of existing
|
||
files. Either a boolean ‘true’ or the value ‘<code>file</code>’ may be combined
|
||
with ‘<code>subst</code>’, 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 <code>_prefix</code> 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><code>ambiguous</code></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 <code>paths</code> tag.</p>
|
||
<p><span id="index-assign_002dlist_002c-completion-style"></span></p>
|
||
<p><code>assign-list</code></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 <code>PATH</code> 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><code>auto-description</code></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 ‘<code>%d</code>’ 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 ‘<code>specify: %d</code>’.
|
||
Note that this may not work for some commands.</p>
|
||
<p><span id="index-avoid_002dcompleter_002c-completion-style"></span></p>
|
||
<p><code>avoid-completer</code></p>
|
||
<p>This is used by the <code>_all_matches</code> 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 ‘<code>_expand _old_list _correct _approximate</code>’, 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><code>cache-path</code></p>
|
||
<p>This style defines the path where any cache files containing dumped
|
||
completion data are stored. It defaults to ‘<code>$ZDOTDIR/.zcompcache</code>’, or
|
||
‘<code>$HOME/.zcompcache</code>’ if <code>$ZDOTDIR</code> is not defined. The completion
|
||
cache will not be used unless the <code>use-cache</code> style is set.</p>
|
||
<p><span id="index-cache_002dpolicy_002c-completion-style"></span></p>
|
||
<p><code>cache-policy</code></p>
|
||
<p>This style defines the function that will be used to determine whether a
|
||
cache needs rebuilding. See the section on the <code>_cache_invalid</code> function
|
||
below.</p>
|
||
<p><span id="index-call_002dcommand_002c-completion-style"></span></p>
|
||
<p><code>call-command</code></p>
|
||
<p>This style is used in the function for commands such as <code>make</code> and <code>ant</code>
|
||
where calling the command directly to generate matches suffers problems
|
||
such as being slow or, as in the case of <code>make</code> 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><code>command</code></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 ‘<code>builtin</code>’ or ‘<code>command</code>’ 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 <code>processes</code> tag to generate the IDs to complete and the list of
|
||
processes to display (if the <code>verbose</code> style is ‘true’). The list
|
||
produced by the command should look like the output of the <code>ps</code> command.
|
||
The first line is not displayed, but is searched for the string ‘<code>PID</code>’
|
||
(or ‘<code>pid</code>’) to find the position of the process IDs in the following
|
||
lines. If the line does not contain ‘<code>PID</code>’, 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><code>command-path</code></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 <code>path</code>.</p>
|
||
<p><span id="index-commands_002c-completion-style"></span></p>
|
||
<p><code>commands</code></p>
|
||
<p>This is used by the function completing sub-commands for the system
|
||
initialisation scripts (residing in <code>/etc/init.d</code> 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
|
||
‘<code>start</code>’ and ‘<code>stop</code>’.</p>
|
||
<p><span id="index-complete_002c-completion-style"></span></p>
|
||
<p><code>complete</code></p>
|
||
<p>This is used by the <code>_expand_alias</code> 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><code>complete-options</code></p>
|
||
<p>This is used by the completer for <code>cd</code>, <code>chdir</code> and <code>pushd</code>. For these
|
||
commands a <code>-</code> 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 <code>-</code>. If it is ‘true’, options will be completed
|
||
after an initial <code>-</code> unless there is a preceding <code>-``-</code> on the command
|
||
line.</p>
|
||
<p><span id="index-completer_002c-completion-style"></span></p>
|
||
<p><code>completer</code></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``:``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-example">zstyle ':completion:*' completer _complete _complete:-foo
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, completion will call the <code>_complete</code> completer twice, once using
|
||
‘<code>complete</code>’ and once using ‘<code>complete-foo</code>’ 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``:``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 <code>_ignored</code> and
|
||
<code>_prefix</code> completers.</p>
|
||
<p>The default value for this style is ‘<code>_complete _ignored</code>’: only
|
||
completion will be done, first using the <code>ignored-patterns</code> style and
|
||
the <code>$fignore</code> array and then without ignoring matches.</p>
|
||
<p><span id="index-condition_002c-completion-style"></span></p>
|
||
<p><code>condition</code></p>
|
||
<p>This style is used by the <code>_list</code> 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><code>delimiters</code></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 <code>:</code>, <code>+</code>, <code>/</code>, <code>-</code>, <code>%</code>. The list may be empty to force
|
||
a delimiter to be typed.</p>
|
||
<p><span id="index-disabled_002c-completion-style"></span></p>
|
||
<p><code>disabled</code></p>
|
||
<p>If this is set to ‘true’, the <code>_expand_alias</code> 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><code>domains</code></p>
|
||
<p>A list of names of network domains for completion. If this is not set,
|
||
domain names will be taken from the file <code>/etc/resolv.conf</code>.</p>
|
||
<p><span id="index-environ_002c-completion-style"></span></p>
|
||
<p><code>environ</code></p>
|
||
<p>The environ style is used when completing for ‘<code>sudo</code>’. It is set to an
|
||
array of ‘<code>VAR``=``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-example">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><code>expand</code></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 ‘<code>prefix</code>’, 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 ‘<code>suffix</code>’, 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-fake_002c-completion-style"></span></p>
|
||
<p><code>fake</code></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``:``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 <code>fake-files</code> and
|
||
<code>fake-parameters</code> provide additional features when completing files or
|
||
parameters.</p>
|
||
<p><span id="index-fake_002dalways_002c-completion-style"></span></p>
|
||
<p><code>fake-always</code></p>
|
||
<p>This works identically to the <code>fake</code> style except that the
|
||
<code>ignored-patterns</code> style is not applied to it. This makes it possible to
|
||
override a set of matches completely by setting the ignored patterns to
|
||
‘<code>*</code>’.</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 <code>tag-order</code> style to divide the
|
||
<code>named-directories</code> tag into two when performing completion with the
|
||
standard completer <code>complete</code> for arguments of <code>cd</code>. The tag
|
||
<code>named-directories-normal</code> behaves as normal, but the tag
|
||
<code>named-directories-mine</code> contains a fixed set of directories. This has
|
||
the effect of adding the match group ‘<code>extra directories</code>’ with the
|
||
given completions.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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><code>fake-files</code></p>
|
||
<p>This style is used when completing files and looked up without a tag.
|
||
Its values are of the form ‘<code>dir``:``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 <code>accept-exact-dirs</code> 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><code>fake-parameters</code></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 ‘<code>scalar</code>’, ‘<code>array</code>’
|
||
or ‘<code>integer</code>’). 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><code>file-list</code></p>
|
||
<p>This style controls whether files completed using the standard builtin
|
||
mechanism are to be listed with a long list similar to <code>ls -l</code>. Note
|
||
that this feature uses the shell module <code>zsh/stat</code> for file information;
|
||
this loads the builtin <code>stat</code> this the following code can be included in
|
||
an initialization file:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmodload -i zsh/stat
|
||
disable stat
|
||
</code></pre>
|
||
</div>
|
||
<p>The style may either be set to a ‘true’ value (or ‘<code>all</code>’), or one of
|
||
the values ‘<code>insert</code>’ or ‘<code>list</code>’, 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-example">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-example">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><code>file-patterns</code></p>
|
||
<p>This is used by the standard function for completing filenames,
|
||
<code>_files</code>. If the style is unset up to three tags are offered,
|
||
‘<code>globbed-files</code>’,‘<code>directories</code>’ and ‘<code>all-files</code>’, depending on the
|
||
types of files expected by the caller of <code>_files</code>. The first two
|
||
(‘<code>globbed-files</code>’ and ‘<code>directories</code>’) are normally offered together
|
||
to make it easier to complete files in sub-directories.</p>
|
||
<p>The <code>file-patterns</code> style provides alternatives to the default tags,
|
||
which are not used. Its value consists of elements of the form
|
||
‘<code>pattern``:``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 ‘<code>%p</code>’ is replaced by any pattern(s) passed
|
||
by the function calling <code>_files</code>. 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 <code>_files</code> 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 ‘<code>files</code>’ 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 ‘<code>%d</code>’ in the value of the
|
||
<code>format</code> style (if that is set) instead of the default description
|
||
supplied by the completion function. If the description given here
|
||
contains itself a ‘<code>%d</code>’, that is replaced with the description supplied
|
||
by the completion function.</p>
|
||
<p>For example, to make the <code>rm</code> 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-example">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-example">zstyle ':completion:*' file-patterns \
|
||
'%p:globbed-files' '*(-/):directories' '*:all-files'
|
||
</code></pre>
|
||
</div>
|
||
<p>This works even where there is no special pattern: <code>_files</code> matches all
|
||
files using the pattern ‘<code>*</code>’ 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>During the execution of completion functions, the <code>EXTENDED_GLOB</code> option
|
||
is in effect, so the characters ‘<code>#</code>’, ‘<code>~</code>’ and ‘<code>^</code>’ have special
|
||
meanings in the patterns.</p>
|
||
<p><span id="index-file_002dsort_002c-completion-style"></span></p>
|
||
<p><code>file-sort</code></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:
|
||
‘<code>size</code>’ to sort by the size of the file; ‘<code>links</code>’ to sort by the
|
||
number of links to the file; ‘<code>modification</code>’ (or ‘<code>time</code>’ or ‘<code>date</code>’)
|
||
to sort by the last modification time; ‘<code>access</code>’ to sort by the last
|
||
access time; and ‘<code>inode</code>’ (or ‘<code>change</code>’) 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
|
||
‘<code>reverse</code>’, sorting is done in the opposite order. If the value
|
||
contains the string ‘<code>follow</code>’, 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><code>file-split-chars</code></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 <code>:</code>; then everything up to and
|
||
including the last <code>:</code> 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><code>filter</code></p>
|
||
<p>The <code>ldap</code> plugin of email address completion (see <code>_email_addresses</code>)
|
||
uses this style to specify the attributes to match against when
|
||
filtering entries. So for example, if the style is set to ‘<code>sn</code>’,
|
||
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 <code>command</code> style to
|
||
specify how to connect to your LDAP server.</p>
|
||
<p><span id="index-force_002dlist_002c-completion-style"></span></p>
|
||
<p><code>force-list</code></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 ‘<code>always</code>’, 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><code>format</code></p>
|
||
<p>If this is set for the <code>descriptions</code> tag, its value is used as a string
|
||
to display above matches in completion lists. The sequence ‘<code>%d</code>’ 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 <code>compadd -X</code> (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 <code>descriptions</code> tag. Hence different format
|
||
strings can be defined for different types of match.</p>
|
||
<p>Note also that some completer functions define additional
|
||
‘<code>%</code>’-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 <code>messages</code> tag. Here, the ‘<code>%d</code>’ is replaced
|
||
with a message given by the completion function.</p>
|
||
<p>Finally, the format string is looked up with the <code>warnings</code> tag, for use
|
||
when no matches could be generated at all. In this case the ‘<code>%d</code>’ is
|
||
replaced with the descriptions for the matches that were expected
|
||
separated by spaces. The sequence ‘<code>%D</code>’ is replaced with the same
|
||
descriptions separated by newlines.</p>
|
||
<p>It is possible to use printf-style field width specifiers with ‘<code>%d</code>’
|
||
and similar escape sequences. This is handled by the <code>zformat</code> builtin
|
||
command from the <code>zsh/zutil</code> module, see <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>.</p>
|
||
<p><span id="index-glob_002c-completion-style"></span></p>
|
||
<p><code>glob</code></p>
|
||
<p>This is used by the <code>_expand</code> completer. If it is set to ‘true’ (the
|
||
default), globbing will be attempted on the words resulting from a
|
||
previous substitution (see the <code>substitute</code> style) or else the original
|
||
string from the line.</p>
|
||
<p><span id="index-global_002c-completion-style"></span></p>
|
||
<p><code>global</code></p>
|
||
<p>If this is set to ‘true’ (the default), the <code>_expand_alias</code> completer
|
||
and bindable command will try to expand global aliases.</p>
|
||
<p><span id="index-group_002dname_002c-completion-style"></span></p>
|
||
<p><code>group-name</code></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-example">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-example">zstyle ':completion:*' group-name ''
|
||
</code></pre>
|
||
</div>
|
||
<p>All matches for which no group name is defined will be put in a group
|
||
named <code>-default-</code>.</p>
|
||
<p><span id="index-group_002dorder_002c-completion-style"></span></p>
|
||
<p><code>group-order</code></p>
|
||
<p>This style is additional to the <code>group-name</code> style to specify the order
|
||
for display of the groups defined by that style (compare <code>tag-order</code>,
|
||
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-example">zstyle ':completion:*:*:-command-:*:*' group-order \
|
||
builtins functions commands
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-groups_002c-completion-style"></span></p>
|
||
<p><code>groups</code></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 ‘<code>/etc/group</code>’.</p>
|
||
<p><span id="index-hidden_002c-completion-style"></span></p>
|
||
<p><code>hidden</code></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 <code>format</code>
|
||
style will be shown. If it is set to ‘<code>all</code>’, 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 <code>tag-order</code> style can be modified as described below.</p>
|
||
<p><span id="index-hosts_002c-completion-style"></span></p>
|
||
<p><code>hosts</code></p>
|
||
<p>A list of names of hosts that should be completed. If this is not set,
|
||
hostnames are taken from the file ‘<code>/etc/hosts</code>’.</p>
|
||
<p><span id="index-hosts_002dports_002c-completion-style"></span></p>
|
||
<p><code>hosts-ports</code></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``:``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><code>ignore-line</code></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 ‘<code>current</code>’, the
|
||
word the cursor is on will not be considered as a possible completion.
|
||
The value ‘<code>current-shown</code>’ is similar but only applies if the list of
|
||
completions is currently shown on the screen. Finally, if the style is
|
||
set to ‘<code>other</code>’, all words on the line except for the current one will
|
||
be excluded from the possible completions.</p>
|
||
<p>The values ‘<code>current</code>’ and ‘<code>current-shown</code>’ are a bit like the opposite
|
||
of the <code>accept-exact</code> 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
|
||
‘<code>other</code>’ for a general context such as ‘<code>:completion:*</code>’. 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><code>ignore-parents</code></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>
|
||
<ul>
|
||
<li>
|
||
<p><code>parent</code><br />
|
||
The name of any directory whose path is already contained in the
|
||
word on the line is ignored. For example, when completing after
|
||
<code>foo/../</code>, the directory <code>foo</code> will not be considered a valid
|
||
completion.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pwd</code><br />
|
||
The name of the current working directory will not be completed;
|
||
hence, for example, completion after <code>../</code> will not use the name of
|
||
the current directory.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In addition, the value may include one or both of:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>..</code><br />
|
||
Ignore the specified directories only when the word on the line
|
||
contains the substring ‘<code>../</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>directory</code><br />
|
||
Ignore the specified directories only when names of directories are
|
||
completed, not when completing names of files.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Excluded values act in a similar fashion to values of the
|
||
<code>ignored-patterns</code> style, so they can be restored to consideration by
|
||
the <code>_ignored</code> completer.</p>
|
||
<p><span id="index-extra_002dverbose_002c-completion-style"></span></p>
|
||
<p><code>extra-verbose</code></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-ignored_002dpatterns_002c-completion-style"></span></p>
|
||
<p><code>ignored-patterns</code></p>
|
||
<p>A list of patterns; any trial completion matching one of the patterns
|
||
will be excluded from consideration. The <code>_ignored</code> completer can appear
|
||
in the list of completers to restore the ignored matches. This is a more
|
||
configurable version of the shell parameter <code>$fignore</code>.</p>
|
||
<p>Note that the <code>EXTENDED_GLOB</code> option is set during the execution of
|
||
completion functions, so the characters ‘<code>#</code>’, ‘<code>~</code>’ and ‘<code>^</code>’ have
|
||
special meanings in the patterns.</p>
|
||
<p><span id="index-insert_002c-completion-style"></span></p>
|
||
<p><code>insert</code></p>
|
||
<p>This style is used by the <code>_all_matches</code> 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><code>insert-ids</code></p>
|
||
<p>When completing process IDs, for example as arguments to the <code>kill</code> and
|
||
<code>wait</code> 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 ‘<code>menu</code>’)
|
||
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 ‘<code>single</code>’, 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_002dtab_002c-completion-style"></span></p>
|
||
<p><code>insert-tab</code></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 ‘<code>pending</code>’ or
|
||
‘<code>pending=``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
|
||
<code>$PENDING</code> special parameter from the <code>zsh/zle</code> 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
|
||
<code>vared</code> builtin command where it is ‘false’.</p>
|
||
<p><span id="index-insert_002dunambiguous_002c-completion-style"></span></p>
|
||
<p><code>insert-unambiguous</code></p>
|
||
<p>This is used by the <code>_match</code> and <code>_approximate</code> 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 <code>_approximate</code> completer, the completer field in the
|
||
context will already have been set to one of <code>correct-``num</code> or
|
||
<code>approximate-``num</code>, where <code>num</code> is the number of errors that were
|
||
accepted.</p>
|
||
<p>In the case of the <code>_match</code> completer, the style may also be set to the
|
||
string ‘<code>pattern</code>’. Then the pattern on the line is left unchanged if it
|
||
does not match unambiguously.</p>
|
||
<p><span id="index-gain_002dprivileges_002c-completion-style"></span></p>
|
||
<p><code>gain-privileges</code></p>
|
||
<p>If set to <code>true</code>, this style enables the use of commands like <code>sudo</code> or
|
||
<code>doas</code> to gain extra privileges when retrieving information for
|
||
completion. This is only done when a command such as <code>sudo</code> appears on
|
||
the command-line. To force the use of, e.g. <code>sudo</code> or to override any
|
||
prefix that might be added due to <code>gain-privileges</code>, the <code>command</code> style
|
||
can be used with a value that begins with a hyphen.</p>
|
||
<p><span id="index-keep_002dprefix_002c-completion-style"></span></p>
|
||
<p><code>keep-prefix</code></p>
|
||
<p>This style is used by the <code>_expand</code> completer. If it is ‘true’, the
|
||
completer will try to keep a prefix containing a tilde or parameter
|
||
expansion. Hence, for example, the string ‘<code>~/f*</code>’ would be expanded to
|
||
‘<code>~/foo</code>’ instead of ‘<code>/home/user/foo</code>’. If the style is set to
|
||
‘<code>changed</code>’ (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 <code>_expand</code> when this style is ‘true’ is to cause
|
||
<code>_expand</code> 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-last_002dprompt_002c-completion-style"></span></p>
|
||
<p><code>last-prompt</code></p>
|
||
<p>This is a more flexible form of the <code>ALWAYS_LAST_PROMPT</code> 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 <code>default</code> 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
|
||
<code>ALWAYS_LAST_PROMPT</code> option this is independent of the numeric argument.</p>
|
||
<p><span id="index-known_002dhosts_002dfiles"></span></p>
|
||
<p><code>known-hosts-files</code></p>
|
||
<p>This style should contain a list of files to search for host names and
|
||
(if the <code>use-ip</code> style is set) IP addresses in a format compatible with
|
||
ssh <code>known_hosts</code> files. If it is not set, the files
|
||
<code>/etc/ssh/ssh_known_hosts</code> and <code>~/.ssh/known_hosts</code> are used.</p>
|
||
<p><span id="index-list_002c-completion-style"></span></p>
|
||
<p><code>list</code></p>
|
||
<p>This style is used by the <code>_history_complete_word</code> 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 <code>AUTO_LIST</code>. The context
|
||
always starts with ‘<code>:completion:history-words</code>’.</p>
|
||
<p><span id="index-list_002dcolors_002c-completion-style"></span></p>
|
||
<p><code>list-colors</code></p>
|
||
<p>If the <code>zsh/complist</code> module is loaded, this style can be used to set
|
||
color specifications. This mechanism replaces the use of the
|
||
<code>ZLS_COLORS</code> and <code>ZLS_COLOURS</code> 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 <code>default</code> 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 <code>group-name</code> 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 <code>group-name</code> tag together
|
||
with the ‘<code>(group)</code>’ syntax allowed by the <code>ZLS_COLORS</code> and
|
||
<code>ZLS_COLOURS</code> parameters and simply using the <code>default</code> tag.</p>
|
||
<p>It is possible to use any color specifications already set up for the
|
||
GNU version of the <code>ls</code> command:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*:default' list-colors \
|
||
${(s.:.)LS_COLORS}
|
||
</code></pre>
|
||
</div>
|
||
<p>The default colors are the same as for the GNU <code>ls</code> command and can be
|
||
obtained by setting the style to an empty string (i.e. <code>’’</code>).</p>
|
||
<p><span id="index-list_002ddirs_002dfirst_002c-completion-style"></span></p>
|
||
<p><code>list-dirs-first</code></p>
|
||
<p>This is used by file completion. If set, directories to be completed are
|
||
listed separately from and before completion for other files, regardless
|
||
of tag ordering. In addition, the tag <code>other-files</code> is used in place of
|
||
<code>all-files</code> for the remaining files, to indicate that no directories are
|
||
presented with that tag.</p>
|
||
<p><span id="index-list_002dgrouped_002c-completion-style"></span></p>
|
||
<p><code>list-grouped</code></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 <code>verbose</code> 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><code>list-packed</code></p>
|
||
<p>This is tested for each tag valid in the current context as well as the
|
||
<code>default</code> tag. If it is set to ‘true’, the corresponding matches appear
|
||
in listings as if the <code>LIST_PACKED</code> 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><code>list-prompt</code></p>
|
||
<p>If this style is set for the <code>default</code> 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: ‘<code>%l</code>’ or ‘<code>%L</code>’, which will
|
||
be replaced by the number of the last line displayed and the total
|
||
number of lines; ‘<code>%m</code>’ or ‘<code>%M</code>’, the number of the last match shown
|
||
and the total number of matches; and ‘<code>%p</code>’ and ‘<code>%P</code>’, ‘<code>Top</code>’ when at
|
||
the beginning of the list, ‘<code>Bottom</code>’ 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 ‘<code>%S</code>’, ‘<code>%s</code>’, ‘<code>%B</code>’, ‘<code>%b</code>’, ‘<code>%U</code>’, ‘<code>%u</code>’ for
|
||
entering and leaving the display modes standout, bold and underline, and
|
||
‘<code>%F</code>’, ‘<code>%f</code>’, ‘<code>%K</code>’, ‘<code>%k</code>’ for changing the foreground background
|
||
colour, are also available, as is the form ‘<code>%{</code>...<code>%}</code>’ for enclosing
|
||
escape sequences which display with zero (or, with a numeric argument,
|
||
some other) width.</p>
|
||
<p>After deleting this prompt the variable <code>LISTPROMPT</code> should be unset for
|
||
the removal to take effect.</p>
|
||
<p><span id="index-list_002drows_002dfirst_002c-completion-style"></span></p>
|
||
<p><code>list-rows-first</code></p>
|
||
<p>This style is tested in the same way as the <code>list-packed</code> style and
|
||
determines whether matches are to be listed in a rows-first fashion as
|
||
if the <code>LIST_ROWS_FIRST</code> option were set.</p>
|
||
<p><span id="index-list_002dsuffixes_002c-completion-style"></span></p>
|
||
<p><code>list-suffixes</code></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-list_002dseparator_002c-completion-style"></span></p>
|
||
<p><code>list-separator</code></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 ‘<code>-``-</code>’ (two hyphens).</p>
|
||
<p><span id="index-local_002c-completion-style"></span></p>
|
||
<p><code>local</code></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-example">zstyle ':completion:*' local toast \
|
||
/var/http/public/toast public_html
|
||
</code></pre>
|
||
</div>
|
||
<p>Completion after ‘<code>http://toast/stuff/</code>’ will look for files in the
|
||
directory <code>/var/http/public/toast/stuff</code>, while completion after
|
||
‘<code>http://toast/~yousir/</code>’ will look for files in the directory
|
||
<code>~yousir/public_html</code>.</p>
|
||
<p><span id="index-mail_002ddirectory_002c-completion-style"></span></p>
|
||
<p><code>mail-directory</code></p>
|
||
<p>If set, zsh will assume that mailbox files can be found in the directory
|
||
specified. It defaults to ‘<code>~/Mail</code>’.</p>
|
||
<p><span id="index-match_002doriginal_002c-completion-style"></span></p>
|
||
<p><code>match-original</code></p>
|
||
<p>This is used by the <code>_match</code> completer. If it is set to <code>only</code>, <code>_match</code>
|
||
will try to generate matches without inserting a ‘<code>*</code>’ at the cursor
|
||
position. If set to any other non-empty value, it will first try to
|
||
generate matches without inserting the ‘<code>*</code>’ and if that yields no
|
||
matches, it will try again with the ‘<code>*</code>’ inserted. If it is unset or
|
||
set to the empty string, matching will only be performed with the ‘<code>*</code>’
|
||
inserted.</p>
|
||
<p><span id="index-matcher_002c-completion-style"></span></p>
|
||
<p><code>matcher</code></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 <code>matcher-list</code> style so can override them via the use of an <code>x:</code>
|
||
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 <code>tag-order</code> style.</p>
|
||
<p>For notes comparing the use of this and the <code>matcher-list</code> style, see
|
||
under the description of the <code>tag-order</code> style.</p>
|
||
<p><span id="index-matcher_002dlist_002c-completion-style"></span></p>
|
||
<p><code>matcher-list</code></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-example">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 <code>+</code>, 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-example">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 <code>_prefix</code> and <code>_ignored</code>. For example, to use the
|
||
completers <code>_complete</code> and <code>_prefix</code> but allow case-insensitive
|
||
completion only with <code>_complete</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>completer</code> 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-example">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 <code>_correct</code> and <code>_approximate</code> do
|
||
not use the match specifications at all, though these completers will
|
||
only ever be called once even if the <code>matcher-list</code> 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 <code>matcher-list</code>, 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
|
||
<code>NO_CASE_GLOB</code> 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 <code>matcher</code> style, see under
|
||
the description of the <code>tag-order</code> style.</p>
|
||
<p><span id="index-max_002derrors_002c-completion-style"></span></p>
|
||
<p><code>max-errors</code></p>
|
||
<p>This is used by the <code>_approximate</code> and <code>_correct</code> 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 ‘<code>numeric</code>’, 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-example">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 ‘<code>ESC-6 TAB</code>’), up to six errors are
|
||
accepted. Hence with a value of ‘<code>0 numeric</code>’, no correcting completion
|
||
will be attempted unless a numeric argument is given.</p>
|
||
<p>If the value contains the string ‘<code>not-numeric</code>’, 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, ‘<code>2 not-numeric</code>’ 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 ‘<code>2 numeric</code>’.</p>
|
||
<p><span id="index-max_002dmatches_002dwidth_002c-completion-style"></span></p>
|
||
<p><code>max-matches-width</code></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 <code>verbose</code> 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><code>menu</code></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 ‘<code>default</code>’ tag.</p>
|
||
<p>If none of the values found in this way is ‘true’ but at least one is
|
||
set to ‘<code>auto</code>’, the shell behaves as if the <code>AUTO_MENU</code> option is set.</p>
|
||
<p>If one of the values is explicitly set to ‘false’, menu completion will
|
||
be explicitly turned off, overriding the <code>MENU_COMPLETE</code> option and
|
||
other settings.</p>
|
||
<p>In the form ‘<code>yes=``num</code>’, where ‘<code>yes</code>’ may be any of the ‘true’ values
|
||
(‘<code>yes</code>’, ‘<code>true</code>’, ‘<code>on</code>’ and ‘<code>1</code>’), menu completion will be turned on
|
||
if there are at least <code>num</code> matches. In the form ‘<code>yes=long</code>’, 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 ‘<code>yes=long-list</code>’ (Typically, the value ‘<code>select=long-list</code>’
|
||
described later is more useful as it provides control over scrolling.)</p>
|
||
<p>Similarly, with any of the ‘false’ values (as in ‘<code>no=10</code>’), 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 <code>zsh/complist</code> module. The following values may appear either
|
||
alongside or instead of the values above.</p>
|
||
<p>If the value contains the string ‘<code>select</code>’, menu selection will be
|
||
started unconditionally.</p>
|
||
<p>In the form ‘<code>select=``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‘<code>no-select</code>’.</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 ‘<code>select=long</code>’. To start
|
||
menu selection even if the current widget only performs listing, use the
|
||
value ‘<code>select=long-list</code>’.</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 ‘<code>yes=</code>’ and ‘<code>select=</code>’ may be given twice, once with a number
|
||
and once with ‘<code>long</code>’ or ‘<code>long-list</code>’.</p>
|
||
<p>Finally, it is possible to activate two special modes of menu selection.
|
||
The word ‘<code>interactive</code>’ 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 ‘<code>search</code>’ does
|
||
the same for incremental search mode. To select backward incremental
|
||
search, include the string ‘<code>search-backward</code>’.</p>
|
||
<p><span id="index-muttrc_002c-completion-style"></span></p>
|
||
<p><code>muttrc</code></p>
|
||
<p>If set, gives the location of the mutt configuration file. It defaults
|
||
to ‘<code>~/.muttrc</code>’.</p>
|
||
<p><span id="index-numbers_002c-completion-style"></span></p>
|
||
<p><code>numbers</code></p>
|
||
<p>This is used with the <code>jobs</code> 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 ‘<code>1</code>’, 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><code>old-list</code></p>
|
||
<p>This is used by the <code>_oldlist</code> completer. If it is set to ‘<code>always</code>’,
|
||
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 ‘<code>never</code>’, giving the behaviour without the
|
||
<code>_oldlist</code> 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 <code>_oldlist</code>. 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 <code>^Xc</code> to use the <code>_correct_word</code> widget,
|
||
which generates a list of corrections for the word under the cursor.
|
||
Usually, typing <code>^D</code> would generate a standard list of completions for
|
||
the word on the command line, and show that. With <code>_oldlist</code>, it will
|
||
instead show the list of corrections already generated.</p>
|
||
<p>As another example consider the <code>_match</code> completer: with the
|
||
<code>insert-unambiguous</code> 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 <code>_oldlist</code> completer and setting this
|
||
style to <code>_match</code>, 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><code>old-matches</code></p>
|
||
<p>This is used by the <code>_all_matches</code> 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 ‘<code>only</code>’. If the value is ‘<code>only</code>’,
|
||
<code>_all_matches</code> 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 <code>_all_matches</code>
|
||
completer unconditionally. One possible use is for either this style or
|
||
the <code>completer</code> style to be defined with the <code>-e</code> option to <code>zstyle</code> to
|
||
make the style conditional.</p>
|
||
<p><span id="index-old_002dmenu_002c-completion-style"></span></p>
|
||
<p><code>old-menu</code></p>
|
||
<p>This is used by the <code>_oldlist</code> completer. It controls how menu
|
||
completion behaves when a completion has already been inserted and the
|
||
user types a standard completion key such as <code>TAB</code>. The default
|
||
behaviour of <code>_oldlist</code> 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
|
||
<code>_oldlist</code> completer.</p>
|
||
<p>For example, suppose you type <code>^Xc</code> 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 <code>TAB</code> at this point would start
|
||
trying to complete the line as it now appears. With <code>_oldlist</code>, it
|
||
instead continues to cycle through the list of corrections.</p>
|
||
<p><span id="index-original_002c-completion-style"></span></p>
|
||
<p><code>original</code></p>
|
||
<p>This is used by the <code>_approximate</code> and <code>_correct</code> 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 <code>correct-``num</code> or <code>approximate-``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><code>packageset</code></p>
|
||
<p>This style is used when completing arguments of the Debian ‘<code>dpkg</code>’
|
||
program. It contains an override for the default package set for a given
|
||
context. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 ‘<code>dpkg -``-status</code>’.</p>
|
||
<p><span id="index-path_002c-completion-style"></span></p>
|
||
<p><code>path</code></p>
|
||
<p>The function that completes color names uses this style with the
|
||
<code>colors</code> tag. The value should be the pathname of a file containing
|
||
color names in the format of an X11 <code>rgb.txt</code> 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><code>path-completion</code></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, <code>/u/b/z</code> can be completed to
|
||
<code>/usr/bin/zsh</code>. Explicitly setting this style to ‘false’ inhibits this
|
||
behaviour for path components up to the <code>/</code> before the cursor; this
|
||
overrides the setting of <code>accept-exact-dirs</code>.</p>
|
||
<p>Even with the style set to ‘false’, it is still possible to complete
|
||
multiple paths by setting the option <code>COMPLETE_IN_WORD</code> and moving the
|
||
cursor back to the first component in the path to be completed. For
|
||
example, <code>/u/b/z</code> can be completed to <code>/usr/bin/zsh</code> if the cursor is
|
||
after the <code>/u</code>.</p>
|
||
<p><span id="index-pine_002ddirectory_002c-completion-style"></span></p>
|
||
<p><code>pine-directory</code></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><code>ports</code></p>
|
||
<p>A list of Internet service names (network ports) to complete. If this is
|
||
not set, service names are taken from the file ‘<code>/etc/services</code>’.</p>
|
||
<p><span id="index-prefix_002dhidden_002c-completion-style"></span></p>
|
||
<p><code>prefix-hidden</code></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><code>prefix-needed</code></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 <code>options</code>, <code>signals</code>, <code>jobs</code>,
|
||
<code>functions</code>, and <code>parameters</code> completion tags.</p>
|
||
<p>For command options, this means that the initial ‘<code>-</code>’, ‘<code>+</code>’, or
|
||
‘<code>-``-</code>’ must be typed explicitly before option names will be
|
||
completed.</p>
|
||
<p>For signals, an initial ‘<code>-</code>’ is required before signal names will be
|
||
completed.</p>
|
||
<p>For jobs, an initial ‘<code>%</code>’ is required before job names will be
|
||
completed.</p>
|
||
<p>For function and parameter names, an initial ‘<code>_</code>’ or ‘<code>.</code>’ 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 <code>function</code> and
|
||
<code>parameter</code> completions, and ‘true’ otherwise.</p>
|
||
<p><span id="index-preserve_002dprefix_002c-completion-style"></span></p>
|
||
<p><code>preserve-prefix</code></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 ‘<code>//</code>’ (double slash) has a special meaning; setting this
|
||
style to the string ‘<code>//</code>’ will preserve it. As another example, setting
|
||
this style to ‘<code>?:/</code>’ under Cygwin would allow completion after
|
||
‘<code>a:/...</code>’ and so on.</p>
|
||
<p><span id="index-range_002c-completion-style"></span></p>
|
||
<p><code>range</code></p>
|
||
<p>This is used by the <code>_history</code> completer and the
|
||
<code>_history_complete_word</code> 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``:``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><code>recursive-files</code></p>
|
||
<p>If this style is set, its value is an array of patterns to be tested
|
||
against ‘<code>$PWD/</code>’: 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 <code>$PWD/</code> 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 <code>**/*(/)</code> 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
|
||
‘<code>*/.git/*</code>’.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*' recursive-files '*/zsh/*'
|
||
</code></pre>
|
||
</div>
|
||
<p>If the current directory is <code>/home/pws/zsh/Src</code>, then <code>zle_tr</code><em>TAB</em> can
|
||
be completed to <code>Zle/zle_tricky.c</code>.</p>
|
||
<p><span id="index-regular_002c-completion-style"></span></p>
|
||
<p><code>regular</code></p>
|
||
<p>This style is used by the <code>_expand_alias</code> 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 ‘<code>always</code>’, regular
|
||
aliases will be expanded even if not in command position.</p>
|
||
<p><span id="index-rehash_002c-completion-style"></span></p>
|
||
<p><code>rehash</code></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
|
||
<code>rehash</code> 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><code>remote-access</code></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 <code>CVS</code> 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><code>remove-all-dups</code></p>
|
||
<p>The <code>_history_complete_word</code> bindable command and the <code>_history</code>
|
||
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><code>select-prompt</code></p>
|
||
<p>If this is set for the <code>default</code> tag, its value will be displayed during
|
||
menu selection (see the <code>menu</code> style above) when the completion list
|
||
does not fit on the screen as a whole. The same escapes as for the
|
||
<code>list-prompt</code> 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><code>select-scroll</code></p>
|
||
<p>This style is tested for the <code>default</code> tag and determines how a
|
||
completion list is scrolled during a menu selection (see the <code>menu</code>
|
||
style above) when the completion list does not fit on the screen as a
|
||
whole. If the value is ‘<code>0</code>’ (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><code>separate-sections</code></p>
|
||
<p>This style is used with the <code>manuals</code> tag when completing names of
|
||
manual pages. If it is ‘true’, entries for different sections are added
|
||
separately using tag names of the form ‘<code>manual.``X</code>’, where <code>X</code> is the
|
||
section number. When the <code>group-name</code> style is also in effect, pages
|
||
from different sections will appear separately. This style is also used
|
||
similarly with the <code>words</code> style when completing words for the dict
|
||
command. It allows words from different dictionary databases to be added
|
||
separately. The default for this style is ‘false’.</p>
|
||
<p><span id="index-show_002dambiguity_002c-completion-style"></span></p>
|
||
<p><code>show-ambiguity</code></p>
|
||
<p>If the <code>zsh/complist</code> 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
|
||
<code>list-colors</code> 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><code>show-completer</code></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><code>single-ignored</code></p>
|
||
<p>This is used by the <code>_ignored</code> completer when there is only one match.
|
||
If its value is ‘<code>show</code>’, the single match will be displayed but not
|
||
inserted. If the value is ‘<code>menu</code>’, 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><code>sort</code></p>
|
||
<p>This allows the standard ordering of matches to be overridden.</p>
|
||
<p>If its value is ‘<code>true</code>’ or ‘<code>false</code>’, sorting is enabled or disabled.
|
||
Additionally the values associated with the ‘<code>-o</code>’ option to <code>compadd</code>
|
||
can also be listed: <code>match</code>, <code>nosort</code>, <code>numeric</code>, <code>reverse</code>. 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 ‘<code>true</code>’ 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 <code>_expand</code> completer, if it is set to ‘true’, the expansions
|
||
generated will always be sorted. If it is set to ‘<code>menu</code>’, 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><code>special-dirs</code></p>
|
||
<p>Normally, the completion code will not produce the directory names ‘<code>.</code>’
|
||
and ‘<code>..</code>’ as possible completions. If this style is set to ‘true’, it
|
||
will add both ‘<code>.</code>’ and ‘<code>..</code>’ as possible completions; if it is set to
|
||
‘<code>..</code>’, only ‘<code>..</code>’ will be added.</p>
|
||
<p>The following example sets <code>special-dirs</code> to ‘<code>..</code>’ when the current
|
||
prefix is empty, is a single ‘<code>.</code>’, or consists only of a path beginning
|
||
with ‘<code>../</code>’. Otherwise the value is ‘false’.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle -e ':completion:*' special-dirs \
|
||
'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-squeeze_002dslashes_002c-completion-style"></span></p>
|
||
<p><code>squeeze-slashes</code></p>
|
||
<p>If set to ‘true’, sequences of slashes in filename paths (for example in
|
||
‘<code>foo//bar</code>’) 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 ‘<code>*</code>’ between the slashes.</p>
|
||
<p><span id="index-stop_002c-completion-style"></span></p>
|
||
<p><code>stop</code></p>
|
||
<p>If set to ‘true’, the <code>_history_complete_word</code> bindable command will
|
||
stop once when reaching the beginning or end of the history. Invoking
|
||
<code>_history_complete_word</code> will then wrap around to the opposite end of
|
||
the history. If this style is set to ‘false’ (the default),
|
||
<code>_history_complete_word</code> will loop immediately as in a menu completion.</p>
|
||
<p><span id="index-strip_002dcomments_002c-completion-style"></span></p>
|
||
<p><code>strip-comments</code></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><code>subst-globs-only</code></p>
|
||
<p>This is used by the <code>_expand</code> 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 <code>substitute</code> 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><code>substitute</code></p>
|
||
<p>This boolean style controls whether the <code>_expand</code> 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><code>suffix</code></p>
|
||
<p>This is used by the <code>_expand</code> 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 ‘<code>~foo</code>’ or ‘<code>$foo</code>’ rather than ‘<code>~foo/</code>’ or ‘<code>$foo/bar</code>’, 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><code>tag-order</code></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 <code>file-patterns</code> style for an exception
|
||
to this behavior.)</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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>
|
||
<ul>
|
||
<li>
|
||
<p><code>-</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>!</code> <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>
|
||
</li>
|
||
<li>
|
||
<p><code>tag``:``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 <code>!</code>.</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>
|
||
</li>
|
||
<li>
|
||
<p><code>tag``:``label``:``description</code><br />
|
||
As before, but <code>description</code> will replace the ‘<code>%d</code>’ in the value of
|
||
the <code>format</code> style instead of the default description supplied by
|
||
the completion function. Spaces in the description must be quoted
|
||
with a backslash. A ‘<code>%d</code>’ appearing in <code>description</code> is replaced
|
||
with the description given by the completion function.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In any of the forms above the tag may be a pattern or several patterns
|
||
in the form ‘<code>{``pat1``,``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-example">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 <code>functions</code> tag
|
||
will be replaced by <code>functions-non-comp</code>. The <code>ignored-patterns</code> style
|
||
is set for this tag to exclude functions starting with an underscore. If
|
||
there are no matches, the second value of the <code>tag-order</code> 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-example">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 <code>group-names</code> style set, options beginning with ‘<code>-``-</code>’,
|
||
options beginning with a single ‘<code>-</code>’ or ‘<code>+</code>’ 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 <code>matcher-list</code> 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 <code>foo</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>foo</code> are tried using
|
||
the normal tag name. If that generates no matches, the second value of
|
||
<code>tag-order</code> is used, which tries all tags again except that this time
|
||
each has <code>-case</code> appended to its name for lookup of styles. Hence this
|
||
time the value for the <code>matcher</code> style from the second call to <code>zstyle</code>
|
||
in the example is used to make completion case-insensitive.</p>
|
||
<p>It is possible to use the <code>-e</code> option of the <code>zstyle</code> builtin command to
|
||
specify conditions for the use of particular tags. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>PREFIX</code> 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
|
||
<code>reply</code> 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 <code>tag-order</code> style has been defined for a context, the strings
|
||
‘<code>(|*-)argument-* (|*-)option-* values</code>’ and ‘<code>options</code>’ 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><code>urls</code></p>
|
||
<p>This is used together with the <code>urls</code> 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 ‘<code>http</code>’,
|
||
‘<code>ftp</code>’, ‘<code>bookmark</code>’ 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-example">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 ‘<code>netscape</code>’ or
|
||
‘<code>lynx</code>’. Note, however, that access methods and files are completed
|
||
separately, so if the <code>hosts</code> style is set hosts can be completed
|
||
without reference to the <code>urls</code> style.</p>
|
||
<p>See the description in the function <code>_urls</code> itself for more information
|
||
(e.g. ‘<code>more $^fpath/_urls(N)</code>’).</p>
|
||
<p><span id="index-use_002dcache_002c-completion-style"></span></p>
|
||
<p><code>use-cache</code></p>
|
||
<p>If this is set, the completion caching layer is activated for any
|
||
completions which use it (via the <code>_store_cache</code>, <code>_retrieve_cache</code>, and
|
||
<code>_cache_invalid</code> functions). The directory containing the cache files
|
||
can be changed with the <code>cache-path</code> style.</p>
|
||
<p><span id="index-use_002dcompctl_002c-completion-style"></span></p>
|
||
<p><code>use-compctl</code></p>
|
||
<p>If this style is set to a string <em>not</em> equal to <code>false</code>, <code>0</code>, <code>no</code>, and
|
||
<code>off</code>, the completion system may use any completion specifications
|
||
defined with the <code>compctl</code> builtin command. If the style is unset, this
|
||
is done only if the <code>zsh/compctl</code> module is loaded. The string may also
|
||
contain the substring ‘<code>first</code>’ to use completions defined with
|
||
‘<code>compctl -T</code>’, and the substring ‘<code>default</code>’ to use the completion
|
||
defined with ‘<code>compctl -D</code>’.</p>
|
||
<p>Note that this is only intended to smooth the transition from <code>compctl</code>
|
||
to the new completion system and may disappear in the future.</p>
|
||
<p>Note also that the definitions from <code>compctl</code> will only be used if there
|
||
is no specific completion function for the command in question. For
|
||
example, if there is a function <code>_foo</code> to complete arguments to the
|
||
command <code>foo</code>, <code>compctl</code> will never be invoked for <code>foo</code>. However, the
|
||
<code>compctl</code> version will be tried if <code>foo</code> only uses default completion.</p>
|
||
<p><span id="index-use_002dip_002c-completion-style"></span></p>
|
||
<p><code>use-ip</code></p>
|
||
<p>By default, the function <code>_hosts</code> 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
|
||
<code>hosts</code> 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><code>users</code></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><code>users-hosts</code></p>
|
||
<p>The values of this style should be of the form ‘<code>user``@``host</code>’ or
|
||
‘<code>user``:``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 <code>rlogin</code> and <code>ssh</code>, by using the <code>my-accounts</code> tag.
|
||
Similarly, values for sets of commands which usually refer to the
|
||
accounts of other people, such as <code>talk</code> and <code>finger</code>, can be grouped by
|
||
using the <code>other-accounts</code> tag. More ambivalent commands may use the
|
||
<code>accounts</code> tag.</p>
|
||
<p><span id="index-users_002dhosts_002dports_002c-completion-style"></span></p>
|
||
<p><code>users-hosts-ports</code></p>
|
||
<p>Like <code>users-hosts</code> but used for commands like <code>telnet</code> and containing
|
||
strings of the form ‘<code>user``@``host``:``port</code>’.</p>
|
||
<p><span id="index-verbose_002c-completion-style"></span></p>
|
||
<p><code>verbose</code></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><code>word</code></p>
|
||
<p>This is used by the <code>_list</code> 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 <code>compinit</code> redefines all the widgets which
|
||
perform completion to call the supplied widget function
|
||
<code>_main_complete</code>. This function acts as a wrapper calling the so-called
|
||
‘completer’ functions that generate matches. If <code>_main_complete</code> 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 <code>completer</code> style. For
|
||
example, to use normal completion and correction if that doesn’t
|
||
generate any matches:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*' completer _complete _correct
|
||
</code></pre>
|
||
</div>
|
||
<p>after calling <code>compinit</code>. The default value for this style is
|
||
‘<code>_complete _ignored</code>’, i.e. normally only ordinary completion is
|
||
tried, first with the effect of the <code>ignored-patterns</code> style and then
|
||
without it. The <code>_main_complete</code> 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
|
||
<code>_main_complete</code> function returns.</p>
|
||
<p>If the first argument to <code>_main_complete</code> 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 ‘<code>:completion::complete:``...</code>’.</p>
|
||
<p><span id="index-completion-system_002c-completers"></span></p>
|
||
<p><span id="index-_005fall_005fmatches"></span></p>
|
||
<p><code>_all_matches</code></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
|
||
<code>avoid-completer</code> and <code>old-matches</code> styles described above.</p>
|
||
<p>It may be useful to use the <code>_generic</code> function described below to bind
|
||
<code>_all_matches</code> to its own keystroke, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>^Xa</code> 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-example">zstyle ':completion:all-matches::::' completer \
|
||
_all_matches _complete
|
||
zstyle ':completion:all-matches:*' insert true
|
||
</code></pre>
|
||
</div>
|
||
<p>In this case the <code>old-matches</code> style should not be set.</p>
|
||
<p><span id="index-_005fapproximate"></span></p>
|
||
<p><code>_approximate</code></p>
|
||
<p>This is similar to the basic <code>_complete</code> completer but allows the
|
||
completions to undergo corrections. The maximum number of errors can be
|
||
specified by the <code>max-errors</code> 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 <code>_complete</code> completer:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>corrections</code> and <code>original</code> when
|
||
generating the possible corrections and the original string. The
|
||
<code>format</code> style for the former may contain the additional sequences
|
||
‘<code>%e</code>’ and ‘<code>%o</code>’ 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 <code>max-errors</code> 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
|
||
‘<code>approximate-1</code>’, on the second try ‘<code>approximate-2</code>’, and so on.</p>
|
||
<p>When <code>_approximate</code> is called from another function, the number of
|
||
errors to accept may be passed with the <code>-a</code> option. The argument is in
|
||
the same format as the <code>max-errors</code> style, all in one string.</p>
|
||
<p>Note that this completer (and the <code>_correct</code> 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 <code>completer</code> style
|
||
using the <code>-e</code> 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-example">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 <code>HISTNO</code> parameter and the <code>BUFFER</code> and <code>CURSOR</code> 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 <code>_ignored</code>, <code>_correct</code> and <code>_approximate</code>
|
||
completers called.</p>
|
||
<p><span id="index-_005fcanonical_005fpaths"></span></p>
|
||
<p><code>_canonical_paths</code> [ <code>-A</code> <code>var</code> ] [ <code>-N</code> ] [ <code>-MJV12nfX</code> ] <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 <code>..</code>’s are present in the word to be completed; and some paths got
|
||
from symlinks).</p>
|
||
<p><code>-A</code>, if specified, takes the paths from the array variable specified.
|
||
Paths can also be specified on the command line as shown above. <code>-N</code>, if
|
||
specified, prevents canonicalizing the paths given before using them for
|
||
completion, in case they are already so. The options <code>-M</code>, <code>-J</code>, <code>-V</code>,
|
||
<code>-1</code>, <code>-2</code>, <code>-n</code>, <code>-F</code>, <code>-X</code> are passed to <code>compadd</code>.</p>
|
||
<p>See <code>_description</code> for a description of <code>tag</code> and <code>descr</code>.</p>
|
||
<p><span id="index-_005fcmdambivalent"></span></p>
|
||
<p><code>_cmdambivalent</code></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 <code>/usr/bin/env</code>) if there are two
|
||
or more remaining positional arguments on the command line, and as a
|
||
quoted command string (in the manner of <code>system(...)</code>) otherwise. See
|
||
also <code>_cmdstring</code> and <code>_precommand</code>.</p>
|
||
<p>This function takes no arguments.</p>
|
||
<p><span id="index-_005fcmdstring"></span></p>
|
||
<p><code>_cmdstring</code></p>
|
||
<p>Completes an external command as a single argument, as for
|
||
<code>system(...)</code>.</p>
|
||
<p><span id="index-_005fcomplete"></span></p>
|
||
<p><code>_complete</code></p>
|
||
<p>This completer generates all possible completions in a context-sensitive
|
||
manner, i.e. using the settings defined with the <code>compdef</code> function
|
||
explained above and the current settings of all special parameters. This
|
||
gives the normal completion behaviour.</p>
|
||
<p>To complete arguments of commands, <code>_complete</code> uses the utility function
|
||
<code>_normal</code>, 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 <code>#compdef</code> tag.</p>
|
||
<p>Before trying to find a function for a specific context, <code>_complete</code>
|
||
checks if the parameter ‘<code>compcontext</code>’ is set. Setting ‘<code>compcontext</code>’
|
||
allows the usual completion dispatching to be overridden which is useful
|
||
in places such as a function that uses <code>vared</code> 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 ‘<code>values</code>’ and the description
|
||
‘<code>value</code>’. 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 ‘<code>compcontext</code>’ is set to a string
|
||
containing colons, it should be of the form
|
||
‘<code>tag``:``descr``:``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 <code>_arguments</code>
|
||
utility function described below.</p>
|
||
<p>Finally, if ‘<code>compcontext</code>’ 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 <code>-command-line-</code> 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><code>_correct</code></p>
|
||
<p>Generate corrections, but not completions, for the current word; this is
|
||
similar to <code>_approximate</code> 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 <code>_approximate</code>, but the completer
|
||
field in the context name is <code>correct</code>.</p>
|
||
<p>For example, with:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>_correct</code> is called as a function, the number of errors to accept
|
||
may be given following the <code>-a</code> option. The argument is in the same form
|
||
a values to the <code>accept</code> style, all in one string.</p>
|
||
<p>This completer function is intended to be used without the
|
||
<code>_approximate</code> completer or, as in the example, just before it. Using it
|
||
after the <code>_approximate</code> completer is useless since <code>_approximate</code> will
|
||
at least generate the corrected strings generated by the <code>_correct</code>
|
||
completer — and probably more.</p>
|
||
<p><span id="index-_005fexpand"></span></p>
|
||
<p><code>_expand</code></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
|
||
<code>complete-word</code>, not <code>expand-or-complete</code> (the default binding for
|
||
<code>TAB</code>), 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 <code>_complete</code> completer function.</p>
|
||
<p>The tags used when generating expansions are <code>all-expansions</code> for the
|
||
string containing all possible expansions, <code>expansions</code> when adding the
|
||
possible expansions as single matches and <code>original</code> when adding the
|
||
original string from the line. The order in which these strings are
|
||
generated, if at all, can be controlled by the <code>group-order</code> and
|
||
<code>tag-order</code> styles, as usual.</p>
|
||
<p>The format string for <code>all-expansions</code> and for <code>expansions</code> may contain
|
||
the sequence ‘<code>%o</code>’ which will be replaced by the original string from
|
||
the line.</p>
|
||
<p>The kind of expansion to be tried is controlled by the <code>substitute</code>,
|
||
<code>glob</code> and <code>subst-globs-only</code> styles.</p>
|
||
<p>It is also possible to call <code>_expand</code> as a function, in which case the
|
||
different modes may be selected with options: <code>-s</code> for <code>substitute</code>,
|
||
<code>-g</code> for <code>glob</code> and <code>-o</code> for <code>subst-globs-only</code>.</p>
|
||
<p><span id="index-_005fexpand_005falias"></span></p>
|
||
<p><code>_expand_alias</code></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 <code>regular</code>, <code>global</code> and <code>disabled</code>.</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><code>_extensions</code></p>
|
||
<p>If the cursor follows the string ‘<code>*.</code>’, 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
|
||
<code>_expand</code> to expand the pattern. The standard <code>add-space</code> and
|
||
<code>prefix-hidden</code> styles are observed.</p>
|
||
<p><span id="index-_005fexternal_005fpwds"></span></p>
|
||
<p><code>_external_pwds</code></p>
|
||
<p>Completes current directories of other zsh processes belonging to the
|
||
current user.</p>
|
||
<p>This is intended to be used via <code>_generic</code>, bound to a custom key
|
||
combination. Note that pattern matching is enabled so matching is
|
||
performed similar to how it works with the <code>_match</code> completer.</p>
|
||
<p><span id="index-_005fhistory"></span></p>
|
||
<p><code>_history</code></p>
|
||
<p>Complete words from the shell’s command history. This completer can be
|
||
controlled by the <code>remove-all-dups</code>, and <code>sort</code> styles as for the
|
||
<code>_history_complete_word</code> 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><code>_ignored</code></p>
|
||
<p>The <code>ignored-patterns</code> 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
|
||
<code>ignored-patterns</code> 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 <code>_prefix</code> completer. The <code>single-ignored</code> style is
|
||
also available as described above.</p>
|
||
<p><span id="index-_005flist"></span></p>
|
||
<p><code>_list</code></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 <code>condition</code> and <code>word</code>, see <a href="#Completion-System-Configuration">Completion
|
||
System Configuration</a>.</p>
|
||
<p><span id="index-_005fmatch"></span></p>
|
||
<p><code>_match</code></p>
|
||
<p>This completer is intended to be used after the <code>_complete</code> 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
|
||
<code>GLOB_COMPLETE</code> option.</p>
|
||
<p>Normally completion will be performed by taking the pattern from the
|
||
line, inserting a ‘<code>*</code>’ at the cursor position and comparing the
|
||
resulting pattern with the possible completions generated. This can be
|
||
modified with the <code>match-original</code> style described above.</p>
|
||
<p>The generated matches will be offered in a menu completion unless the
|
||
<code>insert-unambiguous</code> 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 <code>matcher-list</code> and <code>matcher</code>) will not
|
||
be used.</p>
|
||
<p><span id="index-_005fmenu"></span></p>
|
||
<p><code>_menu</code></p>
|
||
<p>This completer was written as simple example function to show how menu
|
||
effect of disabling menu selection which can be useful with <code>_generic</code>
|
||
based widgets. It should be used as the first completer in the list.
|
||
Note that this is independent of the setting of the <code>MENU_COMPLETE</code>
|
||
option and does not work with the other menu completion widgets such as
|
||
<code>reverse-menu-complete</code>, or <code>accept-and-menu-complete</code>.</p>
|
||
<p><span id="index-_005foldlist"></span></p>
|
||
<p><code>_oldlist</code></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:
|
||
<code>old-list</code> and <code>old-menu</code>, see <a href="#Completion-System-Configuration">Completion System
|
||
Configuration</a>.</p>
|
||
<p><span id="index-_005fprecommand"></span></p>
|
||
<p><code>_precommand</code></p>
|
||
<p>Complete an external command in word-separated arguments, as for <code>exec</code>
|
||
and <code>/usr/bin/env</code>.</p>
|
||
<p><span id="index-_005fprefix"></span></p>
|
||
<p><code>_prefix</code></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 <code>expand-or-complete-prefix</code> command.</p>
|
||
<p>The <code>completer</code> 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
|
||
<code>_prefix</code> 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 <code>_prefix</code> will be called.</p>
|
||
<p>For example, consider this global <code>completer</code> style:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*' completer \
|
||
_complete _prefix _correct _prefix:foo
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, the <code>_prefix</code> completer tries normal completion but ignoring the
|
||
suffix. If that doesn’t generate any matches, and neither does the call
|
||
to the <code>_correct</code> completer after it, <code>_prefix</code> 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 ‘<code>foo</code>’.</p>
|
||
<p>To use <code>_prefix</code> as the last resort and try only normal completion when
|
||
it is invoked:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*' completer _complete ... _prefix
|
||
zstyle ':completion::prefix:*' completer _complete
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>add-space</code> style is also respected. If it is set to ‘true’ then
|
||
<code>_prefix</code> will insert a space between the matches generated (if any) and
|
||
the suffix.</p>
|
||
<p>Note that this completer is only useful if the <code>COMPLETE_IN_WORD</code> 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><code>_user_expand</code></p>
|
||
<p>This completer behaves similarly to the <code>_expand</code> completer but instead
|
||
performs expansions defined by users. The styles <code>add-space</code> and <code>sort</code>
|
||
styles specific to the <code>_expand</code> completer are usable with
|
||
<code>_user_expand</code> in addition to other styles handled more generally by the
|
||
completion system. The tag <code>all-expansions</code> is also available.</p>
|
||
<p>The expansion depends on the array style <code>user-expand</code> 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>
|
||
<ul>
|
||
<li>
|
||
<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 <code>$</code>, 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>
|
||
</li>
|
||
<li>
|
||
<p><code>_func</code><br />
|
||
<code>_func</code> is the name of a shell function whose name must begin with
|
||
<code>_</code> 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 <code>reply</code> to a
|
||
list of expansions. Optionally, it can set <code>REPLY</code> to a word that
|
||
will be used as a description for the set of expansions. The return
|
||
status of the function is irrelevant.</p>
|
||
</li>
|
||
</ul>
|
||
<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><code>_bash_completions</code></p>
|
||
<p>This function is used by two widgets, <code>_bash_complete-word</code> and
|
||
<code>_bash_list-choices</code>. It exists to provide compatibility with completion
|
||
bindings in bash. The last character of the binding determines what is
|
||
completed: ‘<code>!</code>’, command names; ‘<code>$</code>’, environment variables; ‘<code>@</code>’,
|
||
host names; ‘<code>/</code>’, file names; ‘<code>~</code>’ user names. In bash, the binding
|
||
preceded by ‘<code>\e</code>’ gives completion, and preceded by ‘<code>^X</code>’ lists
|
||
options. As some of these bindings clash with standard zsh bindings,
|
||
only ‘<code>\e~</code>’ and ‘<code>^X~</code>’ are bound by default. To add the rest, the
|
||
following should be added to <code>.zshrc</code> after <code>compinit</code> has been run:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 ‘<code>~</code>’ 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><code>_correct_filename</code> (<code>^XC</code>)</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><code>_correct_word</code> (<code>^Xc</code>)</p>
|
||
<p>Performs correction of the current argument using the usual contextual
|
||
completions as possible choices. This stores the string ‘<code>correct-word</code>’
|
||
in the <code>function</code> field of the context name and then calls the
|
||
<code>_correct</code> completer.</p>
|
||
<p><span id="index-_005fexpand_005falias-_0028_005eXa_0029"></span></p>
|
||
<p><code>_expand_alias</code> (<code>^Xa</code>)</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 <code>regular</code>, <code>global</code> and
|
||
<code>disabled</code>.</p>
|
||
<p>When used as a bindable command there is one additional feature that can
|
||
be selected by setting the <code>complete</code> style to ‘true’. In this case, if
|
||
the word is not the name of an alias, <code>_expand_alias</code> 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 <code>_expand_alias</code> once
|
||
more will expand the now-complete alias name.</p>
|
||
<p><span id="index-_005fexpand_005fword-_0028_005eXe_0029"></span></p>
|
||
<p><code>_expand_word</code> (<code>^Xe</code>)</p>
|
||
<p>Performs expansion on the current word: equivalent to the standard
|
||
<code>expand-word</code> command, but using the <code>_expand</code> completer. Before calling
|
||
it, the <code>function</code> field of the context is set to ‘<code>expand-word</code>’.</p>
|
||
<p><span id="index-_005fgeneric"></span></p>
|
||
<p><code>_generic</code></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-example">zle -C foo complete-word _generic
|
||
bindkey '...' foo
|
||
zstyle ':completion:foo:*' menu yes select=1
|
||
</code></pre>
|
||
</div>
|
||
<p>Note in particular that the <code>completer</code> style may be set for the context
|
||
in order to change the set of functions used to generate possible
|
||
matches. If <code>_generic</code> is called with arguments, those are passed
|
||
through to <code>_main_complete</code> as the list of completers in place of those
|
||
defined by the <code>completer</code> style.</p>
|
||
<p><span id="index-_005fhistory_005fcomplete_005fword-_0028_005ce_002f_0029"></span></p>
|
||
<p><code>_history_complete_word</code> (<code>\e/</code>)</p>
|
||
<p>Complete words from the shell’s command history. This uses the <code>list</code>,
|
||
<code>remove-all-dups</code>, <code>sort</code>, and <code>stop</code> styles.</p>
|
||
<p><span id="index-_005fmost_005frecent_005ffile-_0028_005eXm_0029"></span></p>
|
||
<p><code>_most_recent_file</code> (<code>^Xm</code>)</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><code>_next_tags</code> (<code>^Xn</code>)</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 <code>tag-order</code> 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><code>_read_comp</code> (<code>^X^R</code>)</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 ‘<code>_</code>’, for example ‘<code>_files -/</code>’, 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
|
||
<code>compadd</code> 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: ‘<code>DEL</code>’ and ‘<code>^H</code>’ delete the last character; ‘<code>^U</code>’ deletes the
|
||
line, and ‘<code>^C</code>’ and ‘<code>^G</code>’ abort the function, while ‘<code>RET</code>’ 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 <code>_read_comp</code> will use the
|
||
existing string instead of reading a new one. To force a new string to
|
||
be read, call <code>_read_comp</code> with a numeric argument.</p>
|
||
<p><span id="index-_005fcomplete_005fdebug-_0028_005eX_003f_0029"></span></p>
|
||
<p><code>_complete_debug</code> (<code>^X?</code>)</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><code>_complete_help</code> (<code>^Xh</code>)</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 <code>1</code> (as in ‘<code>ESC-2 ^Xh</code>’), 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><code>_complete_help_generic</code></p>
|
||
<p>Unlike other commands listed here, this must be created as a normal ZLE
|
||
widget rather than a completion widget (i.e. with <code>zle -N</code>). It is used
|
||
for generating help with a widget bound to the <code>_generic</code> 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
|
||
<code>_generic</code> widget. That widget will be executed, and information
|
||
provided in the same format that the <code>_complete_help</code> widget displays
|
||
for contextual completion.</p>
|
||
<p>If the widget’s name contains <code>debug</code>, for example if it is created as
|
||
‘<code>zle -N _complete_debug_generic _complete_help_generic</code>’, it will
|
||
read and execute the keystring for a generic widget as before, but then
|
||
generate debugging information as done by <code>_complete_debug</code> for
|
||
contextual completion.</p>
|
||
<p>If the widget’s name contains <code>noread</code>, 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
|
||
<code>ZSH_TRACE_GENERIC_WIDGET</code> which is read by <code>_generic</code>. Unsetting the
|
||
parameter cancels any pending effect of the <code>noread</code> form.</p>
|
||
<p>For example, after executing the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N _complete_debug_generic _complete_help_generic
|
||
bindkey '^x:' _complete_debug_generic
|
||
</code></pre>
|
||
</div>
|
||
<p>typing ‘<code>C-x :</code>’ 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><code>_complete_tag</code> (<code>^Xt</code>)</p>
|
||
<p>This widget completes symbol tags created by the <code>etags</code> or <code>ctags</code>
|
||
programmes (note there is no connection with the completion system’s
|
||
tags) stored in a file <code>TAGS</code>, in the format used by <code>etags</code>, or <code>tags</code>,
|
||
in the format created by <code>ctags</code>. It will look back up the path
|
||
hierarchy for the first occurrence of either file; if both exist, the
|
||
file <code>TAGS</code> is preferred. You can specify the full path to a <code>TAGS</code> or
|
||
<code>tags</code> file by setting the parameter <code>$TAGSFILE</code> or <code>$tagsfile</code>
|
||
respectively. The corresponding completion tags used are <code>etags</code> and
|
||
<code>vtags</code>, 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 <code>Base</code> 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><code>_absolute_command_paths</code></p>
|
||
<p>This function completes external commands as absolute paths (unlike
|
||
<code>_command_names -e</code> which completes their basenames). It takes no
|
||
arguments.</p>
|
||
<p><span id="index-_005fall_005flabels"></span></p>
|
||
<p><code>_all_labels</code> [ <code>-x</code> ] [ <code>-12VJ</code> ] <code>tag</code> <code>name</code> <code>descr</code> [ <code>command</code>
|
||
<code>arg</code> ... ]</p>
|
||
<p>This is a convenient interface to the <code>_next_label</code> function below,
|
||
implementing the loop shown in the <code>_next_label</code> 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 <code>_all_labels</code> to be used in almost all cases where the
|
||
matches can be generated by a single call to the <code>compadd</code> builtin
|
||
command or by a call to one of the utility functions.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local expl
|
||
...
|
||
if _requested foo; then
|
||
...
|
||
_all_labels foo expl '...' compadd ... - $matches
|
||
fi
|
||
</code></pre>
|
||
</div>
|
||
<p>Will complete the strings from the <code>matches</code> parameter, using <code>compadd</code>
|
||
with additional options which will take precedence over those generated
|
||
by <code>_all_labels</code>.</p>
|
||
<p><span id="index-_005falternative"></span></p>
|
||
<p><code>_alternative</code> [ <code>-O</code> <code>name</code> ] [ <code>-C</code> <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 <code>_tags</code> 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``:``descr``:``action</code>’. The <code>tag</code>s are offered using <code>_tags</code> 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
|
||
<code>_arguments</code> function (described below), excluding the ‘<code>->``state</code>’ and
|
||
‘<code>=``...</code>’ forms.</p>
|
||
<p>For example, the <code>action</code> may be a simple function call:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_alternative \
|
||
'users:user:_users' \
|
||
'hosts:host:_hosts'
|
||
</code></pre>
|
||
</div>
|
||
<p>offers usernames and hostnames as possible matches, generated by the
|
||
<code>_users</code> and <code>_hosts</code> functions respectively.</p>
|
||
<p>Like <code>_arguments</code>, this function uses <code>_all_labels</code> 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 <code>_alternative</code>.</p>
|
||
<p>The option ‘<code>-O</code> <code>name</code>’ is used in the same way as by the <code>_arguments</code>
|
||
function. In other words, the elements of the <code>name</code> array will be
|
||
passed to <code>compadd</code> when executing an action.</p>
|
||
<p>Like <code>_tags</code> this function supports the <code>-C</code> option to give a different
|
||
name for the argument context field.</p>
|
||
<p><span id="index-_005farguments"></span></p>
|
||
<p><code>_arguments </code>[ <code>-nswWCRS</code> ] [ <code>-A</code> <code>pat</code> ] [ <code>-O</code> <code>name</code> ] [
|
||
<code>-M</code> <code>matchspec</code> ]</p>
|
||
<p><code> </code>[ <code>:</code> ] <code>spec</code> ...</p>
|
||
<p><code>_arguments </code>[ <code>opt</code> ... ] <code>-``-</code> [ <code>-l</code> ] [ <code>-i</code> <code>pats</code> ] [
|
||
<code>-s</code> <code>pair</code> ]</p>
|
||
<p><code> </code>[ <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 <code>_arguments</code> itself must be in separate words, i.e. <code>-s -w</code>,
|
||
not <code>-sw</code>. The options are followed by <code>spec</code>s that describe options and
|
||
arguments of the analyzed command. To avoid ambiguity, all options to
|
||
<code>_arguments</code> itself may be separated from the <code>spec</code> forms by a single
|
||
colon.</p>
|
||
<p>The ‘<code>-``-</code>’ 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 ‘<code>-``-</code>’ form are otherwise the same options as the first form.
|
||
Note that ‘<code>-s</code>’ following ‘<code>-``-</code>’ has a distinct meaning from ‘<code>-s</code>’
|
||
preceding ‘<code>-``-</code>’, and both may appear.</p>
|
||
<p>The option switches <code>-s</code>, <code>-S</code>, <code>-A</code>, <code>-w</code>, and <code>-W</code> affect how
|
||
<code>_arguments</code> parses the analyzed command line’s options. These switches
|
||
are useful for commands with standard argument parsing.</p>
|
||
<p>The options of <code>_arguments</code> have the following meanings:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-n</code><br />
|
||
With this option, <code>_arguments</code> sets the parameter <code>NORMARG</code> to the
|
||
position of the first normal argument in the <code>$words</code> array, i.e.
|
||
the position after the end of the options. If that argument has not
|
||
been reached, <code>NORMARG</code> is set to <code>-1</code>. The caller should declare
|
||
‘<code>integer NORMARG</code>’ if the <code>-n</code> option is passed; otherwise the
|
||
parameter is not used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><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 ‘<code>-x</code>’ and ‘<code>-y</code>’ may be combined into a
|
||
single word ‘<code>-xy</code>’. By default, every word corresponds to a single
|
||
option name (‘<code>-xy</code>’ is a single option named ‘<code>xy</code>’).</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 <code>-s</code> after <code>-``-</code> has a different meaning, which is
|
||
documented in the segment entitled ‘Deriving <code>spec</code> forms from the
|
||
help output’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-w</code><br />
|
||
In combination with <code>-s</code>, allow option stacking even if one or more
|
||
of the options take arguments. For example, if <code>-x</code> takes an
|
||
argument, with no <code>-s</code>, ‘<code>-xy</code>’ is considered as a single
|
||
(unhandled) option; with <code>-s</code>, <code>-xy</code> is an option with the argument
|
||
‘<code>y</code>’; with both <code>-s</code> and <code>-w</code>, <code>-xy</code> is the option <code>-x</code> and the
|
||
option <code>-y</code> with arguments to <code>-x</code> (and to <code>-y</code>, if it takes
|
||
arguments) still to come in subsequent words.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-W</code><br />
|
||
This option takes <code>-w</code> 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 <code>_guard</code> as part of the action.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-C</code><br />
|
||
Modify the <code>curcontext</code> parameter for an action of the form
|
||
‘<code>->``state</code>’. This is discussed in detail below.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-R</code><br />
|
||
Return status 300 instead of zero when a <code>$state</code> is to be handled,
|
||
in the ‘<code>->``string</code>’ syntax.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-S</code><br />
|
||
Do not complete options after a ‘<code>-``-</code>’ appearing on the line, and
|
||
ignore the ‘<code>-``-</code>’. For example, with <code>-S</code>, in the line</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">foobar -x -- -y
|
||
</code></pre>
|
||
</div>
|
||
<p>the ‘<code>-x</code>’ is considered an option, the ‘<code>-y</code>’ is considered an
|
||
argument, and the ‘<code>-``-</code>’ is considered to be neither.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-A</code> <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 <code>_arguments</code> 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 ‘<code>-A "-*"</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-O</code> <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>
|
||
</li>
|
||
<li>
|
||
<p><code>-M</code> <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 ‘<code>_</code>’ and ‘<code>-</code>’, such as completing ‘<code>-f-b</code>’ to ‘<code>-foo-bar</code>’.
|
||
The default <code>matchspec</code> is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">r:|[_-]=* r:|=*
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<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>
|
||
<ul>
|
||
<li>
|
||
<p><code>n``:``message``:``action</code><br />
|
||
<code>n``::``message``:``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>
|
||
</li>
|
||
<li>
|
||
<p><code>:``message``:``action</code><br />
|
||
<code>::``message``:``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>
|
||
</li>
|
||
<li>
|
||
<p><code>*:``message``:``action</code><br />
|
||
<code>*::``message``:``action</code><br />
|
||
<code>*:::``message``:``action</code><br />
|
||
This describes how arguments (usually non-option arguments, those
|
||
not beginning with <code>-</code> or <code>+</code>) 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 <code>words</code> special array and
|
||
the <code>CURRENT</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><code>optspec</code><br />
|
||
<code>optspec``:``...</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>
|
||
<ul>
|
||
<li>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<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 ‘<code>-foo</code>’. 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 ‘<code>-</code>’ may be replaced by
|
||
or paired with ‘<code>+</code>’ in this way.</p>
|
||
</li>
|
||
<li>
|
||
<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, ‘<code>-foo-:``...</code>’
|
||
specifies that the completed option and argument will look like
|
||
‘<code>-foo``arg</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<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, ‘<code>-foo+:``...</code>’ specifies that the completed option
|
||
and argument will look like either ‘<code>-foo``arg</code>’ or ‘<code>-foo</code>
|
||
<code>arg</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<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 ‘<code>-foo=``arg</code>’ or ‘<code>-foo</code> <code>arg</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<p><code>optspec``[``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 ‘<code>-q[query operation]</code>’.</p>
|
||
<p>The <code>verbose</code> 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
|
||
<code>auto-description</code> 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 ‘<code>%d</code>’ in it
|
||
replaced by the <code>message</code> of the first <code>optarg</code> that follows the
|
||
<code>optspec</code>; see below.</p>
|
||
</li>
|
||
</ul>
|
||
<p>It is possible for options with a literal ‘<code>+</code>’ or ‘<code>=</code>’ to appear,
|
||
but that character must be quoted, for example ‘<code>-\+</code>’.</p>
|
||
<p>Each <code>optarg</code> following an <code>optspec</code> must take one of the following
|
||
forms:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>:``message``:``action</code><br />
|
||
<code>::``message``:``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``:``action1``:``message2``:``action2</code> specifies
|
||
that the option takes two arguments.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:*``pattern``:``message``:``action</code><br />
|
||
<code>:*``pattern``::``message``:``action</code><br />
|
||
<code>:*``pattern``:::``message``:``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. <code>:*:</code>), 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 <code>words</code> special array and the <code>CURRENT</code> 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>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Any literal colon in an <code>optname</code>, <code>message</code>, or <code>action</code> must be
|
||
preceded by a backslash, ‘<code>\:</code>’.</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, ‘<code>(-two -three 1)-one:``...</code>’ completes the option
|
||
‘<code>-one</code>’; if this appears on the command line, the options <code>-two</code> and
|
||
<code>-three</code> and the first ordinary argument will not be completed after it.
|
||
‘<code>(-foo):``...</code>’ specifies an ordinary argument completion; <code>-foo</code> 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 (<code>*</code>) for the rest arguments
|
||
(i.e. a specification of the form ‘<code>*:``...</code>’); a colon (<code>:</code>) for all
|
||
normal (non-option-) arguments; and a hyphen (<code>-</code>) for all options. For
|
||
example, if ‘<code>(*)</code>’ 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 ‘<code>!</code>’; 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 <code>_arguments</code> is called repeatedly for more
|
||
specific contexts: on the first call ‘<code>_arguments $global_options</code>’ is
|
||
used, and on subsequent calls ‘<code>_arguments !$^global_options</code>’.</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 <code>_all_labels</code> 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 ‘<code>-O</code> <code>name</code>’ option as arguments.
|
||
This can be used, for example, to pass the same set of options for the
|
||
<code>compadd</code> builtin to all <code>action</code>s.</p>
|
||
<p>The forms for <code>action</code> are as follows.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code> </code>(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>
|
||
</li>
|
||
<li>
|
||
<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-example">:foo:(foo bar baz)
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p><code>((item1\:desc1 ...))</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-example">:foo:((a\:bar b\:baz))
|
||
</code></pre>
|
||
</div>
|
||
<p>The matches will be listed together with their descriptions if the
|
||
<code>description</code> style is set with the <code>values</code> tag in the context.</p>
|
||
</li>
|
||
<li>
|
||
<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, <code>_arguments</code> 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 <code>_arguments</code> 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 <code>state</code> to the set of all <code>string</code>s for which an
|
||
action is to be performed. The elements of the array <code>state_descr</code>
|
||
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 <code>-R</code> option is
|
||
given, <code>_arguments</code> will instead return a status of 300 to indicate
|
||
that <code>$state</code> is to be handled.</p>
|
||
<p>In addition to <code>$state</code> and <code>$state_descr</code>, <code>_arguments</code> also sets
|
||
the global parameters ‘<code>context</code>’, ‘<code>line</code>’ and ‘<code>opt_args</code>’ as
|
||
described below, and does not reset any changes made to the special
|
||
parameters such as <code>PREFIX</code> and <code>words</code>. This gives the calling
|
||
function the choice of resetting these parameters or propagating
|
||
changes in them.</p>
|
||
<p>A function calling <code>_arguments</code> with at least one action containing
|
||
a ‘<code>->``string</code>’ must therefore declare appropriate local
|
||
parameters:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local context state state_descr line
|
||
typeset -A opt_args
|
||
</code></pre>
|
||
</div>
|
||
<p>to prevent <code>_arguments</code> from altering the global environment.</p>
|
||
</li>
|
||
<li>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<p><code> = ``action</code><br />
|
||
If the <code>action</code> starts with ‘<code>= </code>’ (an equals sign followed by a
|
||
space), <code>_arguments</code> will insert the contents of the <code>argument</code>
|
||
field of the current context as the new first element in the <code>words</code>
|
||
special array and increment the value of the <code>CURRENT</code> 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 <code>_arguments</code> 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 <code>_arguments</code> to be able to
|
||
parse the line.</p>
|
||
</li>
|
||
<li>
|
||
<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
|
||
<code>compadd</code> builtin. They ensure that the state specified by
|
||
<code>_arguments</code>, in particular the descriptions of options and
|
||
arguments, is correctly passed to the completion command. These
|
||
additional arguments are taken from the array parameter ‘<code>expl</code>’;
|
||
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
|
||
‘<code>$expl[@]</code>’ which preserves empty elements of the array.</p>
|
||
</li>
|
||
</ul>
|
||
<p>During the performance of the action the array ‘<code>line</code>’ 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 ‘<code>opt_args</code>’ with
|
||
option names as keys and their arguments as the values. For options that
|
||
have more than one argument these are given as one string, separated by
|
||
colons. All colons and backslashes in the original arguments are
|
||
preceded with backslashes.</p>
|
||
<p>The parameter ‘<code>context</code>’ 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 <code>$state</code>. Each string of
|
||
the form ‘<code>option``-opt``-``n</code>’ for the <code>n</code>’th argument of the option
|
||
<code>-opt</code>, or a string of the form ‘<code>argument-``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 ‘<code>rest</code>’. For example, when
|
||
completing the argument of the <code>-o</code> option, the name is ‘<code>option-o-1</code>’,
|
||
while for the second normal (non-option-) argument it is ‘<code>argument-2</code>’.</p>
|
||
<p>Furthermore, during the evaluation of the <code>action</code> the context name in
|
||
the <code>curcontext</code> parameter is altered to append the same string that is
|
||
stored in the <code>context</code> parameter.</p>
|
||
<p>The option <code>-C</code> tells <code>_arguments</code> to modify the <code>curcontext</code> 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
|
||
<code>context</code> 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-example">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 ‘<code>+</code>’ 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-example">_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-example">_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 ‘<code>opt_args</code>’ with ’<code>group``-``option</code>’ as a key. In
|
||
the example above, a key ‘<code>operation–c</code>’ is used if the option ‘<code>-c</code>’ 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-example">_arguments \
|
||
-a \
|
||
- set1 \
|
||
-c \
|
||
- set2 \
|
||
-d \
|
||
':arg:(x2 y2)'
|
||
</code></pre>
|
||
</div>
|
||
<p>This defines two sets. When the command line contains the option ‘<code>-c</code>’,
|
||
the ‘<code>-d</code>’ option and the argument will not be considered possible
|
||
completions. When it contains ‘<code>-d</code>’ or an argument, the option ‘<code>-c</code>’
|
||
will not be considered. However, after ‘<code>-a</code>’ 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 ‘<code>-foo:*:...</code>’); here the option <code>-foo</code> 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 ‘<code>-``-</code>’ allows <code>_arguments</code> to work out the names of long
|
||
options that support the ‘<code>-``-help</code>’ option which is standard in many
|
||
GNU commands. The command word is called with the argument ‘<code>-``-help</code>’
|
||
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, ‘<code>_arguments -``-</code>’ will try to deduce the types
|
||
of arguments available for options when the form ‘<code>-``-``opt``=``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``:``message``:``action</code>’; note that other <code>_arguments</code>
|
||
<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 ‘<code>*:</code>’ 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-example">_arguments -- '*\*:toggle:(yes no)' \
|
||
'*=FILE*:file:_files' \
|
||
'*=DIR*:directory:_files -/' \
|
||
'*=PATH*:directory:_files -/'
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, ‘<code>yes</code>’ and ‘<code>no</code>’ 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 ‘<code>=FILE</code>’ in the description; and
|
||
directories will be completed for options whose description contains
|
||
‘<code>=DIR</code>’ or ‘<code>=PATH</code>’. 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-example"> -C, --directory=DIR change to directory DIR
|
||
</code></pre>
|
||
</div>
|
||
<p>so that the above specifications will cause directories to be completed
|
||
after ‘<code>-``-directory</code>’, though not after ‘<code>-C</code>’.</p>
|
||
<p>Note also that <code>_arguments</code> 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 ‘<code>(-)</code>’, this will be removed from the pattern
|
||
and the <code>action</code> will be used only directly after the ‘<code>=</code>’, not in the
|
||
next word. This is the behaviour of a normal specification defined with
|
||
the form ‘<code>=-</code>’.</p>
|
||
<p>By default, the command (with the option ‘<code>–help</code>’) is run after
|
||
resetting all the locale categories (except for <code>LC_CTYPE</code>) to ‘<code>C</code>’. If
|
||
the localized help output is known to work, the option ‘<code>-l</code>’ can be
|
||
specified after the ‘<code>_arguments -``-</code>’ so that the command is run in
|
||
the current locale.</p>
|
||
<p>The ‘<code>_arguments -``-</code>’ can be followed by the option ‘<code>-i</code> <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-example">_arguments -- -i \
|
||
"(--(en|dis)able-FEATURE*)"
|
||
</code></pre>
|
||
</div>
|
||
<p>will cause completion to ignore the options ‘<code>-``-enable-FEATURE</code>’ and
|
||
‘<code>-``-disable-FEATURE</code>’ (this example is useful with GNU <code>configure</code>).</p>
|
||
<p>The ‘<code>_arguments -``-</code>’ form can also be followed by the option ‘<code>-s</code>
|
||
<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 <code>_arguments</code>
|
||
call.</p>
|
||
<p>For example, some <code>configure</code>-script help output describes options only
|
||
as ‘<code>-``-enable-foo</code>’, but the script also accepts the negated form
|
||
‘<code>-``-disable-foo</code>’. To allow completion of the second form:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_arguments -- -s "((#s)--enable- --disable-)"
|
||
</code></pre>
|
||
</div>
|
||
<p><em>Miscellaneous notes</em></p>
|
||
<p>Finally, note that <code>_arguments</code> 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 <code>_arguments</code> with other functions,
|
||
those functions should be called either before <code>_arguments</code>, 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 <code>_arguments</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_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: ‘<code>-l</code>’, ‘<code>-format</code>’, and ‘<code>-copy</code>’. 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 ‘<code>-l</code>’ or it may be given as the next word on
|
||
the line.</p>
|
||
<p>The ‘<code>-format</code>’ option takes one argument in the next word, described as
|
||
‘<code>paper size</code>’ for which only the strings ‘<code>letter</code>’ and ‘<code>A4</code>’ will be
|
||
completed.</p>
|
||
<p>The ‘<code>-copy</code>’ 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
|
||
‘<code>300</code>’ and ‘<code>600</code>’.</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 ‘<code>ps</code>’ or ‘<code>eps</code>’ be completed. The last description
|
||
gives all other arguments the description ‘<code>page numbers</code>’ but does not
|
||
offer completions.</p>
|
||
<p><span id="index-_005fcache_005finvalid"></span></p>
|
||
<p><code>_cache_invalid</code> <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 <code>cache-policy</code> 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-example">_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><code>_call_function</code> <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 <code>_call_function</code> 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><code>_call_program</code> [ <code>-l</code> ] [ <code>-p</code> ] <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 <code>command</code> 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 <code>_call_program</code>, 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 <code>LC_CTYPE</code>) are reset to ‘<code>C</code>’ by calling the
|
||
utility function <code>_comp_locale</code> (see below). If the option ‘<code>-l</code>’ is
|
||
given, the command is run with the current locale.</p>
|
||
<p>If the option ‘<code>-p</code>’ is supplied it indicates that the command output is
|
||
influenced by the permissions it is run with. If the <code>gain-privileges</code>
|
||
style is set to true, <code>_call_program</code> will make use of commands such as
|
||
<code>sudo</code>, if present on the command-line, to match the permissions to
|
||
whatever the final command is likely to run under. When looking up the
|
||
<code>gain-privileges</code> and <code>command</code> styles, the command component of the
|
||
zstyle context will end with a slash (‘<code>/</code>’) followed by the command
|
||
that would be used to gain privileges.</p>
|
||
<p><span id="index-_005fcombination"></span></p>
|
||
<p><code>_combination</code> [ <code>-s</code> <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
|
||
‘<code>users-hosts-ports</code>’. For each field for a value is already known, a
|
||
<code>spec</code> of the form ‘<code>field``=``pattern</code>’ is given. For example, if the
|
||
command line so far specifies a user ‘<code>pws</code>’, the argument ‘<code>users=pws</code>’
|
||
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 <code>-s</code> to <code>_combination</code> which specifies a pattern.
|
||
Typically this is a character class, as for example ‘<code>-s "[:@]"</code>’ in the
|
||
case of the <code>users-hosts</code> style. Each ‘<code>field``=``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
|
||
‘<code>users-hosts-ports</code>’ or no matching hostname when a host is required,
|
||
the function ‘<code>_hosts</code>’ will automatically be called.</p>
|
||
<p>If the same name is used for more than one field, in both the
|
||
‘<code>field``=``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 <code>compadd</code> 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><code>_command_names</code> [ <code>-e</code> | <code>-</code> ]</p>
|
||
<p>This function completes words that are valid at command position: names
|
||
of aliases, builtins, hashed commands, functions, and so on. With the
|
||
<code>-e</code> flag, only hashed commands are completed. The <code>-</code> flag is ignored.</p>
|
||
<p><span id="index-_005fcomp_005flocale"></span></p>
|
||
<p><code>_comp_locale</code></p>
|
||
<p>This function resets all the locale categories other than <code>LC_CTYPE</code> to
|
||
‘<code>C</code>’ so that the output from external commands can be easily analyzed
|
||
by the completion system. <code>LC_CTYPE</code> retains the current value (taking
|
||
<code>LC_ALL</code> and <code>LANG</code> 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
|
||
‘<code> $(_comp_locale; ``command</code> ...<code>)</code>’.</p>
|
||
<p><span id="index-_005fcompleters"></span></p>
|
||
<p><code>_completers</code> [ <code>-p</code> ]</p>
|
||
<p>This function completes names of completers.</p>
|
||
<ul>
|
||
<li><code>-p</code><br />
|
||
Include the leading underscore (‘<code>_</code>’) in the matches.</li>
|
||
</ul>
|
||
<p><span id="index-_005fdescribe"></span></p>
|
||
<p><code>_describe </code>[<code>-12JVx</code>] [ <code>-oO</code> | <code>-t</code> <code>tag</code> ] <code>descr</code> <code>name1</code> [
|
||
<code>name2</code> ] [ <code>opt</code> ... ]</p>
|
||
<p><code> </code>[ <code>-``-</code> <code>name1</code> [ <code>name2</code> ] [ <code>opt</code> ... ] ... ]</p>
|
||
<p>This function associates completions with descriptions. Multiple groups
|
||
separated by <code>-``-</code> 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
|
||
<code>format</code> style for the <code>descriptions</code> tag is set. This is followed by
|
||
one or two names of arrays followed by options to pass to <code>compadd</code>. The
|
||
array <code>name1</code> contains the possible completions with their descriptions
|
||
in the form ‘<code>completion``:``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 ‘<code>-o</code>’ appears before the first argument, the matches
|
||
added will be treated as names of command options (N.B. not shell
|
||
options), typically following a ‘<code>-</code>’, ‘<code>-``-</code>’ or ‘<code>+</code>’ on the command
|
||
line. In this case <code>_describe</code> uses the <code>prefix-hidden</code>, <code>prefix-needed</code>
|
||
and <code>verbose</code> styles to find out if the strings should be added as
|
||
completions and if the descriptions should be shown. Without the ‘<code>-o</code>’
|
||
option, only the <code>verbose</code> style is used to decide how descriptions are
|
||
shown. If ‘<code>-O</code>’ is used instead of ‘<code>-o</code>’, command options are
|
||
completed as above but <code>_describe</code> will not handle the <code>prefix-needed</code>
|
||
style.</p>
|
||
<p>With the <code>-t</code> option a <code>tag</code> can be specified. The default is ‘<code>values</code>’
|
||
or, if the <code>-o</code> option is given, ‘<code>options</code>’.</p>
|
||
<p>The options <code>-1</code>, <code>-2</code>, <code>-J</code>, <code>-V</code>, <code>-x</code> are passed to <code>_next_label</code>.</p>
|
||
<p>If selected by the <code>list-grouped</code> style, strings with the same
|
||
description will appear together in the list.</p>
|
||
<p><code>_describe</code> uses the <code>_all_labels</code> 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><code>_description</code> [ <code>-x</code> ] [ <code>-12VJ</code> ] <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 <code>compadd</code>. 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 <code>compadd</code> are put into the array
|
||
named <code>name</code> (this is traditionally ‘<code>expl</code>’, 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: <code>format</code>, <code>hidden</code>, <code>matcher</code>, <code>ignore-line</code>,
|
||
<code>ignored-patterns</code>, <code>group-name</code> and <code>sort</code>. The <code>format</code> style is first
|
||
tested for the given <code>tag</code> and then for the <code>descriptions</code> tag if no
|
||
value was found, while the remainder are only tested for the tag given
|
||
as the first argument. The function also calls <code>_setup</code> which tests some
|
||
more styles.</p>
|
||
<p>The string returned by the <code>format</code> style (if any) will be modified so
|
||
that the sequence ‘<code>%d</code>’ 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 <code>_description</code> is called with more than three arguments, the
|
||
additional <code>spec</code>s should be of the form ‘<code>char``:``str</code>’. These supply
|
||
escape sequence replacements for the <code>format</code> style: every appearance of
|
||
‘<code>%``char</code>’ will be replaced by <code>string</code>.</p>
|
||
<p>If the <code>-x</code> option is given, the description will be passed to <code>compadd</code>
|
||
using the <code>-x</code> option instead of the default <code>-X</code>. 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 <code>group-name</code>
|
||
style, so matches are placed in a separate group where necessary. The
|
||
group normally has its elements sorted (by passing the option <code>-J</code> to
|
||
<code>compadd</code>), but if an option starting with ‘<code>-V</code>’, ‘<code>-J</code>’, ‘<code>-1</code>’, or
|
||
‘<code>-2</code>’ is passed to <code>_description</code>, that option will be included in
|
||
the array. Hence it is possible for the completion group to be unsorted
|
||
by giving the option ‘<code>-V</code>’, ‘<code>-1V</code>’, or ‘<code>-2V</code>’.</p>
|
||
<p>In most cases, the function will be used like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local expl
|
||
_description files expl file
|
||
compadd "$expl[@]" - "$files[@]"
|
||
</code></pre>
|
||
</div>
|
||
<p>Note the use of the parameter <code>expl</code>, the hyphen, and the list of
|
||
matches. Almost all calls to <code>compadd</code> 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><code>_dir_list</code> [ <code>-s</code> <code>sep</code> ] [ <code>-S</code> ]</p>
|
||
<p>Complete a list of directory names separated by colons (the same format
|
||
as <code>$PATH</code>).</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-s</code> <code>sep</code><br />
|
||
Use <code>sep</code> as separator between items. <code>sep</code> defaults to a colon
|
||
(‘<code>:</code>’).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-S</code><br />
|
||
Add <code>sep</code> instead of slash (‘<code>/</code>’) as an autoremoveable suffix.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-_005fdispatch"></span></p>
|
||
<p><code>_dispatch</code> <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 <code>compdef</code>) 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 <code>-default-</code> to cause the function for default completion to
|
||
be used as a fallback.</p>
|
||
<p>The function sets the parameter <code>$service</code> to the <code>string</code> being tried,
|
||
and sets the <code>context/command</code> field (the fourth) of the <code>$curcontext</code>
|
||
parameter to the <code>context</code> given as the first argument.</p>
|
||
<p><span id="index-_005femail_005faddresses"></span></p>
|
||
<p><code>_email_addresses</code> [ <code>-c</code> ] [ <code>-n</code> <code>plugin</code> ]</p>
|
||
<p>Complete email addresses. Addresses are provided by plugins.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-c</code><br />
|
||
Complete bare <code>localhost@domain.tld</code> addresses, without a name part
|
||
or a comment. Without this option, RFC822 ‘<code>Firstname Lastname</code>
|
||
<code><``address``></code>’ strings are completed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code> <code>plugin</code><br />
|
||
Complete aliases from <code>plugin</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The following plugins are available by default: <code>_email-ldap</code> (see the
|
||
<code>filter</code> style), <code>_email-local</code> (completes <code>user``@``hostname</code> Unix
|
||
addresses), <code>_email-mail</code> (completes aliases from <code>~/.mailrc</code>),
|
||
<code>_email-mush</code>, <code>_email-mutt</code>, and <code>_email-pine</code>.</p>
|
||
<p>Addresses from the <code>_email-``foo</code> plugin are added under the tag
|
||
‘<code>email-``foo</code>’.</p>
|
||
<p><em>Writing plugins</em></p>
|
||
<p>Plugins are written as separate functions with names starting with
|
||
‘<code>_email-</code>’. They are invoked with the <code>-c</code> option and <code>compadd</code>
|
||
options. They should either do their own completion or set the <code>$reply</code>
|
||
array to a list of ‘<code>alias``:``address</code>’ elements and return <code>300</code>. New
|
||
plugins will be picked up and run automatically.</p>
|
||
<p><span id="index-_005ffiles"></span></p>
|
||
<p><code>_files</code></p>
|
||
<p>The function <code>_files</code> is a wrapper around <code>_path_files</code>. It supports all
|
||
of the same functionality, with some enhancements — notably, it respects
|
||
the <code>list-dirs-first</code> style, and it allows users to override the
|
||
behaviour of the <code>-g</code> and <code>-/</code> options with the <code>file-patterns</code> style.
|
||
<code>_files</code> should therefore be preferred over <code>_path_files</code> in most cases.</p>
|
||
<p>This function accepts the full set of options allowed by <code>_path_files</code>,
|
||
described below.</p>
|
||
<p><span id="index-_005fgnu_005fgeneric"></span></p>
|
||
<p><code>_gnu_generic</code></p>
|
||
<p>This function is a simple wrapper around the <code>_arguments</code> function
|
||
described above. It can be used to determine automatically the long
|
||
options understood by commands that produce a list when passed the
|
||
option ‘<code>-``-help</code>’. 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 <code>foo</code> and <code>bar</code>, use</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compdef _gnu_generic foo bar
|
||
</code></pre>
|
||
</div>
|
||
<p>after the call to <code>compinit</code>.</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 ‘<code>-``-help</code>’.</p>
|
||
<p><span id="index-_005fguard"></span></p>
|
||
<p><code>_guard</code> [ <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 <code>_arguments</code> 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
|
||
<code>compadd</code> that are passed down from <code>_description</code>, namely <code>-M</code>, <code>-J</code>,
|
||
<code>-V</code>, <code>-1</code>, <code>-2</code>, <code>-n</code>, <code>-F</code> and <code>-X</code>. All of these options will be
|
||
ignored. This fits in conveniently with the argument-passing conventions
|
||
of actions for <code>_arguments</code>.</p>
|
||
<p>As an example, consider a command taking the options <code>-n</code> and <code>-none</code>,
|
||
where <code>-n</code> must be followed by a numeric value in the same word. By
|
||
using:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_arguments '-n-: :_guard "[0-9]#" "numeric value"' '-none'
|
||
</code></pre>
|
||
</div>
|
||
<p><code>_arguments</code> can be made to both display the message ‘<code>numeric value</code>’
|
||
and complete options after ‘<code>-n<TAB></code>’. If the ‘<code>-n</code>’ is already
|
||
followed by one or more digits (the pattern passed to <code>_guard</code>) only the
|
||
message will be displayed; if the ‘<code>-n</code>’ is followed by another
|
||
character, only options are completed.</p>
|
||
<p><span id="index-_005fmessage"></span></p>
|
||
<p><code>_message</code> [ <code>-r12</code> ] [ <code>-VJ</code> <code>group</code> ] <code>descr</code></p>
|
||
<p><code>_message -e</code> [ <code>tag</code> ] <code>descr</code></p>
|
||
<p>The <code>descr</code> is used in the same way as the third argument to the
|
||
<code>_description</code> 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 <code>format</code> style is examined with the <code>messages</code> tag to find a
|
||
message; the usual tag, <code>descriptions</code>, is used only if the style is not
|
||
set with the former.</p>
|
||
<p>If the <code>-r</code> 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
|
||
‘<code>%</code>’-sequence parsing done by <code>compadd</code>.</p>
|
||
<p>The <code>-12VJ</code> options and the <code>group</code> are passed to <code>compadd</code> and hence
|
||
determine the group the message string is added to.</p>
|
||
<p>The second <code>-e</code> 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 <code>_arguments</code> 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 <code>$curtag</code>; 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, <code>compstate[insert]</code> is cleared, so
|
||
additional matches generated later are not inserted on the command line.</p>
|
||
<p><span id="index-_005fmulti_005fparts"></span></p>
|
||
<p><code>_multi_parts</code> [ <code>-i</code> ] <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 ‘<code>(foo bar``)</code>’, 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 <code>_tar</code>
|
||
function uses ‘<code>_multi_parts</code> <code>/</code> <code>patharray</code>’ to complete partial file
|
||
paths from the given array of complete file paths.</p>
|
||
<p>The <code>-i</code> option causes <code>_multi_parts</code> 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 ‘<code>-V</code>’, ‘<code>-J</code>’,
|
||
‘<code>-1</code>’, ‘<code>-2</code>’, ‘<code>-n</code>’, ‘<code>-f</code>’, ‘<code>-X</code>’, ‘<code>-M</code>’, ‘<code>-P</code>’, ‘<code>-S</code>’,
|
||
‘<code>-r</code>’, ‘<code>-R</code>’, and ‘<code>-q</code>’ options and passes them to the <code>compadd</code>
|
||
builtin.</p>
|
||
<p><span id="index-_005fnext_005flabel"></span></p>
|
||
<p><code>_next_label</code> [ <code>-x</code> ] [ <code>-12VJ</code> ] <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 <code>tag-order</code> 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 <code>_tags</code> or
|
||
<code>_requested</code>.</p>
|
||
<p>The <code>-x12VJ</code> options and the first three arguments are passed to the
|
||
<code>_description</code> function. Where appropriate the <code>tag</code> will be replaced by
|
||
a tag label in this call. Any description given in the <code>tag-order</code> style
|
||
is preferred to the <code>descr</code> passed to <code>_next_label</code>.</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 <code>compadd</code> or whatever function is
|
||
called to add the matches.</p>
|
||
<p>Here is a typical use of this function for the tag <code>foo</code>. The call to
|
||
<code>_requested</code> determines if tag <code>foo</code> is required at all; the loop over
|
||
<code>_next_label</code> handles any labels defined for the tag in the <code>tag-order</code>
|
||
style.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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><code>_normal</code> [ <code>-P</code> | <code>-p</code> <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, <code>_normal</code>
|
||
looks for a special completion for that command, and if there is none it
|
||
uses the completion for the <code>-default-</code> context.</p>
|
||
<p>A second use is to reexamine the command line specified by the <code>$words</code>
|
||
array and the <code>$CURRENT</code> parameter after those have been modified. For
|
||
example, the function <code>_precommand</code>, which completes after precommand
|
||
specifiers such as <code>nohup</code>, removes the first word from the <code>words</code>
|
||
array, decrements the <code>CURRENT</code> parameter, then calls ‘<code>_normal -p $service</code>’. The effect is that ‘<code>nohup</code> <code>cmd ...</code>’ is treated in the
|
||
same way as ‘<code>cmd ...</code>’.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-P</code><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. ‘<code>zsh -c</code>’).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-p</code> <code>precommand</code><br />
|
||
Append <code>precommand</code> to the list of precommands. This option should
|
||
be used in nearly all cases in which <code>-P</code> is not applicable.</p>
|
||
</li>
|
||
</ul>
|
||
<p>If the command name matches one of the patterns given by one of the
|
||
options <code>-p</code> or <code>-P</code> to <code>compdef</code>, the corresponding completion function
|
||
is called and then the parameter <code>_compskip</code> 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 <code>-first-</code> context.</p>
|
||
<p><span id="index-_005foptions"></span></p>
|
||
<p><code>_options</code></p>
|
||
<p>This can be used to complete the names of shell options. It provides a
|
||
matcher specification that ignores a leading ‘<code>no</code>’, ignores underscores
|
||
and allows upper-case letters to match their lower-case counterparts
|
||
(for example, ‘<code>glob</code>’, ‘<code>noglob</code>’, ‘<code>NO_GLOB</code>’ are all completed). Any
|
||
arguments are propagated to the <code>compadd</code> builtin.</p>
|
||
<p><span id="index-_005foptions_005fset"></span>
|
||
<span id="index-_005foptions_005funset"></span></p>
|
||
<p><code>_options_set</code> and <code>_options_unset</code></p>
|
||
<p>These functions complete only set or unset options, with the same
|
||
matching specification used in the <code>_options</code> function.</p>
|
||
<p>Note that you need to uncomment a few lines in the <code>_main_complete</code>
|
||
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><code>_parameters</code></p>
|
||
<p>This is used to complete the names of shell parameters.</p>
|
||
<p>The option ‘<code>-g</code> <code>pattern</code>’ limits the completion to parameters whose
|
||
type matches the <code>pattern</code>. The type of a parameter is that shown by
|
||
‘<code>print ${(t)``param``}</code>’, hence judicious use of ‘<code>*</code>’ in <code>pattern</code>
|
||
is probably necessary.</p>
|
||
<p>All other arguments are passed to the <code>compadd</code> builtin.</p>
|
||
<p><span id="index-_005fpath_005ffiles"></span></p>
|
||
<p><code>_path_files</code></p>
|
||
<p>This function is used throughout the completion system to complete
|
||
filenames. It allows completion of partial paths. For example, the
|
||
string ‘<code>/u/i/s/sig</code>’ may be completed to ‘<code>/usr/include/sys/signal.h</code>’.</p>
|
||
<p>The options accepted by both <code>_path_files</code> and <code>_files</code> are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-f</code><br />
|
||
Complete all filenames. This is the default.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-/</code><br />
|
||
Specifies that only directories should be completed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-g</code> <code>pattern</code><br />
|
||
Specifies that only files matching the <code>pattern</code> should be
|
||
completed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-W</code> <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>
|
||
</li>
|
||
<li>
|
||
<p><code>-F</code> <code>ignored-files</code><br />
|
||
This behaves as for the corresponding option to the <code>compadd</code>
|
||
builtin. It gives direct control over which filenames should be
|
||
ignored. If the option is not present, the <code>ignored-patterns</code> style
|
||
is used.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Both <code>_path_files</code> and <code>_files</code> also accept the following options which
|
||
are passed to <code>compadd</code>: ‘<code>-J</code>’, ‘<code>-V</code>’, ‘<code>-1</code>’, ‘<code>-2</code>’, ‘<code>-n</code>’, ‘<code>-X</code>’,
|
||
‘<code>-M</code>’, ‘<code>-P</code>’, ‘<code>-S</code>’, ‘<code>-q</code>’, ‘<code>-r</code>’, and ‘<code>-R</code>’.</p>
|
||
<p>Finally, the <code>_path_files</code> function uses the styles <code>expand</code>,
|
||
<code>ambiguous</code>, <code>special-dirs</code>, <code>list-suffixes</code> and <code>file-sort</code> described
|
||
above.</p>
|
||
<p><span id="index-_005fpick_005fvariant"></span></p>
|
||
<p><code>_pick_variant </code>[ <code>-b</code> <code>builtin-label</code> ] [ <code>-c</code> <code>command</code> ] [
|
||
<code>-r</code> <code>name</code> ]</p>
|
||
<p><code> ``label``=``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 <code>words</code>
|
||
unless this is overridden by the option <code>-c</code>. 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``=``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 ‘<code>-b</code> <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 ‘<code>-r</code> <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 <code>_cmd_variant</code> associative array
|
||
indexed by the name of the command run.</p>
|
||
<p><span id="index-_005fregex_005farguments"></span></p>
|
||
<p><code>_regex_arguments</code> <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 <code>_regex_arguments</code>, 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 <code>words</code> 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 ‘<code>|</code>’,
|
||
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 <code>tag-order</code> style; the various
|
||
formats supported by <code>_alternative</code> can be used in <code>action</code>. The <code>descr</code>
|
||
is used for setting up the array parameter <code>expl</code>.</p>
|
||
<p>Specification arguments take one of following forms, in which
|
||
metacharacters such as ‘<code>(</code>’, ‘<code>)</code>’, ‘<code>#</code>’ and ‘<code>|</code>’ should be quoted.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>/``pattern``/</code> [<code>%``lookahead``%</code>] [<code>-``guard</code>]
|
||
[<code>:``tag``:``descr``:``action</code>]<br />
|
||
This is a single primitive component. The function tests whether the
|
||
combined pattern ‘<code>(#b)((#B)``pattern``)``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 ‘<code>[]</code>’ 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 <code>:</code> is used in the same manner as an
|
||
argument to <code>_alternative</code>.</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>
|
||
</li>
|
||
<li>
|
||
<p><code>/``pattern``/+</code> [<code>%``lookahead``%</code>] [<code>-``guard</code>]
|
||
[<code>:``tag``:``descr``:``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>
|
||
</li>
|
||
<li>
|
||
<p><code>/``pattern``/-</code> [<code>%``lookahead``%</code>] [<code>-``guard</code>]
|
||
[<code>:``tag``:``descr``:``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>
|
||
</li>
|
||
<li>
|
||
<p><code>(</code> <code>spec</code> <code>)</code><br />
|
||
Parentheses may be used to groups <code>spec</code>s; note each parenthesis is
|
||
a single argument to <code>_regex_arguments</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>spec</code> <code>#</code><br />
|
||
This allows any number of repetitions of <code>spec</code>.</p>
|
||
</li>
|
||
<li>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<p><code>spec</code> <code>|</code> <code>spec</code><br />
|
||
Either of the two <code>spec</code>s can be matched.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The function <code>_regex_words</code> 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-example">_regex_arguments _tst /$'[^\0]#\0'/ \
|
||
/$'[^\0]#\0'/ :'compadd aaa'
|
||
</code></pre>
|
||
</div>
|
||
<p>This generates a function <code>_tst</code> that completes <code>aaa</code> 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 <code>aaa</code> being present.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_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 <code>aaa</code> was present as the first argument.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_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 <code>aaa</code> and even arguments as
|
||
<code>bbb</code>. Completion fails unless the set of <code>aaa</code> and <code>bbb</code> arguments
|
||
before the current one is matched correctly.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">_regex_arguments _tst /$'[^\0]#\0'/ \
|
||
\( /$'aaa\0'/ :'compadd aaa' \| \
|
||
/$'bbb\0'/ :'compadd bbb' \) \#
|
||
</code></pre>
|
||
</div>
|
||
<p>This is similar, but either <code>aaa</code> or <code>bbb</code> may be completed for any
|
||
argument. In this case <code>_regex_words</code> could be used to generate</p>
|
||
<p><span id="index-_005fregex_005fwords-_005b-_002dt-term-_005d"></span></p>
|
||
<p><code>_regex_words</code> <code>tag</code> <code>description</code> <code>spec</code> ...</p>
|
||
<p>This function can be used to generate arguments for the
|
||
<code>_regex_arguments</code> 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
|
||
<code>_arguments</code> 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 <code>*</code>; the entire word, before and after the
|
||
<code>*</code> is completed, but only the text before the <code>*</code> 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 <code>-t</code> <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 <code>-s</code> <code>sep</code> to <code>_values</code>.</p>
|
||
<p>The result of the processing by <code>_regex_words</code> is placed in the array
|
||
<code>reply</code>, which should be made local to the calling function. If the set
|
||
of words and arguments may be matched repeatedly, a <code>#</code> should be
|
||
appended to the generated array at that point.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>mydb</code> which takes two
|
||
command arguments, <code>add</code> and <code>show</code>. <code>show</code> takes no arguments, while
|
||
the arguments for <code>add</code> have already been prepared in an array
|
||
<code>mydb_add_cmds</code>, quite possibly by a previous call to <code>_regex_words</code>.</p>
|
||
<p><span id="index-_005frequested"></span></p>
|
||
<p><code>_requested</code> [ <code>-x</code> ] [ <code>-12VJ</code> ] <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 <code>_tags</code> (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-example">_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 <code>_tags</code> loop. This is so that the user can set the
|
||
<code>tag-order</code> 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, <code>_requested</code> calls the <code>_description</code>
|
||
function with these arguments together with the options passed to
|
||
<code>_requested</code>.</p>
|
||
<p>If <code>command</code> is given, the <code>_all_labels</code> 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-example">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 <code>compadd</code>, it must nevertheless be prepared to
|
||
handle the same options.</p>
|
||
<p><span id="index-_005fretrieve_005fcache"></span></p>
|
||
<p><code>_retrieve_cache</code> <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 <code>cache-path</code>
|
||
style which defaults to <code>~/.zcompcache</code>. The return status is zero if
|
||
retrieval was successful. It will only attempt retrieval if the
|
||
<code>use-cache</code> style is set, so you can call this function without worrying
|
||
about whether the user wanted to use the caching layer.</p>
|
||
<p>See <code>_store_cache</code> below for more details.</p>
|
||
<p><span id="index-_005fsep_005fparts"></span></p>
|
||
<p><code>_sep_parts</code></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
|
||
‘<code>hosts=(ftp news)</code>’ the call ‘<code>_sep_parts ’(foo bar)’ @ hosts</code>’ will
|
||
complete the string ‘<code>f</code>’ to ‘<code>foo</code>’ and the string ‘<code>b@n</code>’ to
|
||
‘<code>bar@news</code>’.</p>
|
||
<p>This function accepts the <code>compadd</code> options ‘<code>-V</code>’, ‘<code>-J</code>’, ‘<code>-1</code>’,
|
||
‘<code>-2</code>’, ‘<code>-n</code>’, ‘<code>-X</code>’, ‘<code>-M</code>’, ‘<code>-P</code>’, ‘<code>-S</code>’, ‘<code>-r</code>’, ‘<code>-R</code>’, and
|
||
‘<code>-q</code>’ and passes them on to the <code>compadd</code> builtin used to add the
|
||
matches.</p>
|
||
<p><span id="index-_005fsequence"></span></p>
|
||
<p><code>_sequence</code> [ <code>-s</code> <code>sep</code> ] [ <code>-n</code> <code>max</code> ] [ <code>-d</code> ] <code>function</code> [
|
||
<code>-</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 <code>-s</code> option. If <code>-s</code> is
|
||
omitted it will use ‘<code>,</code>’. Duplicate values are not matched unless <code>-d</code>
|
||
is specified. If there is a fixed or maximum number of items in the
|
||
list, this can be specified with the <code>-n</code> option.</p>
|
||
<p>Common <code>compadd</code> options are passed on to the function. It is possible
|
||
to use <code>compadd</code> directly with <code>_sequence</code>, though <code>_values</code> may be more
|
||
appropriate in this situation.</p>
|
||
<p><span id="index-_005fsetup"></span></p>
|
||
<p><code>_setup</code> <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 <code>list-colors</code>, <code>list-packed</code>, <code>list-rows-first</code>,
|
||
<code>last-prompt</code>, <code>accept-exact</code>, <code>menu</code> and <code>force-list</code>.</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 <code>_description</code> and hence is
|
||
not normally called explicitly.</p>
|
||
<p><span id="index-_005fstore_005fcache"></span></p>
|
||
<p><code>_store_cache</code> <code>cache_identifier</code> <code>param</code> ...</p>
|
||
<p>This function, together with <code>_retrieve_cache</code> and <code>_cache_invalid</code>,
|
||
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 <code>_retrieve_cache</code>, 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
|
||
<code>cache-path</code> style which defaults to <code>~/.zcompcache</code>. 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 <code>use-cache</code> 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 <code>_retrieve_cache</code> when it
|
||
already has the completion data available as parameters. However, in
|
||
that case it should call <code>_cache_invalid</code> 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><code>_tags</code> [ [ <code>-C</code> <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 <code>tag-order</code> style.</p>
|
||
<p>Next, <code>_tags</code> 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 <code>_requested</code> function should be
|
||
called (see above).</p>
|
||
<p>If ‘<code>-C</code> <code>name</code>’ is given, <code>name</code> is temporarily stored in the
|
||
<code>argument</code> field (the fifth) of the context in the <code>curcontext</code>
|
||
parameter during the call to <code>_tags</code>; the field is restored on exit.
|
||
This allows <code>_tags</code> to use a more specific context without having to
|
||
change and reset the <code>curcontext</code> parameter (which has the same effect).</p>
|
||
<p><span id="index-_005ftilde_005ffiles"></span></p>
|
||
<p><code>_tilde_files</code></p>
|
||
<p>Like <code>_files</code>, but resolve leading tildes according to the rules of
|
||
filename expansion, so the suggested completions don’t start with a
|
||
‘<code>~</code>’ even if the filename on the command-line does.</p>
|
||
<p><span id="index-_005fvalues"></span></p>
|
||
<p><code>_values</code> [ <code>-O</code> <code>name</code> ] [ <code>-s</code> <code>sep</code> ] [ <code>-S</code> <code>sep</code> ] [ <code>-wC</code>
|
||
] <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 ‘<code>-O</code> <code>name</code>’, it will be used in
|
||
the same way as by the <code>_arguments</code> function. In other words, the
|
||
elements of the <code>name</code> array will be passed to <code>compadd</code> when executing
|
||
an action.</p>
|
||
<p>If the first argument (or the first argument after ‘<code>-O</code> <code>name</code>’) is
|
||
‘<code>-s</code>’, 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
|
||
‘<code>_values -s</code>’ appear in the same word on the command line, unlike
|
||
completion using <code>_arguments</code>. If this option is not present, only a
|
||
single value will be completed per word.</p>
|
||
<p>Normally, <code>_values</code> 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 <code>-w</code> 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 <code>_arguments</code>
|
||
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 <code>-S</code> (like <code>-s</code>, 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-example">_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: ‘<code>foo</code>’, ‘<code>one</code>’, and ‘<code>two</code>’. The
|
||
first is described as ‘<code>bar</code>’, takes no argument and may appear more
|
||
than once. The second is described as ‘<code>number</code>’, may appear more than
|
||
once, and takes one mandatory argument described as ‘<code>first count</code>’; no
|
||
action is specified, so it will not be completed. The ‘<code>(two)</code>’ at the
|
||
beginning says that if the value ‘<code>one</code>’ is on the line, the value
|
||
‘<code>two</code>’ will no longer be considered a possible completion. Finally,
|
||
the last value (‘<code>two</code>’) is described as ‘<code>another number</code>’ and takes an
|
||
optional argument described as ‘<code>second count</code>’ for which the
|
||
completions (to appear after an ‘<code>=</code>’) are ‘<code>1</code>’, ‘<code>2</code>’, and ‘<code>3</code>’. The
|
||
<code>_values</code> function will complete lists of these values separated by
|
||
commas.</p>
|
||
<p>Like <code>_arguments</code>, 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 <code>verbose</code> is used to decide if the descriptions for the values
|
||
(but not those for the arguments) should be printed.</p>
|
||
<p>The associative array <code>val_args</code> is used to report values and their
|
||
arguments; this works similarly to the <code>opt_args</code> associative array used
|
||
by <code>_arguments</code>. Hence the function calling <code>_values</code> should declare the
|
||
local parameters <code>state</code>, <code>state_descr</code>, <code>line</code>, <code>context</code> and
|
||
<code>val_args</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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
|
||
<code>context</code> parameter will be set to the name of the value whose argument
|
||
is to be completed. Note that for <code>_values</code>, the <code>state</code> and
|
||
<code>state_descr</code> are scalars rather than arrays. Only a single matching
|
||
state is returned.</p>
|
||
<p>Note also that <code>_values</code> normally adds the character used as the
|
||
separator between values as an auto-removable suffix (similar to a ‘<code>/</code>’
|
||
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 ‘<code>-qS</code> <code>x</code>’ either
|
||
directly or indirectly to <code>compadd</code>.</p>
|
||
<p>The option <code>-C</code> is treated in the same way as it is by <code>_arguments</code>. In
|
||
that case the parameter <code>curcontext</code> should be made local instead of
|
||
<code>context</code> (as described above).</p>
|
||
<p><span id="index-_005fwanted"></span></p>
|
||
<p><code>_wanted</code> [ <code>-x</code> ] [ <code>-C</code> <code>name</code> ] [ <code>-12VJ</code> ] <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 <code>_wanted</code> are the same as those to <code>_requested</code>, i.e.
|
||
arguments to be passed to <code>_description</code>. 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 <code>_wanted</code>.</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-example">local expl
|
||
_wanted tag expl 'description' \
|
||
compadd matches...
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that, as for <code>_requested</code>, the <code>command</code> must be able to accept
|
||
options to be passed down to <code>compadd</code>.</p>
|
||
<p>Like <code>_tags</code> this function supports the <code>-C</code> option to give a different
|
||
name for the argument context field. The <code>-x</code> option has the same
|
||
meaning as for <code>_description</code>.</p>
|
||
<p><span id="index-_005fwidgets"></span></p>
|
||
<p><code>_widgets</code> [ <code>-g</code> <code>pattern</code> ]</p>
|
||
<p>This function completes names of zle widgets (see
|
||
<a href="Zsh-Line-Editor.html#Zle-Widgets">Widgets</a>). The <code>pattern</code>, if present,
|
||
is matched against values of the <code>$widgets</code> 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 <code>_main_complete</code>
|
||
function and then used from other functions.</p>
|
||
<p>The standard variables are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>_comp_caller_options</code><br />
|
||
The completion system uses <code>setopt</code> 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 <code>_comp_caller_options</code> associative array.
|
||
Option names, spelled in lowercase without underscores, are mapped
|
||
to one or other of the strings ‘<code>on</code>’ and ‘<code>off</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>_comp_priv_prefix</code><br />
|
||
Completion functions such as <code>_sudo</code> can set the <code>_comp_priv_prefix</code>
|
||
array to a command prefix that may then be used by <code>_call_program</code>
|
||
to match the privileges when calling programs to generate matches.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Two more features are offered by the <code>_main_complete</code> function. The
|
||
arrays <code>compprefuncs</code> and <code>comppostfuncs</code> 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 <code>Completion</code> 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 <code>fpath</code>
|
||
than the standard directory where it appears.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>Base</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>Zsh</code><br />
|
||
Functions for completing arguments of shell builtin commands and
|
||
utility functions for this. Some of these are also used by functions
|
||
from the <code>Unix</code> directory.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Unix</code><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 <code>mount</code> 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 <code>-``-help</code> option is supported.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>X</code>, <code>AIX</code>, <code>BSD</code>, ...<br />
|
||
Completion and utility function for commands available only on some
|
||
systems. These are not arranged hierarchically, so, for example,
|
||
both the <code>Linux</code> and <code>Debian</code> directories, as well as the <code>X</code>
|
||
directory, may be useful on your system.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p>This document was generated on <em>February 15, 2020</em> using
|
||
<a href="http://www.nongnu.org/texi2html/"><em>texi2html 5.0</em></a>.<br />
|
||
Zsh version 5.8, released on February 14, 2020.</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">
|
||
var socket = new WebSocket("ws://localhost:3000/__livereload");
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|