1392 lines
77 KiB
HTML
1392 lines
77 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Completion Widgets - 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" class="active"><strong aria-hidden="true">19.</strong> Completion Widgets</a></li><li class="chapter-item expanded "><a href="Completion-System.html"><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" 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="#19-completion-widgets">19 Completion Widgets</a>
|
||
<ul>
|
||
<li><a href="#191-description">19.1 Description</a></li>
|
||
<li><a href="#192-completion-special-parameters">19.2 Completion Special Parameters</a></li>
|
||
<li><a href="#193-completion-builtin-commands">19.3 Completion Builtin Commands</a></li>
|
||
<li><a href="#194-completion-condition-codes">19.4 Completion Condition Codes</a></li>
|
||
<li><a href="#195-completion-matching-control">19.5 Completion Matching Control</a></li>
|
||
<li><a href="#196-completion-widget-example">19.6 Completion Widget Example</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Completion-Widgets"></span>
|
||
<span id="Completion-Widgets-1"></span></p>
|
||
<h1 id="19-completion-widgets"><a class="header" href="#19-completion-widgets">19 Completion Widgets</a></h1>
|
||
<p><span id="index-completion_002c-widgets"></span>
|
||
<span id="index-completion_002c-programmable"></span>
|
||
<span id="index-completion_002c-controlling"></span></p>
|
||
<hr />
|
||
<p><span id="Description-1"></span></p>
|
||
<h2 id="191-description"><a class="header" href="#191-description">19.1 Description</a></h2>
|
||
<p>The shell’s programmable completion mechanism can be manipulated in two
|
||
ways; here the low-level features supporting the newer, function-based
|
||
mechanism are defined. A complete set of shell functions based on these
|
||
features is described in the next chapter, <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>, and users with no
|
||
interest in adding to that system (or, potentially, writing their own —
|
||
see dictionary entry for ‘hubris’) should skip the current section. The
|
||
older system based on the <code>compctl</code> builtin command is described in
|
||
<a href="Completion-Using-compctl.html#Completion-Using-compctl">Completion Using
|
||
compctl</a>.</p>
|
||
<p>Completion widgets are defined by the <code>-C</code> option to the <code>zle</code> builtin
|
||
command provided by the <code>zsh/zle</code> module (see <a href="Zsh-Modules.html#The-zsh_002fzle-Module">The zsh/zle
|
||
Module</a>). For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -C complete expand-or-complete completer
|
||
</code></pre>
|
||
</div>
|
||
<p>defines a widget named ‘<code>complete</code>’. The second argument is the name of
|
||
any of the builtin widgets that handle completions: <code>complete-word</code>,
|
||
<code>expand-or-complete</code>, <code>expand-or-complete-prefix</code>, <code>menu-complete</code>,
|
||
<code>menu-expand-or-complete</code>, <code>reverse-menu-complete</code>, <code>list-choices</code>, or
|
||
<code>delete-char-or-list</code>. Note that this will still work even if the widget
|
||
in question has been re-bound.</p>
|
||
<p>When this newly defined widget is bound to a key using the <code>bindkey</code>
|
||
builtin command defined in the <code>zsh/zle</code> module (<a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>), typing that key will
|
||
call the shell function ‘<code>completer</code>’. This function is responsible for
|
||
generating the possible matches using the builtins described below. As
|
||
with other ZLE widgets, the function is called with its standard input
|
||
closed.</p>
|
||
<p>Once the function returns, the completion code takes over control again
|
||
and treats the matches in the same manner as the specified builtin
|
||
widget, in this case <code>expand-or-complete</code>.</p>
|
||
<hr />
|
||
<p><span id="Completion-Special-Parameters"></span>
|
||
<span id="Completion-Special-Parameters-1"></span></p>
|
||
<h2 id="192-completion-special-parameters"><a class="header" href="#192-completion-special-parameters">19.2 Completion Special Parameters</a></h2>
|
||
<p>The parameters <code>ZLE_REMOVE_SUFFIX_CHARS</code> and <code>ZLE_SPACE_SUFFIX_CHARS</code>
|
||
are used by the completion mechanism, but are not special. See
|
||
<a href="Parameters.html#Parameters-Used-By-The-Shell">Parameters Used By The
|
||
Shell</a>.</p>
|
||
<p>Inside completion widgets, and any functions called from them, some
|
||
parameters have special meaning; outside these functions they are not
|
||
special to the shell in any way. These parameters are used to pass
|
||
information between the completion code and the completion widget. Some
|
||
of the builtin commands and the condition codes use or change the
|
||
current values of these parameters. Any existing values will be hidden
|
||
during execution of completion widgets; except for <code>compstate</code>, the
|
||
parameters are reset on each function exit (including nested function
|
||
calls from within the completion widget) to the values they had when the
|
||
function was entered.</p>
|
||
<p><span id="index-CURRENT"></span></p>
|
||
<p><code>CURRENT</code></p>
|
||
<p>This is the number of the current word, i.e. the word the cursor is
|
||
currently on in the <code>words</code> array. Note that this value is only correct
|
||
if the <code>ksharrays</code> option is not set.</p>
|
||
<p><span id="index-IPREFIX"></span></p>
|
||
<p><code>IPREFIX</code></p>
|
||
<p>Initially this will be set to the empty string. This parameter functions
|
||
like <code>PREFIX</code>; it contains a string which precedes the one in <code>PREFIX</code>
|
||
and is not considered part of the list of matches. Typically, a string
|
||
is transferred from the beginning of <code>PREFIX</code> to the end of <code>IPREFIX</code>,
|
||
for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">IPREFIX=${PREFIX%%\=*}=
|
||
PREFIX=${PREFIX#*=}
|
||
</code></pre>
|
||
</div>
|
||
<p>causes the part of the prefix up to and including the first equal sign
|
||
not to be treated as part of a matched string. This can be done
|
||
automatically by the <code>compset</code> builtin, see below.</p>
|
||
<p><span id="index-ISUFFIX"></span></p>
|
||
<p><code>ISUFFIX</code></p>
|
||
<p>As <code>IPREFIX</code>, but for a suffix that should not be considered part of the
|
||
matches; note that the <code>ISUFFIX</code> string follows the <code>SUFFIX</code> string.</p>
|
||
<p><span id="index-PREFIX"></span></p>
|
||
<p><code>PREFIX</code></p>
|
||
<p>Initially this will be set to the part of the current word from the
|
||
beginning of the word up to the position of the cursor; it may be
|
||
altered to give a common prefix for all matches.</p>
|
||
<p><span id="index-QIPREFIX"></span></p>
|
||
<p><code>QIPREFIX</code></p>
|
||
<p>This parameter is read-only and contains the quoted string up to the
|
||
word being completed. E.g. when completing ‘<code>"foo</code>’, this parameter
|
||
contains the double quote. If the <code>-q</code> option of <code>compset</code> is used (see
|
||
below), and the original string was ‘<code>"foo bar</code>’ with the cursor on the
|
||
‘<code>bar</code>’, this parameter contains ‘<code>"foo </code>’.</p>
|
||
<p><span id="index-QISUFFIX"></span></p>
|
||
<p><code>QISUFFIX</code></p>
|
||
<p>Like <code>QIPREFIX</code>, but containing the suffix.</p>
|
||
<p><span id="index-SUFFIX"></span></p>
|
||
<p><code>SUFFIX</code></p>
|
||
<p>Initially this will be set to the part of the current word from the
|
||
cursor position to the end; it may be altered to give a common suffix
|
||
for all matches. It is most useful when the option <code>COMPLETE_IN_WORD</code> is
|
||
set, as otherwise the whole word on the command line is treated as a
|
||
prefix.</p>
|
||
<p><span id="index-compstate"></span>
|
||
<span id="index-completion-widgets_002c-examining-and-setting-state-in"></span></p>
|
||
<p><code>compstate</code></p>
|
||
<p>This is an associative array with various keys and values that the
|
||
completion code uses to exchange information with the completion widget.
|
||
The keys are:</p>
|
||
<p><span id="index-all_005fquotes_002c-compstate"></span></p>
|
||
<p><code>all_quotes</code></p>
|
||
<p>The <code>-q</code> option of the <code>compset</code> builtin command (see below) allows a
|
||
quoted string to be broken into separate words; if the cursor is on one
|
||
of those words, that word will be completed, possibly invoking ‘<code>compset -q</code>’ recursively. With this key it is possible to test the types of
|
||
quoted strings which are currently broken into parts in this fashion.
|
||
Its value contains one character for each quoting level. The characters
|
||
are a single quote or a double quote for strings quoted with these
|
||
characters, a dollars sign for strings quoted with <code>$’``...``’</code> and a
|
||
backslash for strings not starting with a quote character. The first
|
||
character in the value always corresponds to the innermost quoting
|
||
level.</p>
|
||
<p><span id="index-context_002c-compstate"></span></p>
|
||
<p><code>context</code></p>
|
||
<p>This will be set by the completion code to the overall context in which
|
||
completion is attempted. Possible values are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>array_value</code><br />
|
||
when completing inside the value of an array parameter assignment;
|
||
in this case the <code>words</code> array contains the words inside the
|
||
parentheses.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>brace_parameter</code><br />
|
||
when completing the name of a parameter in a parameter expansion
|
||
beginning with <code>${</code>. This context will also be set when completing
|
||
parameter flags following <code>${(</code>; the full command line argument is
|
||
presented and the handler must test the value to be completed to
|
||
ascertain that this is the case.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>assign_parameter</code><br />
|
||
when completing the name of a parameter in a parameter assignment.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>command</code><br />
|
||
when completing for a normal command (either in command position or
|
||
for an argument of the command).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>condition</code><br />
|
||
when completing inside a ‘<code>[[</code>...<code>]]</code>’ conditional expression; in
|
||
this case the <code>words</code> array contains only the words inside the
|
||
conditional expression.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>math</code><br />
|
||
when completing in a mathematical environment such as a
|
||
‘<code>((</code>...<code>))</code>’ construct.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>parameter</code><br />
|
||
when completing the name of a parameter in a parameter expansion
|
||
beginning with <code>$</code> but not <code>${</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>redirect</code><br />
|
||
when completing after a redirection operator.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>subscript</code><br />
|
||
when completing inside a parameter subscript.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>value</code><br />
|
||
when completing the value of a parameter assignment.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-exact_002c-compstate"></span></p>
|
||
<p><code>exact</code></p>
|
||
<p>Controls the behaviour when the <code>REC_EXACT</code> option is set. It will be
|
||
set to <code>accept</code> if an exact match would be accepted, and will be unset
|
||
otherwise.</p>
|
||
<p>If it was set when at least one match equal to the string on the line
|
||
was generated, the match is accepted.</p>
|
||
<p><span id="index-exact_005fstring_002c-compstate"></span></p>
|
||
<p><code>exact_string</code></p>
|
||
<p>The string of an exact match if one was found, otherwise unset.</p>
|
||
<p><span id="index-ignored_002c-compstate"></span></p>
|
||
<p><code>ignored</code></p>
|
||
<p>The number of words that were ignored because they matched one of the
|
||
patterns given with the <code>-F</code> option to the <code>compadd</code> builtin command.</p>
|
||
<p><span id="index-insert_002c-compstate"></span></p>
|
||
<p><code>insert</code></p>
|
||
<p>This controls the manner in which a match is inserted into the command
|
||
line. On entry to the widget function, if it is unset the command line
|
||
is not to be changed; if set to <code>unambiguous</code>, any prefix common to all
|
||
matches is to be inserted; if set to <code>automenu-unambiguous</code>, the common
|
||
prefix is to be inserted and the next invocation of the completion code
|
||
may start menu completion (due to the <code>AUTO_MENU</code> option being set); if
|
||
set to <code>menu</code> or <code>automenu</code> menu completion will be started for the
|
||
matches currently generated (in the latter case this will happen because
|
||
the <code>AUTO_MENU</code> is set). The value may also contain the string ‘<code>tab</code>’
|
||
when the completion code would normally not really do completion, but
|
||
only insert the TAB character.</p>
|
||
<p>On exit it may be set to any of the values above (where setting it to
|
||
the empty string is the same as unsetting it), or to a number, in which
|
||
case the match whose number is given will be inserted into the command
|
||
line. Negative numbers count backward from the last match (with ‘<code>-1</code>’
|
||
selecting the last match) and out-of-range values are wrapped around, so
|
||
that a value of zero selects the last match and a value one more than
|
||
the maximum selects the first. Unless the value of this key ends in a
|
||
space, the match is inserted as in a menu completion, i.e. without
|
||
automatically appending a space.</p>
|
||
<p>Both <code>menu</code> and <code>automenu</code> may also specify the number of the match to
|
||
insert, given after a colon. For example, ‘<code>menu:2</code>’ says to start menu
|
||
completion, beginning with the second match.</p>
|
||
<p>Note that a value containing the substring ‘<code>tab</code>’ makes the matches
|
||
generated be ignored and only the TAB be inserted.</p>
|
||
<p>Finally, it may also be set to <code>all</code>, which makes all matches generated
|
||
be inserted into the line.</p>
|
||
<p><span id="index-insert_005fpositions_002c-compstate"></span></p>
|
||
<p><code>insert_positions</code></p>
|
||
<p>When the completion system inserts an unambiguous string into the line,
|
||
there may be multiple places where characters are missing or where the
|
||
character inserted differs from at least one match. The value of this
|
||
key contains a colon separated list of all these positions, as indexes
|
||
into the command line.</p>
|
||
<p><span id="index-last_005fprompt_002c-compstate"></span></p>
|
||
<p><code>last_prompt</code></p>
|
||
<p>If this is set to a non-empty string for every match added, the
|
||
completion code will move the cursor back to the previous prompt after
|
||
the list of completions has been displayed. Initially this is set or
|
||
unset according to the <code>ALWAYS_LAST_PROMPT</code> option.</p>
|
||
<p><span id="index-list_002c-compstate"></span></p>
|
||
<p><code>list</code></p>
|
||
<p>This controls whether or how the list of matches will be displayed. If
|
||
it is unset or empty they will never be listed; if its value begins with
|
||
<code>list</code>, they will always be listed; if it begins with <code>autolist</code> or
|
||
<code>ambiguous</code>, they will be listed when the <code>AUTO_LIST</code> or
|
||
<code>LIST_AMBIGUOUS</code> options respectively would normally cause them to be.</p>
|
||
<p>If the substring <code>force</code> appears in the value, this makes the list be
|
||
shown even if there is only one match. Normally, the list would be shown
|
||
only if there are at least two matches.</p>
|
||
<p>The value contains the substring <code>packed</code> if the <code>LIST_PACKED</code> option is
|
||
set. If this substring is given for all matches added to a group, this
|
||
group will show the <code>LIST_PACKED</code> behavior. The same is done for the
|
||
<code>LIST_ROWS_FIRST</code> option with the substring <code>rows</code>.</p>
|
||
<p>Finally, if the value contains the string <code>explanations</code>, only the
|
||
explanation strings, if any, will be listed and if it contains
|
||
<code>messages</code>, only the messages (added with the <code>-x</code> option of <code>compadd</code>)
|
||
will be listed. If it contains both <code>explanations</code> and <code>messages</code> both
|
||
kinds of explanation strings will be listed. It will be set
|
||
appropriately on entry to a completion widget and may be changed there.</p>
|
||
<p><span id="index-list_005flines_002c-compstate"></span></p>
|
||
<p><code>list_lines</code></p>
|
||
<p>This gives the number of lines that are needed to display the full list
|
||
of completions. Note that to calculate the total number of lines to
|
||
display you need to add the number of lines needed for the command line
|
||
to this value, this is available as the value of the <code>BUFFERLINES</code>
|
||
special parameter.</p>
|
||
<p><span id="index-list_005fmax_002c-compstate"></span></p>
|
||
<p><code>list_max</code></p>
|
||
<p>Initially this is set to the value of the <code>LISTMAX</code> parameter. It may be
|
||
set to any other value; when the widget exits this value will be used in
|
||
the same way as the value of <code>LISTMAX</code>.</p>
|
||
<p><span id="index-nmatches_002c-compstate"></span></p>
|
||
<p><code>nmatches</code></p>
|
||
<p>The number of matches generated and accepted by the completion code so
|
||
far.</p>
|
||
<p><span id="index-old_005finsert_002c-compstate"></span></p>
|
||
<p><code>old_insert</code></p>
|
||
<p>On entry to the widget this will be set to the number of the match of an
|
||
old list of completions that is currently inserted into the command
|
||
line. If no match has been inserted, this is unset.</p>
|
||
<p>As with <code>old_list</code>, the value of this key will only be used if it is the
|
||
string <code>keep</code>. If it was set to this value by the widget and there was
|
||
an old match inserted into the command line, this match will be kept and
|
||
if the value of the <code>insert</code> key specifies that another match should be
|
||
inserted, this will be inserted after the old one.</p>
|
||
<p><span id="index-old_005flist_002c-compstate"></span></p>
|
||
<p><code>old_list</code></p>
|
||
<p>This is set to <code>yes</code> if there is still a valid list of completions from
|
||
a previous completion at the time the widget is invoked. This will
|
||
usually be the case if and only if the previous editing operation was a
|
||
completion widget or one of the builtin completion functions. If there
|
||
is a valid list and it is also currently shown on the screen, the value
|
||
of this key is <code>shown</code>.</p>
|
||
<p>After the widget has exited the value of this key is only used if it was
|
||
set to <code>keep</code>. In this case the completion code will continue to use
|
||
this old list. If the widget generated new matches, they will not be
|
||
used.</p>
|
||
<p><span id="index-parameter_002c-compstate"></span></p>
|
||
<p><code>parameter</code></p>
|
||
<p>The name of the parameter when completing in a subscript or in the value
|
||
of a parameter assignment.</p>
|
||
<p><span id="index-pattern_005finsert_002c-compstate"></span></p>
|
||
<p><code>pattern_insert</code></p>
|
||
<p>Normally this is set to <code>menu</code>, which specifies that menu completion
|
||
will be used whenever a set of matches was generated using pattern
|
||
matching. If it is set to any other non-empty string by the user and
|
||
menu completion is not selected by other option settings, the code will
|
||
instead insert any common prefix for the generated matches as with
|
||
normal completion.</p>
|
||
<p><span id="index-pattern_005fmatch_002c-compstate"></span></p>
|
||
<p><code>pattern_match</code></p>
|
||
<p>Locally controls the behaviour given by the <code>GLOB_COMPLETE</code> option.
|
||
Initially it is set to ‘<code>*</code>’ if and only if the option is set. The
|
||
completion widget may set it to this value, to an empty string (which
|
||
has the same effect as unsetting it), or to any other non-empty string.
|
||
If it is non-empty, unquoted metacharacters on the command line will be
|
||
treated as patterns; if it is ‘<code>*</code>’, then additionally a wildcard ‘<code>*</code>’
|
||
is assumed at the cursor position; if it is empty or unset,
|
||
metacharacters will be treated literally.</p>
|
||
<p>Note that the matcher specifications given to the <code>compadd</code> builtin
|
||
command are not used if this is set to a non-empty string.</p>
|
||
<p><span id="index-quote_002c-compstate"></span></p>
|
||
<p><code>quote</code></p>
|
||
<p>When completing inside quotes, this contains the quotation character
|
||
(i.e. either a single quote, a double quote, or a backtick). Otherwise
|
||
it is unset.</p>
|
||
<p><span id="index-quoting_002c-compstate"></span></p>
|
||
<p><code>quoting</code></p>
|
||
<p>When completing inside single quotes, this is set to the string
|
||
<code>single</code>; inside double quotes, the string <code>double</code>; inside backticks,
|
||
the string <code>backtick</code>. Otherwise it is unset.</p>
|
||
<p><span id="index-redirect_002c-compstate"></span></p>
|
||
<p><code>redirect</code></p>
|
||
<p>The redirection operator when completing in a redirection position, i.e.
|
||
one of <code><</code>, <code>></code>, etc.</p>
|
||
<p><span id="index-restore_002c-compstate"></span></p>
|
||
<p><code>restore</code></p>
|
||
<p>This is set to <code>auto</code> before a function is entered, which forces the
|
||
special parameters mentioned above (<code>words</code>, <code>CURRENT</code>, <code>PREFIX</code>,
|
||
<code>IPREFIX</code>, <code>SUFFIX</code>, and <code>ISUFFIX</code>) to be restored to their previous
|
||
values when the function exits. If a function unsets it or sets it to
|
||
any other string, they will not be restored.</p>
|
||
<p><span id="index-to_005fend_002c-compstate"></span></p>
|
||
<p><code>to_end</code></p>
|
||
<p>Specifies the occasions on which the cursor is moved to the end of a
|
||
string when a match is inserted. On entry to a widget function, it may
|
||
be <code>single</code> if this will happen when a single unambiguous match was
|
||
inserted or <code>match</code> if it will happen any time a match is inserted (for
|
||
example, by menu completion; this is likely to be the effect of the
|
||
<code>ALWAYS_TO_END</code> option).</p>
|
||
<p>On exit, it may be set to <code>single</code> as above. It may also be set to
|
||
<code>always</code>, or to the empty string or unset; in those cases the cursor
|
||
will be moved to the end of the string always or never respectively. Any
|
||
other string is treated as <code>match</code>.</p>
|
||
<p><span id="index-unambiguous_002c-compstate"></span></p>
|
||
<p><code>unambiguous</code></p>
|
||
<p>This key is read-only and will always be set to the common (unambiguous)
|
||
prefix the completion code has generated for all matches added so far.</p>
|
||
<p><span id="index-unambiguous_005fcursor_002c-compstate"></span></p>
|
||
<p><code>unambiguous_cursor</code></p>
|
||
<p>This gives the position the cursor would be placed at if the common
|
||
prefix in the <code>unambiguous</code> key were inserted, relative to the value of
|
||
that key. The cursor would be placed before the character whose index is
|
||
given by this key.</p>
|
||
<p><span id="index-unambiguous_005fpositions_002c-compstate"></span></p>
|
||
<p><code>unambiguous_positions</code></p>
|
||
<p>This contains all positions where characters in the unambiguous string
|
||
are missing or where the character inserted differs from at least one of
|
||
the matches. The positions are given as indexes into the string given by
|
||
the value of the <code>unambiguous</code> key.</p>
|
||
<p><span id="index-vared_002c-compstate"></span></p>
|
||
<p><code>vared</code></p>
|
||
<p>If completion is called while editing a line using the <code>vared</code> builtin,
|
||
the value of this key is set to the name of the parameter given as an
|
||
argument to <code>vared</code>. This key is only set while a <code>vared</code> command is
|
||
active.</p>
|
||
<p><span id="index-words"></span></p>
|
||
<p><code>words</code></p>
|
||
<p>This array contains the words present on the command line currently
|
||
being edited.</p>
|
||
<hr />
|
||
<p><span id="Completion-Builtin-Commands"></span>
|
||
<span id="Completion-Builtin-Commands-1"></span></p>
|
||
<h2 id="193-completion-builtin-commands"><a class="header" href="#193-completion-builtin-commands">19.3 Completion Builtin Commands</a></h2>
|
||
<p><span id="index-compadd"></span>
|
||
<span id="index-completion-widgets_002c-adding-specified-matches"></span></p>
|
||
<p><code>compadd </code>[ <code>-akqQfenUl12C</code> ] [ <code>-F</code> <code>array</code> ]</p>
|
||
<p><code> </code>[<code>-P</code> <code>prefix</code> ] [ <code>-S</code> <code>suffix</code> ]</p>
|
||
<p><code> </code>[<code>-p</code> <code>hidden-prefix</code> ] [ <code>-s</code> <code>hidden-suffix</code> ]</p>
|
||
<p><code> </code>[<code>-i</code> <code>ignored-prefix</code> ] [ <code>-I</code> <code>ignored-suffix</code> ]</p>
|
||
<p><code> </code>[<code>-W</code> <code>file-prefix</code> ] [ <code>-d</code> <code>array</code> ]</p>
|
||
<p><code> </code>[<code>-J</code> <code>group-name</code> ] [ <code>-X</code> <code>explanation</code> ] [ <code>-x</code>
|
||
<code>message</code> ]</p>
|
||
<p><code> </code>[<code>-V</code> <code>group-name</code> ] [ <code>-o</code> [ <code>order</code> ] ]</p>
|
||
<p><code> </code>[<code>-r</code> <code>remove-chars</code> ] [ <code>-R</code> <code>remove-func</code> ]</p>
|
||
<p><code> </code>[<code>-D</code> <code>array</code> ] [ <code>-O</code> <code>array</code> ] [ <code>-A</code> <code>array</code> ]</p>
|
||
<p><code> </code>[<code>-E</code> <code>number</code> ]</p>
|
||
<p><code> </code>[<code>-M</code> <code>match-spec</code> ] [ <code>-``-</code> ] [ <code>words</code> ... ]</p>
|
||
<p>This builtin command can be used to add matches directly and control all
|
||
the information the completion code stores with each possible match. The
|
||
return status is zero if at least one match was added and non-zero if no
|
||
matches were added.</p>
|
||
<p>The completion code breaks the string to complete into seven fields in
|
||
the order:</p>
|
||
<blockquote>
|
||
<p><code><ipre><apre><hpre><word><hsuf><asuf><isuf></code></p>
|
||
</blockquote>
|
||
<p>The first field is an ignored prefix taken from the command line, the
|
||
contents of the <code>IPREFIX</code> parameter plus the string given with the <code>-i</code>
|
||
option. With the <code>-U</code> option, only the string from the <code>-i</code> option is
|
||
used. The field <code><apre></code> is an optional prefix string given with the
|
||
<code>-P</code> option. The <code><hpre></code> field is a string that is considered part of
|
||
the match but that should not be shown when listing completions, given
|
||
with the <code>-p</code> option; for example, functions that do filename generation
|
||
might specify a common path prefix this way. <code><word></code> is the part of the
|
||
match that should appear in the list of completions, i.e. one of the
|
||
<code>words</code> given at the end of the <code>compadd</code> command line. The suffixes
|
||
<code><hsuf></code>, <code><asuf></code> and <code><isuf></code> correspond to the prefixes <code><hpre></code>,
|
||
<code><apre></code> and <code><ipre></code> and are given by the options <code>-s</code>, <code>-S</code> and <code>-I</code>,
|
||
respectively.</p>
|
||
<p>The supported flags are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-P</code> <code>prefix</code><br />
|
||
This gives a string to be inserted before the given <code>words</code>. The
|
||
string given is not considered as part of the match and any shell
|
||
metacharacters in it will not be quoted when the string is inserted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-S</code> <code>suffix</code><br />
|
||
Like <code>-P</code>, but gives a string to be inserted after the match.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-p</code> <code>hidden-prefix</code><br />
|
||
This gives a string that should be inserted into the command line
|
||
before the match but that should not appear in the list of matches.
|
||
Unless the <code>-U</code> option is given, this string must be matched as part
|
||
of the string on the command line.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code> <code>hidden-suffix</code><br />
|
||
Like ‘<code>-p</code>’, but gives a string to insert after the match.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-i</code> <code>ignored-prefix</code><br />
|
||
This gives a string to insert into the command line just before any
|
||
string given with the ‘<code>-P</code>’ option. Without ‘<code>-P</code>’ the string is
|
||
inserted before the string given with ‘<code>-p</code>’ or directly before the
|
||
match.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-I</code> <code>ignored-suffix</code><br />
|
||
Like <code>-i</code>, but gives an ignored suffix.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-a</code><br />
|
||
With this flag the <code>words</code> are taken as names of arrays and the
|
||
possible matches are their values. If only some elements of the
|
||
arrays are needed, the <code>words</code> may also contain subscripts, as in
|
||
‘<code>foo[2,-1]</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-k</code><br />
|
||
With this flag the <code>words</code> are taken as names of associative arrays
|
||
and the possible matches are their keys. As for <code>-a</code>, the <code>words</code>
|
||
may also contain subscripts, as in ‘<code>foo[(R)*bar*]</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-d</code> <code>array</code><br />
|
||
This adds per-match display strings. The <code>array</code> should contain one
|
||
element per <code>word</code> given. The completion code will then display the
|
||
first element instead of the first <code>word</code>, and so on. The <code>array</code>
|
||
may be given as the name of an array parameter or directly as a
|
||
space-separated list of words in parentheses.</p>
|
||
<p>If there are fewer display strings than <code>words</code>, the leftover
|
||
<code>words</code> will be displayed unchanged and if there are more display
|
||
strings than <code>words</code>, the leftover display strings will be silently
|
||
ignored.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-l</code><br />
|
||
This option only has an effect if used together with the <code>-d</code>
|
||
option. If it is given, the display strings are listed one per line,
|
||
not arrayed in columns.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-o</code> [ <code>order</code> ]<br />
|
||
This controls the order in which matches are sorted. <code>order</code> is a
|
||
comma-separated list comprising the following possible values. These
|
||
values can be abbreviated to their initial two or three characters.
|
||
Note that the order forms part of the group name space so matches
|
||
with different orderings will not be in the same group.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>match</code><br />
|
||
If given, the order of the output is determined by the match
|
||
strings; otherwise it is determined by the display strings (i.e.
|
||
the strings given by the <code>-d</code> option). This is the default if
|
||
‘<code>-o</code>’ is specified but the <code>order</code> argument is omitted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>nosort</code><br />
|
||
This specifies that the matches are pre-sorted and their order
|
||
should be preserved. This value only makes sense alone and
|
||
cannot be combined with any others.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>numeric</code><br />
|
||
If the matches include numbers, sort them numerically rather
|
||
than lexicographically.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>reverse</code><br />
|
||
Arrange the matches backwards by reversing the sort ordering.</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>-J</code> <code>group-name</code><br />
|
||
Gives the name of the group of matches the words should be stored
|
||
in.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-V</code> <code>group-name</code><br />
|
||
Like <code>-J</code> but naming an unsorted group. This option is identical to
|
||
the combination of <code>-J</code> and <code>-o nosort</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-1</code><br />
|
||
If given together with the <code>-V</code> option, makes only consecutive
|
||
duplicates in the group be removed. If combined with the <code>-J</code>
|
||
option, this has no visible effect. Note that groups with and
|
||
without this flag are in different name spaces.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-2</code><br />
|
||
If given together with the <code>-J</code> or <code>-V</code> option, makes all duplicates
|
||
be kept. Again, groups with and without this flag are in different
|
||
name spaces.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-X</code> <code>explanation</code><br />
|
||
The <code>explanation</code> string will be printed with the list of matches,
|
||
above the group currently selected.</p>
|
||
<p>Within the <code>explanation</code>, the following sequences may be used to
|
||
specify output attributes (see <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>): ‘<code>%B</code>’, ‘<code>%S</code>’,
|
||
‘<code>%U</code>’, ‘<code>%F</code>’, ‘<code>%K</code>’ and their lower case counterparts, as well as
|
||
‘<code>%{</code>...<code>%}</code>’. ‘<code>%F</code>’, ‘<code>%K</code>’ and ‘<code>%{</code>...<code>%}</code>’ take arguments in
|
||
the same form as prompt expansion. (Note that the sequence ‘<code>%G</code>’ is
|
||
not available; an argument to ‘<code>%{</code>’ should be used instead.) The
|
||
sequence ‘<code>%%</code>’ produces a literal ‘<code>%</code>’.</p>
|
||
<p>These sequences are most often employed by users when customising
|
||
the <code>format</code> style (see <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>), but they must
|
||
also be taken into account when writing completion functions, as
|
||
passing descriptions with unescaped ‘<code>%</code>’ characters to utility
|
||
functions such as <code>_arguments</code> and <code>_message</code> may produce unexpected
|
||
results. If arbitrary text is to be passed in a description, it can
|
||
be escaped using e.g. <code>${my_str//\%/%%}</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-x</code> <code>message</code><br />
|
||
Like <code>-X</code>, but the <code>message</code> will be printed even if there are no
|
||
matches in the group.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-q</code><br />
|
||
The suffix given with <code>-S</code> will be automatically removed if the next
|
||
character typed is a blank or does not insert anything, or if the
|
||
suffix consists of only one character and the next character typed
|
||
is the same character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code> <code>remove-chars</code><br />
|
||
This is a more versatile form of the <code>-q</code> option. The suffix given
|
||
with <code>-S</code> or the slash automatically added after completing
|
||
directories will be automatically removed if the next character
|
||
typed inserts one of the characters given in the <code>remove-chars</code>.
|
||
This string is parsed as a characters class and understands the
|
||
backslash sequences used by the <code>print</code> command. For example, ‘<code>-r "a-z\t"</code>’ removes the suffix if the next character typed inserts a
|
||
lower case character or a TAB, and ‘<code>-r "^0-9"</code>’ removes the suffix
|
||
if the next character typed inserts anything but a digit. One extra
|
||
backslash sequence is understood in this string: ‘<code>\-</code>’ stands for
|
||
all characters that insert nothing. Thus ‘<code>-S "=" -q</code>’ is the same
|
||
as ‘<code>-S "=" -r "= \t\n\-"</code>’.</p>
|
||
<p>This option may also be used without the <code>-S</code> option; then any
|
||
automatically added space will be removed when one of the characters
|
||
in the list is typed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-R</code> <code>remove-func</code><br />
|
||
This is another form of the <code>-r</code> option. When a suffix has been
|
||
inserted and the completion accepted, the function <code>remove-func</code>
|
||
will be called after the next character typed. It is passed the
|
||
length of the suffix as an argument and can use the special
|
||
parameters available in ordinary (non-completion) zle widgets (see
|
||
<a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line Editor</a>) to analyse
|
||
and modify the command line.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-f</code><br />
|
||
If this flag is given, all of the matches built from <code>words</code> are
|
||
marked as being the names of files. They are not required to be
|
||
actual filenames, but if they are, and the option <code>LIST_TYPES</code> is
|
||
set, the characters describing the types of the files in the
|
||
completion lists will be shown. This also forces a slash to be added
|
||
when the name of a directory is completed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-e</code><br />
|
||
This flag can be used to tell the completion code that the matches
|
||
added are parameter names for a parameter expansion. This will make
|
||
the <code>AUTO_PARAM_SLASH</code> and <code>AUTO_PARAM_KEYS</code> options be used for the
|
||
matches.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-W</code> <code>file-prefix</code><br />
|
||
This string is a pathname that will be prepended to each of the
|
||
matches formed by the given <code>words</code> together with any prefix
|
||
specified by the <code>-p</code> option to form a complete filename for
|
||
testing. Hence it is only useful if combined with the <code>-f</code> flag, as
|
||
the tests will not otherwise be performed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-F</code> <code>array</code><br />
|
||
Specifies an array containing patterns. Words matching one of these
|
||
patterns are ignored, i.e. not considered to be possible matches.</p>
|
||
<p>The <code>array</code> may be the name of an array parameter or a list of
|
||
literal patterns enclosed in parentheses and quoted, as in ‘<code>-F "(*?.o *?.h)"</code>’. If the name of an array is given, the elements of
|
||
the array are taken as the patterns.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-Q</code><br />
|
||
This flag instructs the completion code not to quote any
|
||
metacharacters in the words when inserting them into the command
|
||
line.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-M</code> <code>match-spec</code><br />
|
||
This gives local match specifications as described below in
|
||
<a href="#Completion-Matching-Control">Completion Matching Control</a>. This
|
||
option may be given more than once. In this case all <code>match-spec</code>s
|
||
given are concatenated with spaces between them to form the
|
||
specification string to use. Note that they will only be used if the
|
||
<code>-U</code> option is not given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code><br />
|
||
Specifies that the words added are to be used as possible matches,
|
||
but are not to appear in the completion listing.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-U</code><br />
|
||
If this flag is given, all words given will be accepted and no
|
||
matching will be done by the completion code. Normally this is used
|
||
in functions that do the matching themselves.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-O</code> <code>array</code><br />
|
||
If this option is given, the <code>words</code> are <em>not</em> added to the set of
|
||
possible completions. Instead, matching is done as usual and all of
|
||
the <code>words</code> given as arguments that match the string on the command
|
||
line will be stored in the array parameter whose name is given as
|
||
<code>array</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-A</code> <code>array</code><br />
|
||
As the <code>-O</code> option, except that instead of those of the <code>words</code>
|
||
which match being stored in <code>array</code>, the strings generated
|
||
internally by the completion code are stored. For example, with a
|
||
matching specification of ‘<code>-M "L:|no="</code>’, the string ‘<code>nof</code>’ on the
|
||
command line and the string ‘<code>foo</code>’ as one of the <code>words</code>, this
|
||
option stores the string ‘<code>nofoo</code>’ in the array, whereas the <code>-O</code>
|
||
option stores the ‘<code>foo</code>’ originally given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-D</code> <code>array</code><br />
|
||
As with <code>-O</code>, the <code>words</code> are not added to the set of possible
|
||
completions. Instead, the completion code tests whether each <code>word</code>
|
||
in turn matches what is on the line. If the <code>n</code>th <code>word</code> does not
|
||
match, the <code>n</code>th element of the <code>array</code> is removed. Elements for
|
||
which the corresponding <code>word</code> is matched are retained.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-C</code><br />
|
||
This option adds a special match which expands to all other matches
|
||
when inserted into the line, even those that are added after this
|
||
option is used. Together with the <code>-d</code> option it is possible to
|
||
specify a string that should be displayed in the list for this
|
||
special match. If no string is given, it will be shown as a string
|
||
containing the strings that would be inserted for the other matches,
|
||
truncated to the width of the screen.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-E</code> <code>number</code><br />
|
||
This option adds <code>number</code> empty matches after the <code>words</code> have been
|
||
added. An empty match takes up space in completion listings but will
|
||
never be inserted in the line and can’t be selected with menu
|
||
completion or menu selection. This makes empty matches only useful
|
||
to format completion lists and to make explanatory string be shown
|
||
in completion lists (since empty matches can be given display
|
||
strings with the <code>-d</code> option). And because all but one empty string
|
||
would otherwise be removed, this option implies the <code>-V</code> and <code>-2</code>
|
||
options (even if an explicit <code>-J</code> option is given). This can be
|
||
important to note as it affects the name space into which matches
|
||
are added.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-</code><br />
|
||
<code>-``-</code><br />
|
||
This flag ends the list of flags and options. All arguments after it
|
||
will be taken as the words to use as matches even if they begin with
|
||
hyphens.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Except for the <code>-M</code> flag, if any of these flags is given more than once,
|
||
the first one (and its argument) will be used.</p>
|
||
<p><span id="index-compset"></span>
|
||
<span id="index-completion-widgets_002c-modifying-special-parameters"></span></p>
|
||
<p><code>compset -p</code> <code>number</code></p>
|
||
<p><code>compset -P</code> [ <code>number</code> ] <code>pattern</code></p>
|
||
<p><code>compset -s</code> <code>number</code></p>
|
||
<p><code>compset -S</code> [ <code>number</code> ] <code>pattern</code></p>
|
||
<p><code>compset -n</code> <code>begin</code> [ <code>end</code> ]</p>
|
||
<p><code>compset -N</code> <code>beg-pat</code> [ <code>end-pat</code> ]</p>
|
||
<p><code>compset -q</code></p>
|
||
<p>This command simplifies modification of the special parameters, while
|
||
its return status allows tests on them to be carried out.</p>
|
||
<p>The options are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-p</code> <code>number</code><br />
|
||
If the value of the <code>PREFIX</code> parameter is at least <code>number</code>
|
||
characters long, the first <code>number</code> characters are removed from it
|
||
and appended to the contents of the <code>IPREFIX</code> parameter.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-P</code> [ <code>number</code> ] <code>pattern</code><br />
|
||
If the value of the <code>PREFIX</code> parameter begins with anything that
|
||
matches the <code>pattern</code>, the matched portion is removed from <code>PREFIX</code>
|
||
and appended to <code>IPREFIX</code>.</p>
|
||
<p>Without the optional <code>number</code>, the longest match is taken, but if
|
||
<code>number</code> is given, anything up to the <code>number</code>th match is moved. If
|
||
the <code>number</code> is negative, the <code>number</code>th longest match is moved. For
|
||
example, if <code>PREFIX</code> contains the string ‘<code>a=b=c</code>’, then <code>compset -P ’*=’</code> will move the string ‘<code>a=b=</code>’ into the <code>IPREFIX</code> parameter,
|
||
but <code>compset -P 1 ’*\=’</code> will move only the string ‘<code>a=</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code> <code>number</code><br />
|
||
As <code>-p</code>, but transfer the last <code>number</code> characters from the value of
|
||
<code>SUFFIX</code> to the front of the value of <code>ISUFFIX</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-S</code> [ <code>number</code> ] <code>pattern</code><br />
|
||
As <code>-P</code>, but match the last portion of <code>SUFFIX</code> and transfer the
|
||
matched portion to the front of the value of <code>ISUFFIX</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code> <code>begin</code> [ <code>end</code> ]<br />
|
||
If the current word position as specified by the parameter <code>CURRENT</code>
|
||
is greater than or equal to <code>begin</code>, anything up to the <code>begin</code>th
|
||
word is removed from the <code>words</code> array and the value of the
|
||
parameter <code>CURRENT</code> is decremented by <code>begin</code>.</p>
|
||
<p>If the optional <code>end</code> is given, the modification is done only if the
|
||
current word position is also less than or equal to <code>end</code>. In this
|
||
case, the words from position <code>end</code> onwards are also removed from
|
||
the <code>words</code> array.</p>
|
||
<p>Both <code>begin</code> and <code>end</code> may be negative to count backwards from the
|
||
last element of the <code>words</code> array.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-N</code> <code>beg-pat</code> [ <code>end-pat</code> ]<br />
|
||
If one of the elements of the <code>words</code> array before the one at the
|
||
index given by the value of the parameter <code>CURRENT</code> matches the
|
||
pattern <code>beg-pat</code>, all elements up to and including the matching one
|
||
are removed from the <code>words</code> array and the value of <code>CURRENT</code> is
|
||
changed to point to the same word in the changed array.</p>
|
||
<p>If the optional pattern <code>end-pat</code> is also given, and there is an
|
||
element in the <code>words</code> array matching this pattern, the parameters
|
||
are modified only if the index of this word is higher than the one
|
||
given by the <code>CURRENT</code> parameter (so that the matching word has to
|
||
be after the cursor). In this case, the words starting with the one
|
||
matching <code>end-pat</code> are also removed from the <code>words</code> array. If
|
||
<code>words</code> contains no word matching <code>end-pat</code>, the testing and
|
||
modification is performed as if it were not given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-q</code><br />
|
||
The word currently being completed is split on spaces into separate
|
||
words, respecting the usual shell quoting conventions. The resulting
|
||
words are stored in the <code>words</code> array, and <code>CURRENT</code>, <code>PREFIX</code>,
|
||
<code>SUFFIX</code>, <code>QIPREFIX</code>, and <code>QISUFFIX</code> are modified to reflect the
|
||
word part that is completed.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In all the above cases the return status is zero if the test succeeded
|
||
and the parameters were modified and non-zero otherwise. This allows one
|
||
to use this builtin in tests such as:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">if compset -P '*\='; then ...
|
||
</code></pre>
|
||
</div>
|
||
<p>This forces anything up to and including the last equal sign to be
|
||
ignored by the completion code.</p>
|
||
<p><code>compcall</code> [ <code>-TD</code> ]</p>
|
||
<p>This allows the use of completions defined with the <code>compctl</code> builtin
|
||
from within completion widgets. The list of matches will be generated as
|
||
if one of the non-widget completion functions (<code>complete-word</code>, etc.)
|
||
had been called, except that only <code>compctl</code>s given for specific commands
|
||
are used. To force the code to try completions defined with the <code>-T</code>
|
||
option of <code>compctl</code> and/or the default completion (whether defined by
|
||
<code>compctl -D</code> or the builtin default) in the appropriate places, the <code>-T</code>
|
||
and/or <code>-D</code> flags can be passed to <code>compcall</code>.</p>
|
||
<p>The return status can be used to test if a matching <code>compctl</code> definition
|
||
was found. It is non-zero if a <code>compctl</code> was found and zero otherwise.</p>
|
||
<p>Note that this builtin is defined by the <code>zsh/compctl</code> module.</p>
|
||
<hr />
|
||
<p><span id="Completion-Condition-Codes"></span>
|
||
<span id="Completion-Condition-Codes-1"></span></p>
|
||
<h2 id="194-completion-condition-codes"><a class="header" href="#194-completion-condition-codes">19.4 Completion Condition Codes</a></h2>
|
||
<p><span id="index-completion-widgets_002c-condition-codes"></span></p>
|
||
<p>The following additional condition codes for use within the <code>[[</code> <code>...</code>
|
||
<code>]]</code> construct are available in completion widgets. These work on the
|
||
special parameters. All of these tests can also be performed by the
|
||
<code>compset</code> builtin, but in the case of the condition codes the contents
|
||
of the special parameters are not modified.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-prefix</code> [ <code>number</code> ] <code>pattern</code><br />
|
||
true if the test for the <code>-P</code> option of <code>compset</code> would succeed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-suffix</code> [ <code>number</code> ] <code>pattern</code><br />
|
||
true if the test for the <code>-S</code> option of <code>compset</code> would succeed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-after</code> <code>beg-pat</code><br />
|
||
true if the test of the <code>-N</code> option with only the <code>beg-pat</code> given
|
||
would succeed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-between</code> <code>beg-pat end-pat</code><br />
|
||
true if the test for the <code>-N</code> option with both patterns would
|
||
succeed.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Completion-Matching-Control"></span>
|
||
<span id="Completion-Matching-Control-1"></span></p>
|
||
<h2 id="195-completion-matching-control"><a class="header" href="#195-completion-matching-control">19.5 Completion Matching Control</a></h2>
|
||
<p>It is possible by use of the <code>-M</code> option of the <code>compadd</code> builtin
|
||
command to specify how the characters in the string to be completed
|
||
(referred to here as the command line) map onto the characters in the
|
||
list of matches produced by the completion code (referred to here as the
|
||
trial completions). Note that this is not used if the command line
|
||
contains a glob pattern and the <code>GLOB_COMPLETE</code> option is set or the
|
||
<code>pattern_match</code> of the <code>compstate</code> special association is set to a
|
||
non-empty string.</p>
|
||
<p>The <code>match-spec</code> given as the argument to the <code>-M</code> option (see
|
||
<a href="#Completion-Builtin-Commands">Completion Builtin Commands</a>) consists of
|
||
one or more matching descriptions separated by whitespace. Each
|
||
description consists of a letter followed by a colon and then the
|
||
patterns describing which character sequences on the line match which
|
||
character sequences in the trial completion. Any sequence of characters
|
||
not handled in this fashion must match exactly, as usual.</p>
|
||
<p>The forms of <code>match-spec</code> understood are as follows. In each case, the
|
||
form with an upper case initial character retains the string already
|
||
typed on the command line as the final result of completion, while with
|
||
a lower case initial character the string on the command line is changed
|
||
into the corresponding part of the trial completion.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>m:``lpat``=``tpat</code><br />
|
||
<code>M:``lpat``=``tpat</code><br />
|
||
Here, <code>lpat</code> is a pattern that matches on the command line,
|
||
corresponding to <code>tpat</code> which matches in the trial completion.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>l:``lanchor``|``lpat``=``tpat</code><br />
|
||
<code>L:``lanchor``|``lpat``=``tpat</code><br />
|
||
<code>l:``lanchor``||``ranchor``=``tpat</code><br />
|
||
<code>L:``lanchor``||``ranchor``=``tpat</code><br />
|
||
<code>b:``lpat``=``tpat</code><br />
|
||
<code>B:``lpat``=``tpat</code><br />
|
||
These letters are for patterns that are anchored by another pattern
|
||
on the left side. Matching for <code>lpat</code> and <code>tpat</code> is as for <code>m</code> and
|
||
<code>M</code>, but the pattern <code>lpat</code> matched on the command line must be
|
||
preceded by the pattern <code>lanchor</code>. The <code>lanchor</code> can be blank to
|
||
anchor the match to the start of the command line string; otherwise
|
||
the anchor can occur anywhere, but must match in both the command
|
||
line and trial completion strings.</p>
|
||
<p>If no <code>lpat</code> is given but a <code>ranchor</code> is, this matches the gap
|
||
between substrings matched by <code>lanchor</code> and <code>ranchor</code>. Unlike
|
||
<code>lanchor</code>, the <code>ranchor</code> only needs to match the trial completion
|
||
string.</p>
|
||
<p>The <code>b</code> and <code>B</code> forms are similar to <code>l</code> and <code>L</code> with an empty
|
||
anchor, but need to match only the beginning of the word on the
|
||
command line or trial completion, respectively.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>r:``lpat``|``ranchor``=``tpat</code><br />
|
||
<code>R:``lpat``|``ranchor``=``tpat</code><br />
|
||
<code>r:``lanchor``||``ranchor``=``tpat</code><br />
|
||
<code>R:``lanchor``||``ranchor``=``tpat</code><br />
|
||
<code>e:``lpat``=``tpat</code><br />
|
||
<code>E:``lpat``=``tpat</code><br />
|
||
As <code>l</code>, <code>L</code>, <code>b</code> and <code>B</code>, with the difference that the command line
|
||
and trial completion patterns are anchored on the right side. Here
|
||
an empty <code>ranchor</code> and the <code>e</code> and <code>E</code> forms force the match to the
|
||
end of the command line or trial completion string.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x:</code><br />
|
||
This form is used to mark the end of matching specifications:
|
||
subsequent specifications are ignored. In a single standalone list
|
||
of specifications this has no use but where matching specifications
|
||
are accumulated, such as from nested function calls, it can allow
|
||
one function to override another.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Each <code>lpat</code>, <code>tpat</code> or <code>anchor</code> is either an empty string or consists of
|
||
a sequence of literal characters (which may be quoted with a backslash),
|
||
question marks, character classes, and correspondence classes; ordinary
|
||
shell patterns are not used. Literal characters match only themselves,
|
||
question marks match any character, and character classes are formed as
|
||
for globbing and match any character in the given set.</p>
|
||
<p>Correspondence classes are defined like character classes, but with two
|
||
differences: they are delimited by a pair of braces, and negated classes
|
||
are not allowed, so the characters <code>!</code> and <code>^</code> have no special meaning
|
||
directly after the opening brace. They indicate that a range of
|
||
characters on the line match a range of characters in the trial
|
||
completion, but (unlike ordinary character classes) paired according to
|
||
the corresponding position in the sequence. For example, to make any
|
||
ASCII lower case letter on the line match the corresponding upper case
|
||
letter in the trial completion, you can use ‘<code>m:{a-z}={A-Z}</code>’ (however,
|
||
see below for the recommended form for this). More than one pair of
|
||
classes can occur, in which case the first class before the <code>=</code>
|
||
corresponds to the first after it, and so on. If one side has more such
|
||
classes than the other side, the superfluous classes behave like normal
|
||
character classes. In anchor patterns correspondence classes also behave
|
||
like normal character classes.</p>
|
||
<p>The standard ‘<code>[:``name``:]</code>’ forms described for standard shell
|
||
patterns (see <a href="Expansion.html#Filename-Generation">Filename Generation</a>)
|
||
may appear in correspondence classes as well as normal character
|
||
classes. The only special behaviour in correspondence classes is if the
|
||
form on the left and the form on the right are each one of <code>[:upper:]</code>,
|
||
<code>[:lower:]</code>. In these cases the character in the word and the character
|
||
on the line must be the same up to a difference in case. Hence to make
|
||
any lower case character on the line match the corresponding upper case
|
||
character in the trial completion you can use
|
||
‘<code>m:{[:lower:]}={[:upper:]}</code>’. Although the matching system does not
|
||
yet handle multibyte characters, this is likely to be a future
|
||
extension, at which point this syntax will handle arbitrary alphabets;
|
||
hence this form, rather than the use of explicit ranges, is the
|
||
recommended form. In other cases ‘<code>[:``name``:]</code>’ forms are allowed. If
|
||
the two forms on the left and right are the same, the characters must
|
||
match exactly. In remaining cases, the corresponding tests are applied
|
||
to both characters, but they are not otherwise constrained; any matching
|
||
character in one set goes with any matching character in the other set:
|
||
this is equivalent to the behaviour of ordinary character classes.</p>
|
||
<p>The pattern <code>tpat</code> may also be one or two stars, ‘<code>*</code>’ or ‘<code>**</code>’. This
|
||
means that the pattern on the command line can match any number of
|
||
characters in the trial completion. In this case the pattern must be
|
||
anchored (on either side); in the case of a single star, the <code>anchor</code>
|
||
then determines how much of the trial completion is to be included —
|
||
only the characters up to the next appearance of the anchor will be
|
||
matched. With two stars, substrings matched by the anchor can be
|
||
matched, too.</p>
|
||
<p>Examples:</p>
|
||
<p>The keys of the <code>options</code> association defined by the <code>parameter</code> module
|
||
are the option names in all-lower-case form, without underscores, and
|
||
without the optional <code>no</code> at the beginning even though the builtins
|
||
<code>setopt</code> and <code>unsetopt</code> understand option names with upper case letters,
|
||
underscores, and the optional <code>no</code>. The following alters the matching
|
||
rules so that the prefix <code>no</code> and any underscore are ignored when trying
|
||
to match the trial completions generated and upper case letters on the
|
||
line match the corresponding lower case letters in the words:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \
|
||
${(k)options}
|
||
</code></pre>
|
||
</div>
|
||
<p>The first part says that the pattern ‘<code>[nN][oO]</code>’ at the beginning (the
|
||
empty anchor before the pipe symbol) of the string on the line matches
|
||
the empty string in the list of words generated by completion, so it
|
||
will be ignored if present. The second part does the same for an
|
||
underscore anywhere in the command line string, and the third part uses
|
||
correspondence classes so that any upper case letter on the line matches
|
||
the corresponding lower case letter in the word. The use of the upper
|
||
case forms of the specification characters (<code>L</code> and <code>M</code>) guarantees that
|
||
what has already been typed on the command line (in particular the
|
||
prefix <code>no</code>) will not be deleted.</p>
|
||
<p>Note that the use of <code>L</code> in the first part means that it matches only
|
||
when at the beginning of both the command line string and the trial
|
||
completion. I.e., the string ‘<code>_NO_f</code>’ would not be completed to
|
||
‘<code>_NO_foo</code>’, nor would ‘<code>NONO_f</code>’ be completed to ‘<code>NONO_foo</code>’ because
|
||
of the leading underscore or the second ‘<code>NO</code>’ on the line which makes
|
||
the pattern fail even though they are otherwise ignored. To fix this,
|
||
one would use ‘<code>B:[nN][oO]=</code>’ instead of the first part. As described
|
||
above, this matches at the beginning of the trial completion,
|
||
independent of other characters or substrings at the beginning of the
|
||
command line word which are ignored by the same or other <code>match-spec</code>s.</p>
|
||
<p>The second example makes completion case insensitive. This is just the
|
||
same as in the option example, except here we wish to retain the
|
||
characters in the list of completions:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'm:{[:lower:]}={[:upper:]}' ...
|
||
</code></pre>
|
||
</div>
|
||
<p>This makes lower case letters match their upper case counterparts. To
|
||
make upper case letters match the lower case forms as well:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...
|
||
</code></pre>
|
||
</div>
|
||
<p>A nice example for the use of <code>*</code> patterns is partial word completion.
|
||
Sometimes you would like to make strings like ‘<code>c.s.u</code>’ complete to
|
||
strings like ‘<code>comp.source.unix</code>’, i.e. the word on the command line
|
||
consists of multiple parts, separated by a dot in this example, where
|
||
each part should be completed separately — note, however, that the case
|
||
where each part of the word, i.e. ‘<code>comp</code>’, ‘<code>source</code>’ and ‘<code>unix</code>’ in
|
||
this example, is to be completed from separate sets of matches is a
|
||
different problem to be solved by the implementation of the completion
|
||
widget. The example can be handled by:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'r:|.=* r:|=*' \
|
||
- comp.sources.unix comp.sources.misc ...
|
||
</code></pre>
|
||
</div>
|
||
<p>The first specification says that <code>lpat</code> is the empty string, while
|
||
<code>anchor</code> is a dot; <code>tpat</code> is <code>*</code>, so this can match anything except for
|
||
the ‘<code>.</code>’ from the anchor in the trial completion word. So in ‘<code>c.s.u</code>’,
|
||
the matcher sees ‘<code>c</code>’, followed by the empty string, followed by the
|
||
anchor ‘<code>.</code>’, and likewise for the second dot, and replaces the empty
|
||
strings before the anchors, giving
|
||
‘<code>c</code>[<code>omp</code>]<code>.s</code>[<code>ources</code>]<code>.u</code>[<code>nix</code>]’, where the last part of
|
||
the completion is just as normal.</p>
|
||
<p>With the pattern shown above, the string ‘<code>c.u</code>’ could not be completed
|
||
to ‘<code>comp.sources.unix</code>’ because the single star means that no dot
|
||
(matched by the anchor) can be skipped. By using two stars as in
|
||
‘<code>r:|.=**</code>’, however, ‘<code>c.u</code>’ could be completed to
|
||
‘<code>comp.sources.unix</code>’. This also shows that in some cases, especially
|
||
if the anchor is a real pattern, like a character class, the form with
|
||
two stars may result in more matches than one would like.</p>
|
||
<p>The second specification is needed to make this work when the cursor is
|
||
in the middle of the string on the command line and the option
|
||
<code>COMPLETE_IN_WORD</code> is set. In this case the completion code would
|
||
normally try to match trial completions that end with the string as
|
||
typed so far, i.e. it will only insert new characters at the cursor
|
||
position rather than at the end. However in our example we would like
|
||
the code to recognise matches which contain extra characters after the
|
||
string on the line (the ‘<code>nix</code>’ in the example). Hence we say that the
|
||
empty string at the end of the string on the line matches any characters
|
||
at the end of the trial completion.</p>
|
||
<p>More generally, the specification</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'r:|[.,_-]=* r:|=*' ...
|
||
</code></pre>
|
||
</div>
|
||
<p>allows one to complete words with abbreviations before any of the
|
||
characters in the square brackets. For example, to complete
|
||
<code>veryverylongfile.c</code> rather than <code>veryverylongheader.h</code> with the above
|
||
in effect, you can just type <code>very.c</code> before attempting completion.</p>
|
||
<p>The specifications with both a left and a right anchor are useful to
|
||
complete partial words whose parts are not separated by some special
|
||
character. For example, in some places strings have to be completed that
|
||
are formed ‘<code>LikeThis</code>’ (i.e. the separate parts are determined by a
|
||
leading upper case letter) or maybe one has to complete strings with
|
||
trailing numbers. Here one could use the simple form with only one
|
||
anchor as in:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234
|
||
</code></pre>
|
||
</div>
|
||
<p>But with this, the string ‘<code>H</code>’ would neither complete to ‘<code>FooHoo</code>’ nor
|
||
to ‘<code>LikeTHIS</code>’ because in each case there is an upper case letter
|
||
before the ‘<code>H</code>’ and that is matched by the anchor. Likewise, a ‘<code>2</code>’
|
||
would not be completed. In both cases this could be changed by using
|
||
‘<code>r:|[[:upper:]0-9]=**</code>’, but then ‘<code>H</code>’ completes to both
|
||
‘<code>LikeTHIS</code>’ and ‘<code>FooHoo</code>’ and a ‘<code>2</code>’ matches the other strings
|
||
because characters can be inserted before every upper case letter and
|
||
digit. To avoid this one would use:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \
|
||
LikeTHIS FooHoo foo123 bar234
|
||
</code></pre>
|
||
</div>
|
||
<p>By using these two anchors, a ‘<code>H</code>’ matches only upper case ‘<code>H</code>’s that
|
||
are immediately preceded by something matching the left anchor
|
||
‘<code>[^[:upper:]0-9]</code>’. The effect is, of course, that ‘<code>H</code>’ matches only
|
||
the string ‘<code>FooHoo</code>’, a ‘<code>2</code>’ matches only ‘<code>bar234</code>’ and so on.</p>
|
||
<p>When using the completion system (see <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>), users can define
|
||
match specifications that are to be used for specific contexts by using
|
||
the <code>matcher</code> and <code>matcher-list</code> styles. The values for the latter will
|
||
be used everywhere.</p>
|
||
<hr />
|
||
<p><span id="Completion-Widget-Example"></span>
|
||
<span id="Completion-Widget-Example-1"></span></p>
|
||
<h2 id="196-completion-widget-example"><a class="header" href="#196-completion-widget-example">19.6 Completion Widget Example</a></h2>
|
||
<p><span id="index-completion-widgets_002c-example"></span></p>
|
||
<p>The first step is to define the widget:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -C complete complete-word complete-files
|
||
</code></pre>
|
||
</div>
|
||
<p>Then the widget can be bound to a key using the <code>bindkey</code> builtin
|
||
command:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey '^X\t' complete
|
||
</code></pre>
|
||
</div>
|
||
<p>After that the shell function <code>complete-files</code> will be invoked after
|
||
typing control-X and TAB. The function should then generate the matches,
|
||
e.g.:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">complete-files () { compadd - * }
|
||
</code></pre>
|
||
</div>
|
||
<p>This function will complete files in the current directory matching the
|
||
current word.</p>
|
||
<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="Zsh-Line-Editor.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-System.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="Zsh-Line-Editor.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-System.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>
|