5276 lines
254 KiB
HTML
5276 lines
254 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>User Contributions - 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"><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" class="active"><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="#26-user-contributions">26 User Contributions</a>
|
||
<ul>
|
||
<li><a href="#261-description">26.1 Description</a></li>
|
||
<li><a href="#262-utilities">26.2 Utilities</a>
|
||
<ul>
|
||
<li><a href="#2621-accessing-on-line-help">26.2.1 Accessing On-Line Help</a></li>
|
||
<li><a href="#2622-recompiling-functions">26.2.2 Recompiling Functions</a></li>
|
||
<li><a href="#2623-keyboard-definition">26.2.3 Keyboard Definition</a></li>
|
||
<li><a href="#2624-dumping-shell-state">26.2.4 Dumping Shell State</a></li>
|
||
<li><a href="#2625-manipulating-hook-functions">26.2.5 Manipulating Hook Functions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#263-remembering-recent-directories">26.3 Remembering Recent Directories</a>
|
||
<ul>
|
||
<li><a href="#2631-installation">26.3.1 Installation</a></li>
|
||
<li><a href="#2632-use">26.3.2 Use</a></li>
|
||
<li><a href="#2633-options">26.3.3 Options</a></li>
|
||
<li><a href="#2634-configuration">26.3.4 Configuration</a></li>
|
||
<li><a href="#2635-use-with-dynamic-directory-naming">26.3.5 Use with dynamic directory naming</a></li>
|
||
<li><a href="#2636-details-of-directory-handling">26.3.6 Details of directory handling</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#264-abbreviated-dynamic-references-to-directories">26.4 Abbreviated dynamic references to directories</a>
|
||
<ul>
|
||
<li><a href="#2641-usage">26.4.1 Usage</a></li>
|
||
<li><a href="#2642-configuration">26.4.2 Configuration</a></li>
|
||
<li><a href="#2643-complete-example">26.4.3 Complete example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#265-gathering-information-from-version-control-systems">26.5 Gathering information from version control systems</a>
|
||
<ul>
|
||
<li><a href="#2651-quickstart">26.5.1 Quickstart</a></li>
|
||
<li><a href="#2652-configuration">26.5.2 Configuration</a></li>
|
||
<li><a href="#2653-oddities">26.5.3 Oddities</a></li>
|
||
<li><a href="#2654-quilt-support">26.5.4 Quilt Support</a></li>
|
||
<li><a href="#2655-function-descriptions-public-api">26.5.5 Function Descriptions (Public API)</a></li>
|
||
<li><a href="#2656-variable-description">26.5.6 Variable Description</a></li>
|
||
<li><a href="#2657-hooks-in-vcs%5C_info">26.5.7 Hooks in vcs_info</a></li>
|
||
<li><a href="#2658-examples">26.5.8 Examples</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#266-prompt-themes">26.6 Prompt Themes</a>
|
||
<ul>
|
||
<li><a href="#2661-installation">26.6.1 Installation</a></li>
|
||
<li><a href="#2662-theme-selection">26.6.2 Theme Selection</a></li>
|
||
<li><a href="#2663-utility-themes">26.6.3 Utility Themes</a></li>
|
||
<li><a href="#2664-writing-themes">26.6.4 Writing Themes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#267-zle-functions">26.7 ZLE Functions</a>
|
||
<ul>
|
||
<li><a href="#2671-widgets">26.7.1 Widgets</a></li>
|
||
<li><a href="#2672-utility-functions">26.7.2 Utility Functions</a></li>
|
||
<li><a href="#2673-styles">26.7.3 Styles</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#268-exception-handling">26.8 Exception Handling</a></li>
|
||
<li><a href="#269-mime-functions">26.9 MIME Functions</a></li>
|
||
<li><a href="#2610-mathematical-functions">26.10 Mathematical Functions</a></li>
|
||
<li><a href="#2611-user-configuration-functions">26.11 User Configuration Functions</a></li>
|
||
<li><a href="#2612-other-functions">26.12 Other Functions</a>
|
||
<ul>
|
||
<li><a href="#26121-descriptions">26.12.1 Descriptions</a></li>
|
||
<li><a href="#26122-styles">26.12.2 Styles</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="User-Contributions"></span>
|
||
<span id="User-Contributions-1"></span></p>
|
||
<h1 id="26-user-contributions"><a class="header" href="#26-user-contributions">26 User Contributions</a></h1>
|
||
<p><span id="index-user-contributions"></span></p>
|
||
<hr />
|
||
<p><span id="Description-2"></span></p>
|
||
<h2 id="261-description"><a class="header" href="#261-description">26.1 Description</a></h2>
|
||
<p>The Zsh source distribution includes a number of items contributed by
|
||
the user community. These are not inherently a part of the shell, and
|
||
some may not be available in every zsh installation. The most
|
||
significant of these are documented here. For documentation on other
|
||
contributed items such as shell functions, look for comments in the
|
||
function source files.</p>
|
||
<hr />
|
||
<p><span id="Utilities"></span> <span id="Utilities-1"></span></p>
|
||
<h2 id="262-utilities"><a class="header" href="#262-utilities">26.2 Utilities</a></h2>
|
||
<hr />
|
||
<p><span id="Accessing-On_002dLine-Help"></span></p>
|
||
<h3 id="2621-accessing-on-line-help"><a class="header" href="#2621-accessing-on-line-help">26.2.1 Accessing On-Line Help</a></h3>
|
||
<p><span id="index-helpfiles-utility"></span></p>
|
||
<p>The key sequence <code>ESC h</code> is normally bound by ZLE to execute the
|
||
<code>run-help</code> widget (see <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>). This invokes the
|
||
<code>run-help</code> command with the command word from the current input line as
|
||
its argument. By default, <code>run-help</code> is an alias for the <code>man</code> command,
|
||
so this often fails when the command word is a shell builtin or a
|
||
user-defined function. By redefining the <code>run-help</code> alias, one can
|
||
improve the on-line help provided by the shell.</p>
|
||
<p>The <code>helpfiles</code> utility, found in the <code>Util</code> directory of the
|
||
distribution, is a Perl program that can be used to process the zsh
|
||
manual to produce a separate help file for each shell builtin and for
|
||
many other shell features as well. The autoloadable <code>run-help</code> function,
|
||
found in <code>Functions/Misc</code>, searches for these helpfiles and performs
|
||
several other tests to produce the most complete help possible for the
|
||
command.</p>
|
||
<p>Help files are installed by default to a subdirectory of
|
||
<code>/usr/share/zsh</code> or <code>/usr/local/share/zsh</code>.</p>
|
||
<p>To create your own help files with <code>helpfiles</code>, choose or create a
|
||
directory where the individual command help files will reside. For
|
||
example, you might choose <code>~/zsh_help</code>. If you unpacked the zsh
|
||
distribution in your home directory, you would use the commands:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">mkdir ~/zsh_help
|
||
perl ~/zsh-5.8/Util/helpfiles ~/zsh_help
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-HELPDIR"></span></p>
|
||
<p>The <code>HELPDIR</code> parameter tells <code>run-help</code> where to look for the help
|
||
files. When unset, it uses the default installation path. To use your
|
||
own set of help files, set this to the appropriate path in one of your
|
||
startup files:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">HELPDIR=~/zsh_help
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-run_002dhelp_002c-use-of"></span></p>
|
||
<p>To use the <code>run-help</code> function, you need to add lines something like the
|
||
following to your <code>.zshrc</code> or equivalent startup file:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">unalias run-help
|
||
autoload run-help
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that in order for ‘<code>autoload run-help</code>’ to work, the <code>run-help</code>
|
||
file must be in one of the directories named in your <code>fpath</code> array (see
|
||
<a href="Parameters.html#Parameters-Used-By-The-Shell">Parameters Used By The
|
||
Shell</a>). This should
|
||
already be the case if you have a standard zsh installation; if it is
|
||
not, copy <code>Functions/Misc/run-help</code> to an appropriate directory.</p>
|
||
<hr />
|
||
<p><span id="Recompiling-Functions"></span></p>
|
||
<h3 id="2622-recompiling-functions"><a class="header" href="#2622-recompiling-functions">26.2.2 Recompiling Functions</a></h3>
|
||
<p><span id="index-functions_002c-recompiling"></span>
|
||
<span id="index-zrecompile-utility"></span></p>
|
||
<p>If you frequently edit your zsh functions, or periodically update your
|
||
zsh installation to track the latest developments, you may find that
|
||
function digests compiled with the <code>zcompile</code> builtin are frequently out
|
||
of date with respect to the function source files. This is not usually a
|
||
problem, because zsh always looks for the newest file when loading a
|
||
function, but it may cause slower shell startup and function loading.
|
||
Also, if a digest file is explicitly used as an element of <code>fpath</code>, zsh
|
||
won’t check whether any of its source files has changed.</p>
|
||
<p>The <code>zrecompile</code> autoloadable function, found in <code>Functions/Misc</code>, can
|
||
be used to keep function digests up to date.</p>
|
||
<p><span id="index-zrecompile"></span></p>
|
||
<p><code>zrecompile</code> [ <code>-qt</code> ] [ <code>name</code> ... ]</p>
|
||
<p><code>zrecompile</code> [ <code>-qt</code> ] <code>-p</code> <code>arg</code> ... [ <code>-``-</code> <code>arg</code> ... ]</p>
|
||
<p>This tries to find <code>*.zwc</code> files and automatically re-compile them if at
|
||
least one of the original files is newer than the compiled file. This
|
||
works only if the names stored in the compiled files are full paths or
|
||
are relative to the directory that contains the <code>.zwc</code> file.</p>
|
||
<p>In the first form, each <code>name</code> is the name of a compiled file or a
|
||
directory containing <code>*.zwc</code> files that should be checked. If no
|
||
arguments are given, the directories and <code>*.zwc</code> files in <code>fpath</code> are
|
||
used.</p>
|
||
<p>When <code>-t</code> is given, no compilation is performed, but a return status of
|
||
zero (true) is set if there are files that need to be re-compiled and
|
||
non-zero (false) otherwise. The <code>-q</code> option quiets the chatty output
|
||
that describes what <code>zrecompile</code> is doing.</p>
|
||
<p>Without the <code>-t</code> option, the return status is zero if all files that
|
||
needed re-compilation could be compiled and non-zero if compilation for
|
||
at least one of the files failed.</p>
|
||
<p>If the <code>-p</code> option is given, the <code>arg</code>s are interpreted as one or more
|
||
sets of arguments for <code>zcompile</code>, separated by ‘<code>-``-</code>’. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zrecompile -p \
|
||
-R ~/.zshrc -- \
|
||
-M ~/.zcompdump -- \
|
||
~/zsh/comp.zwc ~/zsh/Completion/*/_*
|
||
</code></pre>
|
||
</div>
|
||
<p>This compiles <code>~/.zshrc</code> into <code>~/.zshrc.zwc</code> if that doesn’t exist or if
|
||
it is older than <code>~/.zshrc</code>. The compiled file will be marked for
|
||
reading instead of mapping. The same is done for <code>~/.zcompdump</code> and
|
||
<code>~/.zcompdump.zwc</code>, but this compiled file is marked for mapping. The
|
||
last line re-creates the file <code>~/zsh/comp.zwc</code> if any of the files
|
||
matching the given pattern is newer than it.</p>
|
||
<p>Without the <code>-p</code> option, <code>zrecompile</code> does not create function digests
|
||
that do not already exist, nor does it add new functions to the digest.</p>
|
||
<p>The following shell loop is an example of a method for creating function
|
||
digests for all functions in your <code>fpath</code>, assuming that you have write
|
||
permission to the directories:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">for ((i=1; i <= $#fpath; ++i)); do
|
||
dir=$fpath[i]
|
||
zwc=${dir:t}.zwc
|
||
if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
|
||
continue
|
||
fi
|
||
files=($dir/*(N-.))
|
||
if [[ -w $dir:h && -n $files ]]; then
|
||
files=(${${(M)files%/*/*}#/})
|
||
if ( cd $dir:h &&
|
||
zrecompile -p -U -z $zwc $files ); then
|
||
fpath[i]=$fpath[i].zwc
|
||
fi
|
||
fi
|
||
done
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>-U</code> and <code>-z</code> options are appropriate for functions in the default
|
||
zsh installation <code>fpath</code>; you may need to use different options for your
|
||
personal function directories.</p>
|
||
<p>Once the digests have been created and your <code>fpath</code> modified to refer to
|
||
them, you can keep them up to date by running <code>zrecompile</code> with no
|
||
arguments.</p>
|
||
<hr />
|
||
<p><span id="Keyboard-Definition"></span></p>
|
||
<h3 id="2623-keyboard-definition"><a class="header" href="#2623-keyboard-definition">26.2.3 Keyboard Definition</a></h3>
|
||
<p><span id="index-keyboard-definition"></span>
|
||
<span id="index-zkbd"></span></p>
|
||
<p>The large number of possible combinations of keyboards, workstations,
|
||
terminals, emulators, and window systems makes it impossible for zsh to
|
||
have built-in key bindings for every situation. The <code>zkbd</code> utility,
|
||
found in <code>Functions/Misc</code>, can help you quickly create key bindings for
|
||
your configuration.</p>
|
||
<p>Run <code>zkbd</code> either as an autoloaded function, or as a shell script:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zsh -f ~/zsh-5.8/Functions/Misc/zkbd
|
||
</code></pre>
|
||
</div>
|
||
<p>When you run <code>zkbd</code>, it first asks you to enter your terminal type; if
|
||
the default it offers is correct, just press return. It then asks you to
|
||
press a number of different keys to determine characteristics of your
|
||
keyboard and terminal; <code>zkbd</code> warns you if it finds anything out of the
|
||
ordinary, such as a Delete key that sends neither <code>^H</code> nor <code>^?</code>.</p>
|
||
<p>The keystrokes read by <code>zkbd</code> are recorded as a definition for an
|
||
associative array named <code>key</code>, written to a file in the subdirectory
|
||
<code>.zkbd</code> within either your <code>HOME</code> or <code>ZDOTDIR</code> directory. The name of
|
||
the file is composed from the <code>TERM</code>, <code>VENDOR</code> and <code>OSTYPE</code> parameters,
|
||
joined by hyphens.</p>
|
||
<p>You may read this file into your <code>.zshrc</code> or another startup file with
|
||
the ‘<code>source</code>’ or ‘<code>.</code>’ commands, then reference the <code>key</code> parameter in
|
||
bindkey commands, like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
|
||
[[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
|
||
[[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
|
||
# etc.
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that in order for ‘<code>autoload zkbd</code>’ to work, the <code>zkdb</code> file must
|
||
be in one of the directories named in your <code>fpath</code> array (see
|
||
<a href="Parameters.html#Parameters-Used-By-The-Shell">Parameters Used By The
|
||
Shell</a>). This should
|
||
already be the case if you have a standard zsh installation; if it is
|
||
not, copy <code>Functions/Misc/zkbd</code> to an appropriate directory.</p>
|
||
<hr />
|
||
<p><span id="Dumping-Shell-State"></span></p>
|
||
<h3 id="2624-dumping-shell-state"><a class="header" href="#2624-dumping-shell-state">26.2.4 Dumping Shell State</a></h3>
|
||
<p><span id="index-reporter-utility"></span></p>
|
||
<p>Occasionally you may encounter what appears to be a bug in the shell,
|
||
particularly if you are using a beta version of zsh or a development
|
||
release. Usually it is sufficient to send a description of the problem
|
||
to one of the zsh mailing lists (see <a href="Introduction.html#Mailing-Lists">Mailing
|
||
Lists</a>), but sometimes one of the zsh
|
||
developers will need to recreate your environment in order to track the
|
||
problem down.</p>
|
||
<p>The script named <code>reporter</code>, found in the <code>Util</code> directory of the
|
||
distribution, is provided for this purpose. (It is also possible to
|
||
<code>autoload reporter</code>, but <code>reporter</code> is not installed in <code>fpath</code> by
|
||
default.) This script outputs a detailed dump of the shell state, in the
|
||
form of another script that can be read with ‘<code>zsh -f</code>’ to recreate that
|
||
state.</p>
|
||
<p>To use <code>reporter</code>, read the script into your shell with the ‘<code>.</code>’
|
||
command and redirect the output into a file:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">. ~/zsh-5.8/Util/reporter > zsh.report
|
||
</code></pre>
|
||
</div>
|
||
<p>You should check the <code>zsh.report</code> file for any sensitive information
|
||
such as passwords and delete them by hand before sending the script to
|
||
the developers. Also, as the output can be voluminous, it’s best to wait
|
||
for the developers to ask for this information before sending it.</p>
|
||
<p>You can also use <code>reporter</code> to dump only a subset of the shell state.
|
||
This is sometimes useful for creating startup files for the first time.
|
||
Most of the output from reporter is far more detailed than usually is
|
||
necessary for a startup file, but the <code>aliases</code>, <code>options</code>, and
|
||
<code>zstyles</code> states may be useful because they include only changes from
|
||
the defaults. The <code>bindings</code> state may be useful if you have created any
|
||
of your own keymaps, because <code>reporter</code> arranges to dump the keymap
|
||
creation commands as well as the bindings for every keymap.</p>
|
||
<p>As is usual with automated tools, if you create a startup file with
|
||
<code>reporter</code>, you should edit the results to remove unnecessary commands.
|
||
Note that if you’re using the new completion system, you should <em>not</em>
|
||
dump the <code>functions</code> state to your startup files with <code>reporter</code>; use
|
||
the <code>compdump</code> function instead (see <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>).</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>reporter</code> [ <code>state</code> ... ]<br />
|
||
<span id="index-reporter"></span></p>
|
||
<p>Print to standard output the indicated subset of the current shell
|
||
state. The <code>state</code> arguments may be one or more of:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>all</code><br />
|
||
Output everything listed below.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>aliases</code><br />
|
||
Output alias definitions.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>bindings</code><br />
|
||
Output ZLE key maps and bindings.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>completion</code><br />
|
||
Output old-style <code>compctl</code> commands. New completion is covered
|
||
by <code>functions</code> and <code>zstyles</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>functions</code><br />
|
||
Output autoloads and function definitions.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>limits</code><br />
|
||
Output <code>limit</code> commands.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>options</code><br />
|
||
Output <code>setopt</code> commands.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>styles</code><br />
|
||
Same as <code>zstyles</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>variables</code><br />
|
||
Output shell parameter assignments, plus <code>export</code> commands for
|
||
any environment variables.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyles</code><br />
|
||
Output <code>zstyle</code> commands.</p>
|
||
</li>
|
||
</ul>
|
||
<p>If the <code>state</code> is omitted, <code>all</code> is assumed.</p>
|
||
<p>With the exception of ‘<code>all</code>’, every <code>state</code> can be abbreviated by
|
||
any prefix, even a single letter; thus <code>a</code> is the same as <code>aliases</code>,
|
||
<code>z</code> is the same as <code>zstyles</code>, etc.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Manipulating-Hook-Functions"></span></p>
|
||
<h3 id="2625-manipulating-hook-functions"><a class="header" href="#2625-manipulating-hook-functions">26.2.5 Manipulating Hook Functions</a></h3>
|
||
<p><span id="index-hook-function-utility"></span></p>
|
||
<p><span id="index-add_002dzsh_002dhook"></span></p>
|
||
<p><code>add-zsh-hook</code> [ <code>-L</code> | <code>-dD</code> ] [ <code>-Uzk</code> ] <code>hook</code> <code>function</code></p>
|
||
<p>Several functions are special to the shell, as described in the section
|
||
Special Functions, <a href="Functions.html#Functions">Functions</a>, in that they
|
||
are automatically called at specific points during shell execution. Each
|
||
has an associated array consisting of names of functions to be called at
|
||
the same point; these are so-called ‘hook functions’. The shell function
|
||
<code>add-zsh-hook</code> provides a simple way of adding or removing functions
|
||
from the array.</p>
|
||
<p><code>hook</code> is one of <code>chpwd</code>, <code>periodic</code>, <code>precmd</code>, <code>preexec</code>,
|
||
<code>zshaddhistory</code>, <code>zshexit</code>, or <code>zsh_directory_name</code>, the special
|
||
functions in question. Note that <code>zsh_directory_name</code> is called in a
|
||
different way from the other functions, but may still be manipulated as
|
||
a hook.</p>
|
||
<p><code>function</code> is name of an ordinary shell function. If no options are
|
||
given this will be added to the array of functions to be executed in the
|
||
given context. Functions are invoked in the order they were added.</p>
|
||
<p>If the option <code>-L</code> is given, the current values for the hook arrays are
|
||
listed with <code>typeset</code>.</p>
|
||
<p>If the option <code>-d</code> is given, the <code>function</code> is removed from the array of
|
||
functions to be executed.</p>
|
||
<p>If the option <code>-D</code> is given, the <code>function</code> is treated as a pattern and
|
||
any matching names of functions are removed from the array of functions
|
||
to be executed.</p>
|
||
<p>The options <code>-U</code>, <code>-z</code> and <code>-k</code> are passed as arguments to <code>autoload</code>
|
||
for <code>function</code>. For functions contributed with zsh, the options <code>-Uz</code>
|
||
are appropriate.</p>
|
||
<p><span id="index-add_002dzle_002dhook_002dwidget"></span></p>
|
||
<p><code>add-zle-hook-widget</code> [ <code>-L</code> | <code>-dD</code> ] [ <code>-Uzk</code> ] <code>hook</code>
|
||
<code>widgetname</code></p>
|
||
<p>Several widget names are special to the line editor, as described in the
|
||
section Special Widgets, <a href="Zsh-Line-Editor.html#Zle-Widgets">Widgets</a>, in
|
||
that they are automatically called at specific points during editing.
|
||
Unlike function hooks, these do not use a predefined array of other
|
||
names to call at the same point; the shell function
|
||
<code>add-zle-hook-widget</code> maintains a similar array and arranges for the
|
||
special widget to invoke those additional widgets.</p>
|
||
<p><code>hook</code> is one of <code>isearch-exit</code>, <code>isearch-update</code>, <code>line-pre-redraw</code>,
|
||
<code>line-init</code>, <code>line-finish</code>, <code>history-line-set</code>, or <code>keymap-select</code>,
|
||
corresponding to each of the special widgets <code>zle-isearch-exit</code>, etc.
|
||
The special widget names are also accepted as the <code>hook</code> argument.</p>
|
||
<p><code>widgetname</code> is the name of a ZLE widget. If no options are given this
|
||
is added to the array of widgets to be invoked in the given hook
|
||
context. Widgets are invoked in the order they were added, with</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle widgetname -Nw -- "$@"
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-WIDGET_002c-in-hooks"></span></p>
|
||
<p>Note that this means that the ‘<code>WIDGET</code>’ special parameter tracks the
|
||
<code>widgetname</code> when the widget function is called, rather than tracking
|
||
the name of the corresponding special hook widget.</p>
|
||
<p>If the option <code>-d</code> is given, the <code>widgetname</code> is removed from the array
|
||
of widgets to be executed.</p>
|
||
<p>If the option <code>-D</code> is given, the <code>widgetname</code> is treated as a pattern
|
||
and any matching names of widgets are removed from the array.</p>
|
||
<p>If <code>widgetname</code> does not name an existing widget when added to the
|
||
array, it is assumed that a shell function also named <code>widgetname</code> is
|
||
meant to provide the implementation of the widget. This name is
|
||
therefore marked for autoloading, and the options <code>-U</code>, <code>-z</code> and <code>-k</code>
|
||
are passed as arguments to <code>autoload</code> as with <code>add-zsh-hook</code>. The widget
|
||
is also created with ‘<code> zle -N ``widgetname</code>’ to cause the
|
||
corresponding function to be loaded the first time the hook is called.</p>
|
||
<p>The arrays of <code>widgetname</code> are currently maintained in <code>zstyle</code>
|
||
contexts, one for each <code>hook</code> context, with a style of ‘<code>widgets</code>’. If
|
||
the <code>-L</code> option is given, this set of styles is listed with ‘<code>zstyle -L</code>’. This implementation may change, and the special widgets that
|
||
refer to the styles are created only if <code>add-zle-hook-widget</code> is called
|
||
to add at least one widget, so if this function is used for any hooks,
|
||
then all hooks should be managed only via this function.</p>
|
||
<hr />
|
||
<p><span id="Recent-Directories"></span>
|
||
<span id="index-recent-directories_002c-maintaining-list-of"></span>
|
||
<span id="index-directories_002c-maintaining-list-of-recent"></span>
|
||
<span id="index-cdr"></span> <span id="index-_005fcdr"></span>
|
||
<span id="index-chpwd_005frecent_005fadd"></span>
|
||
<span id="index-chpwd_005frecent_005fdirs"></span>
|
||
<span id="index-chpwd_005frecent_005ffilehandler"></span>
|
||
<span id="Remembering-Recent-Directories"></span></p>
|
||
<h2 id="263-remembering-recent-directories"><a class="header" href="#263-remembering-recent-directories">26.3 Remembering Recent Directories</a></h2>
|
||
<p>The function <code>cdr</code> allows you to change the working directory to a
|
||
previous working directory from a list maintained automatically. It is
|
||
similar in concept to the directory stack controlled by the <code>pushd</code>,
|
||
<code>popd</code> and <code>dirs</code> builtins, but is more configurable, and as it stores
|
||
all entries in files it is maintained across sessions and (by default)
|
||
between terminal emulators in the current session. Duplicates are
|
||
automatically removed, so that the list reflects the single most recent
|
||
use of each directory.</p>
|
||
<p>Note that the <code>pushd</code> directory stack is not actually modified or used
|
||
by <code>cdr</code> unless you configure it to do so as described in the
|
||
configuration section below.</p>
|
||
<hr />
|
||
<p><span id="Installation-3"></span></p>
|
||
<h3 id="2631-installation"><a class="header" href="#2631-installation">26.3.1 Installation</a></h3>
|
||
<p>The system works by means of a hook function that is called every time
|
||
the directory changes. To install the system, autoload the required
|
||
functions and use the <code>add-zsh-hook</code> function described above:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -Uz chpwd_recent_dirs cdr add-zsh-hook
|
||
add-zsh-hook chpwd chpwd_recent_dirs
|
||
</code></pre>
|
||
</div>
|
||
<p>Now every time you change directly interactively, no matter which
|
||
command you use, the directory to which you change will be remembered in
|
||
most-recent-first order.</p>
|
||
<hr />
|
||
<p><span id="Use"></span></p>
|
||
<h3 id="2632-use"><a class="header" href="#2632-use">26.3.2 Use</a></h3>
|
||
<p>All direct user interaction is via the <code>cdr</code> function.</p>
|
||
<p>The argument to cdr is a number <code>N</code> corresponding to the <code>N</code>th most
|
||
recently changed-to directory. 1 is the immediately preceding directory;
|
||
the current directory is remembered but is not offered as a destination.
|
||
Note that if you have multiple windows open 1 may refer to a directory
|
||
changed to in another window; you can avoid this by having per-terminal
|
||
files for storing directory as described for the <code>recent-dirs-file</code>
|
||
style below.</p>
|
||
<p>If you set the <code>recent-dirs-default</code> style described below <code>cdr</code> will
|
||
behave the same as <code>cd</code> if given a non-numeric argument, or more than
|
||
one argument. The recent directory list is updated just the same however
|
||
you change directory.</p>
|
||
<p>If the argument is omitted, 1 is assumed. This is similar to <code>pushd</code>’s
|
||
behaviour of swapping the two most recent directories on the stack.</p>
|
||
<p>Completion for the argument to <code>cdr</code> is available if compinit has been
|
||
run; menu selection is recommended, using:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*:*:cdr:*:*' menu selection
|
||
</code></pre>
|
||
</div>
|
||
<p>to allow you to cycle through recent directories; the order is
|
||
preserved, so the first choice is the most recent directory before the
|
||
current one. The verbose style is also recommended to ensure the
|
||
directory is shown; this style is on by default so no action is required
|
||
unless you have changed it.</p>
|
||
<hr />
|
||
<p><span id="Options-2"></span></p>
|
||
<h3 id="2633-options"><a class="header" href="#2633-options">26.3.3 Options</a></h3>
|
||
<p>The behaviour of <code>cdr</code> may be modified by the following options.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-l</code><br />
|
||
lists the numbers and the corresponding directories in abbreviated
|
||
form (i.e. with <code>~</code> substitution reapplied), one per line. The
|
||
directories here are not quoted (this would only be an issue if a
|
||
directory name contained a newline). This is used by the completion
|
||
system.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><br />
|
||
sets the variable <code>reply</code> to the current set of directories. Nothing
|
||
is printed and the directory is not changed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-e</code><br />
|
||
allows you to edit the list of directories, one per line. The list
|
||
can be edited to any extent you like; no sanity checking is
|
||
performed. Completion is available. No quoting is necessary (except
|
||
for newlines, where I have in any case no sympathy); directories are
|
||
in unabbreviated from and contain an absolute path, i.e. they start
|
||
with <code>/</code>. Usually the first entry should be left as the current
|
||
directory.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-p ’``pattern``’</code><br />
|
||
Prunes any items in the directory list that match the given extended
|
||
glob pattern; the pattern needs to be quoted from immediate
|
||
expansion on the command line. The pattern is matched against each
|
||
completely expanded file name in the list; the full string must
|
||
match, so wildcards at the end (e.g. <code>’*removeme*’</code>) are needed to
|
||
remove entries with a given substring.</p>
|
||
<p>If output is to a terminal, then the function will print the new
|
||
list after pruning and prompt for confirmation by the user. This
|
||
output and confirmation step can be skipped by using <code>-P</code> instead of
|
||
<code>-p</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Configuration-2"></span></p>
|
||
<h3 id="2634-configuration"><a class="header" href="#2634-configuration">26.3.4 Configuration</a></h3>
|
||
<p>Configuration is by means of the styles mechanism that should be
|
||
familiar from completion; if not, see the description of the <code>zstyle</code>
|
||
command in <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>. The context for
|
||
setting styles should be <code>’:chpwd:*’</code> in case the meaning of the context
|
||
is extended in future, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':chpwd:*' recent-dirs-max 0
|
||
</code></pre>
|
||
</div>
|
||
<p>sets the value of the <code>recent-dirs-max</code> style to 0. In practice the
|
||
style name is specific enough that a context of ’*’ should be fine.</p>
|
||
<p>An exception is <code>recent-dirs-insert</code>, which is used exclusively by the
|
||
completion system and so has the usual completion system context
|
||
(<code>’:completion:*’</code> if nothing more specific is needed), though again
|
||
<code>’*’</code> should be fine in practice.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>recent-dirs-default</code><br />
|
||
If true, and the command is expecting a recent directory index, and
|
||
either there is more than one argument or the argument is not an
|
||
integer, then fall through to "cd". This allows the lazy to use only
|
||
one command for directory changing. Completion recognises this, too;
|
||
see recent-dirs-insert for how to control completion when this
|
||
option is in use.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>recent-dirs-file</code><br />
|
||
The file where the list of directories is saved. The default is
|
||
<code>${ZDOTDIR:-$HOME}/.chpwd-recent-dirs</code>, i.e. this is in your home
|
||
directory unless you have set the variable <code>ZDOTDIR</code> to point
|
||
somewhere else. Directory names are saved in <code>$’``...``’</code> quoted
|
||
form, so each line in the file can be supplied directly to the shell
|
||
as an argument.</p>
|
||
<p>The value of this style may be an array. In this case, the first
|
||
file in the list will always be used for saving directories while
|
||
any other files are left untouched. When reading the recent
|
||
directory list, if there are fewer than the maximum number of
|
||
entries in the first file, the contents of later files in the array
|
||
will be appended with duplicates removed from the list shown. The
|
||
contents of the two files are not sorted together, i.e. all the
|
||
entries in the first file are shown first. The special value <code>+</code> can
|
||
appear in the list to indicate the default file should be read at
|
||
that point. This allows effects like the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':chpwd:*' recent-dirs-file \
|
||
~/.chpwd-recent-dirs-${TTY##*/} +
|
||
</code></pre>
|
||
</div>
|
||
<p>Recent directories are read from a file numbered according to the
|
||
terminal. If there are insufficient entries the list is supplemented
|
||
from the default file.</p>
|
||
<p>It is possible to use <code>zstyle -e</code> to make the directory configurable
|
||
at run time:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle -e ':chpwd:*' recent-dirs-file pick-recent-dirs-file
|
||
pick-recent-dirs-file() {
|
||
if [[ $PWD = ~/text/writing(|/*) ]]; then
|
||
reply=(~/.chpwd-recent-dirs-writing)
|
||
else
|
||
reply=(+)
|
||
fi
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>In this example, if the current directory is <code>~/text/writing</code> or a
|
||
directory under it, then use a special file for saving recent
|
||
directories, else use the default.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>recent-dirs-insert</code><br />
|
||
Used by completion. If <code>recent-dirs-default</code> is true, then setting
|
||
this to <code>true</code> causes the actual directory, rather than its index,
|
||
to be inserted on the command line; this has the same effect as
|
||
using the corresponding index, but makes the history clearer and the
|
||
line easier to edit. With this setting, if part of an argument was
|
||
already typed, normal directory completion rather than recent
|
||
directory completion is done; this is because recent directory
|
||
completion is expected to be done by cycling through entries menu
|
||
fashion.</p>
|
||
<p>If the value of the style is <code>always</code>, then only recent directories
|
||
will be completed; in that case, use the <code>cd</code> command when you want
|
||
to complete other directories.</p>
|
||
<p>If the value is <code>fallback</code>, recent directories will be tried first,
|
||
then normal directory completion is performed if recent directory
|
||
completion failed to find a match.</p>
|
||
<p>Finally, if the value is <code>both</code> then both sets of completions are
|
||
presented; the usual tag mechanism can be used to distinguish
|
||
results, with recent directories tagged as <code>recent-dirs</code>. Note that
|
||
the recent directories inserted are abbreviated with directory names
|
||
where appropriate.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>recent-dirs-max</code><br />
|
||
The maximum number of directories to save to the file. If this is
|
||
zero or negative there is no maximum. The default is 20. Note this
|
||
includes the current directory, which isn’t offered, so the highest
|
||
number of directories you will be offered is one less than the
|
||
maximum.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>recent-dirs-prune</code><br />
|
||
This style is an array determining what directories should (or
|
||
should not) be added to the recent list. Elements of the array can
|
||
include:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>parent</code><br />
|
||
Prune parents (more accurately, ancestors) from the recent list.
|
||
If present, changing directly down by any number of directories
|
||
causes the current directory to be overwritten. For example,
|
||
changing from ~pws to ~pws/some/other/dir causes ~pws not to
|
||
be left on the recent directory stack. This only applies to
|
||
direct changes to descendant directories; earlier directories on
|
||
the list are not pruned. For example, changing from
|
||
~pws/yet/another to ~pws/some/other/dir does not cause ~pws
|
||
to be pruned.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pattern:pattern</code><br />
|
||
Gives a zsh pattern for directories that should not be added to
|
||
the recent list (if not already there). This element can be
|
||
repeated to add different patterns. For example,
|
||
<code>’pattern:/tmp(|/*)’</code> stops <code>/tmp</code> or its descendants from
|
||
being added. The <code>EXTENDED_GLOB</code> option is always turned on for
|
||
these patterns.</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>recent-dirs-pushd</code><br />
|
||
If set to true, <code>cdr</code> will use <code>pushd</code> instead of <code>cd</code> to change the
|
||
directory, so the directory is saved on the directory stack. As the
|
||
directory stack is completely separate from the list of files saved
|
||
by the mechanism used in this file there is no obvious reason to do
|
||
this.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Use-with-dynamic-directory-naming"></span></p>
|
||
<h3 id="2635-use-with-dynamic-directory-naming"><a class="header" href="#2635-use-with-dynamic-directory-naming">26.3.5 Use with dynamic directory naming</a></h3>
|
||
<p>It is possible to refer to recent directories using the dynamic
|
||
directory name syntax by using the supplied function
|
||
<code>zsh_directory_name_cdr</code> a hook:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -Uz add-zsh-hook
|
||
add-zsh-hook -Uz zsh_directory_name zsh_directory_name_cdr
|
||
</code></pre>
|
||
</div>
|
||
<p>When this is done, <code>~[1]</code> will refer to the most recent directory other
|
||
than $PWD, and so on. Completion after <code>~[``...</code> also works.</p>
|
||
<hr />
|
||
<p><span id="Details-of-directory-handling"></span></p>
|
||
<h3 id="2636-details-of-directory-handling"><a class="header" href="#2636-details-of-directory-handling">26.3.6 Details of directory handling</a></h3>
|
||
<p>This section is for the curious or confused; most users will not need to
|
||
know this information.</p>
|
||
<p>Recent directories are saved to a file immediately and hence are
|
||
preserved across sessions. Note currently no file locking is applied:
|
||
the list is updated immediately on interactive commands and nowhere else
|
||
(unlike history), and it is assumed you are only going to change
|
||
directory in one window at once. This is not safe on shared accounts,
|
||
but in any case the system has limited utility when someone else is
|
||
changing to a different set of directories behind your back.</p>
|
||
<p>To make this a little safer, only directory changes instituted from the
|
||
command line, either directly or indirectly through shell function calls
|
||
(but not through subshells, evals, traps, completion functions and the
|
||
like) are saved. Shell functions should use <code>cd -q</code> or <code>pushd -q</code> to
|
||
avoid side effects if the change to the directory is to be invisible at
|
||
the command line. See the contents of the function <code>chpwd_recent_dirs</code>
|
||
for more details.</p>
|
||
<hr />
|
||
<p><span id="Other-Directory-Functions"></span>
|
||
<span id="index-directories_002c-named_002c-dynamic_002c-helper-function"></span>
|
||
<span id="index-dynamic-directory-naming_002c-helper-function"></span>
|
||
<span id="index-named-directories_002c-dynamic_002c-helper-function"></span>
|
||
<span id="index-zsh_005fdirectory_005fname_005fgeneric"></span>
|
||
<span id="Abbreviated-dynamic-references-to-directories"></span></p>
|
||
<h2 id="264-abbreviated-dynamic-references-to-directories"><a class="header" href="#264-abbreviated-dynamic-references-to-directories">26.4 Abbreviated dynamic references to directories</a></h2>
|
||
<p>The dynamic directory naming system is described in the subsection
|
||
<em>Dynamic named directories</em> of <a href="Expansion.html#Filename-Expansion">Filename
|
||
Expansion</a>. In this, a reference to
|
||
<code>~[``...``]</code> is expanded by a function found by the hooks mechanism.</p>
|
||
<p>The contributed function <code>zsh_directory_name_generic</code> provides a system
|
||
allowing the user to refer to directories with only a limited amount of
|
||
new code. It supports all three of the standard interfaces for directory
|
||
naming: converting from a name to a directory, converting in the reverse
|
||
direction to find a short name, and completion of names.</p>
|
||
<p>The main feature of this function is a path-like syntax, combining
|
||
abbreviations at multiple levels separated by ":". As an example,
|
||
~[g:p:s] might specify:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>g</code><br />
|
||
The top level directory for your git area. This first component has
|
||
to match, or the function will return indicating another directory
|
||
name hook function should be tried.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>p</code><br />
|
||
The name of a project within your git area.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>s</code><br />
|
||
The source area within that project.</p>
|
||
</li>
|
||
</ul>
|
||
<p>This allows you to collapse references to long hierarchies to a very
|
||
compact form, particularly if the hierarchies are similar across
|
||
different areas of the disk.</p>
|
||
<p>Name components may be completed: if a description is shown at the top
|
||
of the list of completions, it includes the path to which previous
|
||
components expand, while the description for an individual completion
|
||
shows the path segment it would add. No additional configuration is
|
||
needed for this as the completion system is aware of the dynamic
|
||
directory name mechanism.</p>
|
||
<hr />
|
||
<p><span id="Usage"></span></p>
|
||
<h3 id="2641-usage"><a class="header" href="#2641-usage">26.4.1 Usage</a></h3>
|
||
<p>To use the function, first define a wrapper function for your specific
|
||
case. We’ll assume it’s to be autoloaded. This can have any name but
|
||
we’ll refer to it as zdn_mywrapper. This wrapper function will define
|
||
various variables and then call this function with the same arguments
|
||
that the wrapper function gets. This configuration is described below.</p>
|
||
<p>Then arrange for the wrapper to be run as a zsh_directory_name hook:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -Uz add-zsh-hook zsh_diretory_name_generic zdn_mywrapper
|
||
add-zsh-hook -U zsh_directory_name zdn_mywrapper
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Configuration"></span></p>
|
||
<h3 id="2642-configuration"><a class="header" href="#2642-configuration">26.4.2 Configuration</a></h3>
|
||
<p>The wrapper function should define a local associative array zdn_top.
|
||
Alternatively, this can be set with a style called <code>mapping</code>. The
|
||
context for the style is <code>:zdn:``wrapper-name</code> where <code>wrapper-name</code> is
|
||
the function calling zsh_directory_name_generic; for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :zdn:zdn_mywrapper: mapping zdn_mywrapper_top
|
||
</code></pre>
|
||
</div>
|
||
<p>The keys in this associative array correspond to the first component of
|
||
the name. The values are matching directories. They may have an optional
|
||
suffix with a slash followed by a colon and the name of a variable in
|
||
the same format to give the next component. (The slash before the colon
|
||
is to disambiguate the case where a colon is needed in the path for a
|
||
drive. There is otherwise no syntax for escaping this, so path
|
||
components whose names start with a colon are not supported.) A special
|
||
component <code>:default:</code> specifies a variable in the form <code>/:``var</code> (the
|
||
path section is ignored and so is usually empty) that will be used for
|
||
the next component if no variable is given for the path. Variables
|
||
referred to within <code>zdn_top</code> have the same format as <code>zdn_top</code> itself,
|
||
but contain relative paths.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local -A zdn_top=(
|
||
g ~/git
|
||
ga ~/alternate/git
|
||
gs /scratch/$USER/git/:second2
|
||
:default: /:second1
|
||
)
|
||
</code></pre>
|
||
</div>
|
||
<p>This specifies the behaviour of a directory referred to as <code>~[g:...]</code> or
|
||
<code>~[ga:...]</code> or <code>~[gs:...]</code>. Later path components are optional; in that
|
||
case <code>~[g]</code> expands to <code>~/git</code>, and so on. <code>gs</code> expands to
|
||
<code>/scratch/$USER/git</code> and uses the associative array <code>second2</code> to match
|
||
the second component; <code>g</code> and <code>ga</code> use the associative array <code>second1</code>
|
||
to match the second component.</p>
|
||
<p>When expanding a name to a directory, if the first component is not <code>g</code>
|
||
or <code>ga</code> or <code>gs</code>, it is not an error; the function simply returns 1 so
|
||
that a later hook function can be tried. However, matching the first
|
||
component commits the function, so if a later component does not match,
|
||
an error is printed (though this still does not stop later hooks from
|
||
being executed).</p>
|
||
<p>For components after the first, a relative path is expected, but note
|
||
that multiple levels may still appear. Here is an example of <code>second1</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local -A second1=(
|
||
p myproject
|
||
s somproject
|
||
os otherproject/subproject/:third
|
||
)
|
||
</code></pre>
|
||
</div>
|
||
<p>The path as found from <code>zdn_top</code> is extended with the matching
|
||
directory, so <code>~[g:p]</code> becomes <code>~/git/myproject</code>. The slash between is
|
||
added automatically (it’s not possible to have a later component modify
|
||
the name of a directory already matched). Only <code>os</code> specifies a variable
|
||
for a third component, and there’s no <code>:default:</code>, so it’s an error to
|
||
use a name like <code>~[g:p:x]</code> or <code>~[ga:s:y]</code> because there’s nowhere to
|
||
look up the <code>x</code> or <code>y</code>.</p>
|
||
<p>The associative arrays need to be visible within this function; the
|
||
generic function therefore uses internal variable names beginning
|
||
<code>_zdn_</code> in order to avoid clashes. Note that the variable <code>reply</code> needs
|
||
to be passed back to the shell, so should not be local in the calling
|
||
function.</p>
|
||
<p>The function does not test whether directories assembled by component
|
||
actually exist; this allows the system to work across automounted file
|
||
systems. The error from the command trying to use a non-existent
|
||
directory should be sufficient to indicate the problem.</p>
|
||
<hr />
|
||
<p><span id="Complete-example"></span></p>
|
||
<h3 id="2643-complete-example"><a class="header" href="#2643-complete-example">26.4.3 Complete example</a></h3>
|
||
<p>Here is a full fictitious but usable autoloadable definition of the
|
||
example function defined by the code above. So <code>~[gs:p:s]</code> expands to
|
||
<code>/scratch/$USER/git/myscratchproject/top/srcdir</code> (with <code>$USER</code> also
|
||
expanded).</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local -A zdn_top=(
|
||
g ~/git
|
||
ga ~/alternate/git
|
||
gs /scratch/$USER/git/:second2
|
||
:default: /:second1
|
||
)
|
||
|
||
local -A second1=(
|
||
p myproject
|
||
s somproject
|
||
os otherproject/subproject/:third
|
||
)
|
||
|
||
local -A second2=(
|
||
p myscratchproject
|
||
s somescratchproject
|
||
)
|
||
|
||
local -A third=(
|
||
s top/srcdir
|
||
d top/documentation
|
||
)
|
||
|
||
# autoload not needed if you did this at initialisation...
|
||
autoload -Uz zsh_directory_name_generic
|
||
zsh_directory_name_generic "$@
|
||
</code></pre>
|
||
</div>
|
||
<p>It is also possible to use global associative arrays, suitably named,
|
||
and set the style for the context of your wrapper function to refer to
|
||
this. Then your set up code would contain the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">typeset -A zdn_mywrapper_top=(...)
|
||
# ... and so on for other associative arrays ...
|
||
zstyle ':zdn:zdn_mywrapper:' mapping zdn_mywrapper_top
|
||
autoload -Uz add-zsh-hook zsh_directory_name_generic zdn_mywrapper
|
||
add-zsh-hook -U zsh_directory_name zdn_mywrapper
|
||
</code></pre>
|
||
</div>
|
||
<p>and the function <code>zdn_mywrapper</code> would contain only the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zsh_directory_name_generic "$@"
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Version-Control-Information"></span>
|
||
<span id="Gathering-information-from-version-control-systems"></span></p>
|
||
<h2 id="265-gathering-information-from-version-control-systems"><a class="header" href="#265-gathering-information-from-version-control-systems">26.5 Gathering information from version control systems</a></h2>
|
||
<p><span id="index-version-control-utility"></span></p>
|
||
<p>In a lot of cases, it is nice to automatically retrieve information from
|
||
version control systems (VCSs), such as subversion, CVS or git, to be
|
||
able to provide it to the user; possibly in the user’s prompt. So that
|
||
you can instantly tell which branch you are currently on, for example.</p>
|
||
<p>In order to do that, you may use the <code>vcs_info</code> function.</p>
|
||
<p>The following VCSs are supported, showing the abbreviated name by which
|
||
they are referred to within the system:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Bazaar (<code>bzr</code>)<br />
|
||
<code>https://bazaar.canonical.com/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Codeville (<code>cdv</code>)<br />
|
||
<code>http://freecode.com/projects/codeville/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Concurrent Versioning System (<code>cvs</code>)<br />
|
||
<code>https://www.nongnu.org/cvs/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Darcs (<code>darcs</code>)<br />
|
||
<code>http://darcs.net/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Fossil (<code>fossil</code>)<br />
|
||
<code>https://fossil-scm.org/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Git (<code>git</code>)<br />
|
||
<code>https://git-scm.com/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>GNU arch (<code>tla</code>)<br />
|
||
<code>https://www.gnu.org/software/gnu-arch/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Mercurial (<code>hg</code>)<br />
|
||
<code>https://www.mercurial-scm.org/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Monotone (<code>mtn</code>)<br />
|
||
<code>https://monotone.ca/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Perforce (<code>p4</code>)<br />
|
||
<code>https://www.perforce.com/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Subversion (<code>svn</code>)<br />
|
||
<code>https://subversion.apache.org/</code></p>
|
||
</li>
|
||
<li>
|
||
<p>SVK (<code>svk</code>)<br />
|
||
<code>https://svk.bestpractical.com/</code></p>
|
||
</li>
|
||
</ul>
|
||
<p>There is also support for the patch management system <code>quilt</code>
|
||
(<code>https://savannah.nongnu.org/projects/quilt</code>). See <a href="#vcs_005finfo-Quilt-Support">Quilt
|
||
Support</a> below for details.</p>
|
||
<p>To load <code>vcs_info</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -Uz vcs_info
|
||
</code></pre>
|
||
</div>
|
||
<p>It can be used in any existing prompt, because it does not require any
|
||
specific <code>$psvar</code> entries to be available.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Quickstart"></span> <span id="Quickstart"></span></p>
|
||
<h3 id="2651-quickstart"><a class="header" href="#2651-quickstart">26.5.1 Quickstart</a></h3>
|
||
<p>To get this feature working quickly (including colors), you can do the
|
||
following (assuming, you loaded <code>vcs_info</code> properly - see above):</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' actionformats \
|
||
'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
|
||
zstyle ':vcs_info:*' formats \
|
||
'%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
|
||
zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
|
||
precmd () { vcs_info }
|
||
PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '
|
||
</code></pre>
|
||
</div>
|
||
<p>Obviously, the last two lines are there for demonstration. You need to
|
||
call <code>vcs_info</code> from your <code>precmd</code> function. Once that is done you need
|
||
a <em>single quoted</em> <code>’${vcs_info_msg_0_}’</code> in your prompt.</p>
|
||
<p>To be able to use <code>’${vcs_info_msg_0_}’</code> directly in your prompt like
|
||
this, you will need to have the <code>PROMPT_SUBST</code> option enabled.</p>
|
||
<p>Now call the <code>vcs_info_printsys</code> utility from the command line:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">% vcs_info_printsys
|
||
## list of supported version control backends:
|
||
## disabled systems are prefixed by a hash sign (#)
|
||
bzr
|
||
cdv
|
||
cvs
|
||
darcs
|
||
fossil
|
||
git
|
||
hg
|
||
mtn
|
||
p4
|
||
svk
|
||
svn
|
||
tla
|
||
## flavours (cannot be used in the enable or disable styles; they
|
||
## are enabled and disabled with their master [git-svn -> git])
|
||
## they *can* be used in contexts: ':vcs_info:git-svn:*'.
|
||
git-p4
|
||
git-svn
|
||
hg-git
|
||
hg-hgsubversion
|
||
hg-hgsvn
|
||
</code></pre>
|
||
</div>
|
||
<p>You may not want all of these because there is no point in running the
|
||
code to detect systems you do not use. So there is a way to disable some
|
||
backends altogether:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla
|
||
</code></pre>
|
||
</div>
|
||
<p>You may also pick a few from that list and enable only those:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' enable git cvs svn
|
||
</code></pre>
|
||
</div>
|
||
<p>If you rerun <code>vcs_info_printsys</code> after one of these commands, you will
|
||
see the backends listed in the <code>disable</code> style (or backends not in the
|
||
<code>enable</code> style - if you used that) marked as disabled by a hash sign.
|
||
That means the detection of these systems is skipped <em>completely</em>. No
|
||
wasted time there.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Configuration"></span>
|
||
<span id="Configuration-1"></span></p>
|
||
<h3 id="2652-configuration"><a class="header" href="#2652-configuration">26.5.2 Configuration</a></h3>
|
||
<p>The <code>vcs_info</code> feature can be configured via <code>zstyle</code>.</p>
|
||
<p>First, the context in which we are working:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">:vcs_info:vcs-string:user-context:repo-root-name
|
||
</code></pre>
|
||
</div>
|
||
<ul>
|
||
<li>
|
||
<p><code>vcs-string</code><br />
|
||
is one of: <code>git</code>, <code>git-svn</code>, <code>git-p4</code>, <code>hg</code>, <code>hg-git</code>,
|
||
<code>hg-hgsubversion</code>, <code>hg-hgsvn</code>, <code>darcs</code>, <code>bzr</code>, <code>cdv</code>, <code>mtn</code>, <code>svn</code>,
|
||
<code>cvs</code>, <code>svk</code>, <code>tla</code>, <code>p4</code> or <code>fossil</code>. This is followed by
|
||
‘<code>.quilt-``quilt-mode</code>’ in Quilt mode (see <a href="#vcs_005finfo-Quilt-Support">Quilt
|
||
Support</a> for details) and by
|
||
‘<code>+``hook-name</code>’ while hooks are active (see <a href="#vcs_005finfo-Hooks">Hooks in
|
||
vcs_info</a> for details).</p>
|
||
<p>Currently, hooks in quilt mode don’t add the ‘<code>.quilt-``quilt-mode</code>’
|
||
information. This may change in the future.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>user-context</code><br />
|
||
is a freely configurable string, assignable by the user as the first
|
||
argument to <code>vcs_info</code> (see its description below).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>repo-root-name</code><br />
|
||
is the name of a repository in which you want a style to match. So,
|
||
if you want a setting specific to <code>/usr/src/zsh</code>, with that being a
|
||
CVS checkout, you can set <code>repo-root-name</code> to <code>zsh</code> to make it so.</p>
|
||
</li>
|
||
</ul>
|
||
<p>There are three special values for <code>vcs-string</code>: The first is named
|
||
<code>-init-</code>, that is in effect as long as there was no decision what VCS
|
||
backend to use. The second is <code>-preinit-</code>; it is used <em>before</em>
|
||
<code>vcs_info</code> is run, when initializing the data exporting variables. The
|
||
third special value is <code>formats</code> and is used by the <code>vcs_info_lastmsg</code>
|
||
for looking up its styles.</p>
|
||
<p>The initial value of <code>repo-root-name</code> is <code>-all-</code> and it is replaced with
|
||
the actual name, as soon as it is known. Only use this part of the
|
||
context for defining the <code>formats</code>, <code>actionformats</code> or <code>branchformat</code>
|
||
styles, as it is guaranteed that <code>repo-root-name</code> is set up correctly
|
||
for these only. For all other styles, just use <code>’*’</code> instead.</p>
|
||
<p>There are two pre-defined values for <code>user-context</code>:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>default</code><br />
|
||
the one used if none is specified</p>
|
||
</li>
|
||
<li>
|
||
<p><code>command</code><br />
|
||
used by vcs_info_lastmsg to lookup its styles</p>
|
||
</li>
|
||
</ul>
|
||
<p>You can of course use <code>’:vcs_info:*’</code> to match all VCSs in all
|
||
user-contexts at once.</p>
|
||
<p>This is a description of all styles that are looked up.</p>
|
||
<p><span id="index-formats"></span></p>
|
||
<p><code>formats</code></p>
|
||
<p>A list of formats, used when actionformats is not used (which is most of
|
||
the time).</p>
|
||
<p><span id="index-actionformats"></span></p>
|
||
<p><code>actionformats</code></p>
|
||
<p>A list of formats, used if there is a special action going on in your
|
||
current repository; like an interactive rebase or a merge conflict.</p>
|
||
<p><span id="index-branchformat"></span></p>
|
||
<p><code>branchformat</code></p>
|
||
<p>Some backends replace <code>%b</code> in the formats and actionformats styles
|
||
above, not only by a branch name but also by a revision number. This
|
||
style lets you modify how that string should look.</p>
|
||
<p><span id="index-nvcsformats"></span></p>
|
||
<p><code>nvcsformats</code></p>
|
||
<p>These "formats" are set when we didn’t detect a version control system
|
||
for the current directory or <code>vcs_info</code> was disabled. This is useful if
|
||
you want <code>vcs_info</code> to completely take over the generation of your
|
||
prompt. You would do something like <code>PS1=’${vcs_info_msg_0_}’</code> to
|
||
accomplish that.</p>
|
||
<p><span id="index-hgrevformat"></span></p>
|
||
<p><code>hgrevformat</code></p>
|
||
<p><code>hg</code> uses both a hash and a revision number to reference a specific
|
||
changeset in a repository. With this style you can format the revision
|
||
string (see <code>branchformat</code>) to include either or both. It’s only useful
|
||
when <code>get-revision</code> is true. Note, the full 40-character revision id is
|
||
not available (except when using the <code>use-simple</code> option) because
|
||
executing hg more than once per prompt is too slow; you may customize
|
||
this behavior using hooks.</p>
|
||
<p><span id="index-max_002dexports"></span></p>
|
||
<p><code>max-exports</code></p>
|
||
<p>Defines the maximum number of <code>vcs_info_msg_*_</code> variables <code>vcs_info</code>
|
||
will set.</p>
|
||
<p><span id="index-enable-1"></span></p>
|
||
<p><code>enable</code></p>
|
||
<p>A list of backends you want to use. Checked in the <code>-init-</code> context. If
|
||
this list contains an item called <code>NONE</code> no backend is used at all and
|
||
<code>vcs_info</code> will do nothing. If this list contains <code>ALL</code>, <code>vcs_info</code> will
|
||
use all known backends. Only with <code>ALL</code> in <code>enable</code> will the <code>disable</code>
|
||
style have any effect. <code>ALL</code> and <code>NONE</code> are case insensitive.</p>
|
||
<p><span id="index-disable-1"></span></p>
|
||
<p><code>disable</code></p>
|
||
<p>A list of VCSs you don’t want <code>vcs_info</code> to test for repositories
|
||
(checked in the <code>-init-</code> context, too). Only used if <code>enable</code> contains
|
||
<code>ALL</code>.</p>
|
||
<p><span id="index-disable_002dpatterns"></span></p>
|
||
<p><code>disable-patterns</code></p>
|
||
<p>A list of patterns that are checked against <code>$PWD</code>. If a pattern
|
||
matches, <code>vcs_info</code> will be disabled. This style is checked in the
|
||
<code>:vcs_info:-init-:*:-all-</code> context.</p>
|
||
<p>Say, <code>~/.zsh</code> is a directory under version control, in which you do not
|
||
want <code>vcs_info</code> to be active, do:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' disable-patterns "${(b)HOME}/.zsh(|/*)"
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-use_002dquilt"></span></p>
|
||
<p><code>use-quilt</code></p>
|
||
<p>If enabled, the <code>quilt</code> support code is active in ‘addon’ mode. See
|
||
<a href="#vcs_005finfo-Quilt-Support">Quilt Support</a> for details.</p>
|
||
<p><span id="index-quilt_002dstandalone"></span></p>
|
||
<p><code>quilt-standalone</code></p>
|
||
<p>If enabled, ‘standalone’ mode detection is attempted if no VCS is active
|
||
in a given directory. See <a href="#vcs_005finfo-Quilt-Support">Quilt Support</a>
|
||
for details.</p>
|
||
<p><span id="index-quilt_002dpatch_002ddir"></span></p>
|
||
<p><code>quilt-patch-dir</code></p>
|
||
<p>Overwrite the value of the <code>$QUILT_PATCHES</code> environment variable. See
|
||
<a href="#vcs_005finfo-Quilt-Support">Quilt Support</a> for details.</p>
|
||
<p><span id="index-quiltcommand"></span></p>
|
||
<p><code>quiltcommand</code></p>
|
||
<p>When <code>quilt</code> itself is called in quilt support, the value of this style
|
||
is used as the command name.</p>
|
||
<p><span id="index-check_002dfor_002dchanges"></span></p>
|
||
<p><code>check-for-changes</code></p>
|
||
<p>If enabled, this style causes the <code>%c</code> and <code>%u</code> format escapes to show
|
||
when the working directory has uncommitted changes. The strings
|
||
displayed by these escapes can be controlled via the <code>stagedstr</code> and
|
||
<code>unstagedstr</code> styles. The only backends that currently support this
|
||
option are <code>git</code>, <code>hg</code>, and <code>bzr</code> (the latter two only support
|
||
unstaged).</p>
|
||
<p>For this style to be evaluated with the <code>hg</code> backend, the <code>get-revision</code>
|
||
style needs to be set and the <code>use-simple</code> style needs to be unset. The
|
||
latter is the default; the former is not.</p>
|
||
<p>With the <code>bzr</code> backend, <em>lightweight checkouts</em> only honor this style if
|
||
the <code>use-server</code> style is set.</p>
|
||
<p>Note, the actions taken if this style is enabled are potentially
|
||
expensive (read: they may be slow, depending on how big the current
|
||
repository is). Therefore, it is disabled by default.</p>
|
||
<p><span id="index-check_002dfor_002dstaged_002dchanges"></span></p>
|
||
<p><code>check-for-staged-changes</code></p>
|
||
<p>This style is like <code>check-for-changes</code>, but it never checks the worktree
|
||
files, only the metadata in the <code>.${vcs}</code> dir. Therefore, this style
|
||
initializes only the <code>%c</code> escape (with <code>stagedstr</code>) but not the <code>%u</code>
|
||
escape. This style is faster than <code>check-for-changes</code>.</p>
|
||
<p>In the <code>git</code> backend, this style checks for changes in the index. Other
|
||
backends do not currently implement this style.</p>
|
||
<p>This style is disabled by default.</p>
|
||
<p><span id="index-stagedstr"></span></p>
|
||
<p><code>stagedstr</code></p>
|
||
<p>This string will be used in the <code>%c</code> escape if there are staged changes
|
||
in the repository.</p>
|
||
<p><span id="index-unstagedstr"></span></p>
|
||
<p><code>unstagedstr</code></p>
|
||
<p>This string will be used in the <code>%u</code> escape if there are unstaged
|
||
changes in the repository.</p>
|
||
<p><span id="index-command-2"></span></p>
|
||
<p><code>command</code></p>
|
||
<p>This style causes <code>vcs_info</code> to use the supplied string as the command
|
||
to use as the VCS’s binary. Note, that setting this in ’<code>:vcs_info:*</code>’
|
||
is not a good idea.</p>
|
||
<p>If the value of this style is empty (which is the default), the used
|
||
binary name is the name of the backend in use (e.g. <code>svn</code> is used in an
|
||
<code>svn</code> repository).</p>
|
||
<p>The <code>repo-root-name</code> part in the context is always the default <code>-all-</code>
|
||
when this style is looked up.</p>
|
||
<p>For example, this style can be used to use binaries from non-default
|
||
installation directories. Assume, <code>git</code> is installed in /usr/bin but
|
||
your sysadmin installed a newer version in /usr/local/bin. Instead of
|
||
changing the order of your <code>$PATH</code> parameter, you can do this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-use_002dserver"></span></p>
|
||
<p><code>use-server</code></p>
|
||
<p>This is used by the Perforce backend (<code>p4</code>) to decide if it should
|
||
contact the Perforce server to find out if a directory is managed by
|
||
Perforce. This is the only reliable way of doing this, but runs the risk
|
||
of a delay if the server name cannot be found. If the server (more
|
||
specifically, the <code>host``:``port</code> pair describing the server) cannot be
|
||
contacted, its name is put into the associative array
|
||
<code>vcs_info_p4_dead_servers</code> and is not contacted again during the session
|
||
until it is removed by hand. If you do not set this style, the <code>p4</code>
|
||
backend is only usable if you have set the environment variable
|
||
<code>P4CONFIG</code> to a file name and have corresponding files in the root
|
||
directories of each Perforce client. See comments in the function
|
||
<code>VCS_INFO_detect_p4</code> for more detail.</p>
|
||
<p>The Bazaar backend (<code>bzr</code>) uses this to permit contacting the server
|
||
about lightweight checkouts, see the <code>check-for-changes</code> style.</p>
|
||
<p><span id="index-use_002dsimple"></span></p>
|
||
<p><code>use-simple</code></p>
|
||
<p>If there are two different ways of gathering information, you can select
|
||
the simpler one by setting this style to true; the default is to use the
|
||
not-that-simple code, which is potentially a lot slower but might be
|
||
more accurate in all possible cases. This style is used by the <code>bzr</code> and
|
||
<code>hg</code> backends. In the case of <code>hg</code> it will invoke the external hexdump
|
||
program to parse the binary dirstate cache file; this method will not
|
||
return the local revision number.</p>
|
||
<p><span id="index-get_002drevision"></span></p>
|
||
<p><code>get-revision</code></p>
|
||
<p>If set to true, vcs_info goes the extra mile to figure out the revision
|
||
of a repository’s work tree (currently for the <code>git</code> and <code>hg</code> backends,
|
||
where this kind of information is not always vital). For <code>git</code>, the hash
|
||
value of the currently checked out commit is available via the <code>%i</code>
|
||
expansion. With <code>hg</code>, the local revision number and the corresponding
|
||
global hash are available via <code>%i</code>.</p>
|
||
<p><span id="index-get_002dmq"></span></p>
|
||
<p><code>get-mq</code></p>
|
||
<p>If set to true, the <code>hg</code> backend will look for a Mercurial Queue (<code>mq</code>)
|
||
patch directory. Information will be available via the ‘<code>%m</code>’
|
||
replacement.</p>
|
||
<p><span id="index-get_002dbookmarks"></span></p>
|
||
<p><code>get-bookmarks</code></p>
|
||
<p>If set to true, the <code>hg</code> backend will try to get a list of current
|
||
bookmarks. They will be available via the ‘<code>%m</code>’ replacement.</p>
|
||
<p>The default is to generate a comma-separated list of all bookmark names
|
||
that refer to the currently checked out revision. If a bookmark is
|
||
active, its name is suffixed an asterisk and placed first in the list.</p>
|
||
<p><span id="index-use_002dprompt_002descapes"></span></p>
|
||
<p><code>use-prompt-escapes</code></p>
|
||
<p>Determines if we assume that the assembled string from <code>vcs_info</code>
|
||
includes prompt escapes. (Used by <code>vcs_info_lastmsg</code>.)</p>
|
||
<p><span id="index-debug"></span></p>
|
||
<p><code>debug</code></p>
|
||
<p>Enable debugging output to track possible problems. Currently this style
|
||
is only used by <code>vcs_info</code>’s hooks system.</p>
|
||
<p><span id="index-hooks"></span></p>
|
||
<p><code>hooks</code></p>
|
||
<p>A list style that defines hook-function names. See <a href="#vcs_005finfo-Hooks">Hooks in
|
||
vcs_info</a> below for details.</p>
|
||
<p><span id="index-patch_002dformat"></span>
|
||
<span id="index-nopatch_002dformat"></span></p>
|
||
<p><code>patch-format</code></p>
|
||
<p><code>nopatch-format</code></p>
|
||
<p>This pair of styles format the patch information used by the <code>%m</code>
|
||
expando in formats and actionformats for the <code>git</code> and <code>hg</code> backends.
|
||
The value is subject to certain <code>%</code>-expansions described below. The
|
||
expanded value is made available in the global <code>backend_misc</code> array as
|
||
<code>${backend_misc[patches]}</code> (also if a <code>set-patch-format</code> hook is used).</p>
|
||
<p><span id="index-get_002dunapplied"></span></p>
|
||
<p><code>get-unapplied</code></p>
|
||
<p>This boolean style controls whether a backend should attempt to gather a
|
||
list of unapplied patches (for example with Mercurial Queue patches).</p>
|
||
<p>Used by the <code>quilt</code> and <code>hg</code> backends.</p>
|
||
<p>The default values for these styles in all contexts are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>formats</code><br />
|
||
" (%s)-[%b]%u%c-"</p>
|
||
</li>
|
||
<li>
|
||
<p><code>actionformats</code><br />
|
||
" (%s)-[%b|%a]%u%c-"</p>
|
||
</li>
|
||
<li>
|
||
<p><code>branchformat</code><br />
|
||
"%b:%r" (for bzr, svn, svk and hg)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>nvcsformats</code><br />
|
||
""</p>
|
||
</li>
|
||
<li>
|
||
<p><code>hgrevformat</code><br />
|
||
"%r:%h"</p>
|
||
</li>
|
||
<li>
|
||
<p><code>max-exports</code><br />
|
||
2</p>
|
||
</li>
|
||
<li>
|
||
<p><code>enable</code><br />
|
||
ALL</p>
|
||
</li>
|
||
<li>
|
||
<p><code>disable</code><br />
|
||
(empty list)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>disable-patterns</code><br />
|
||
(empty list)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>check-for-changes</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>check-for-staged-changes</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>stagedstr</code><br />
|
||
(string: "S")</p>
|
||
</li>
|
||
<li>
|
||
<p><code>unstagedstr</code><br />
|
||
(string: "U")</p>
|
||
</li>
|
||
<li>
|
||
<p><code>command</code><br />
|
||
(empty string)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>use-server</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>use-simple</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>get-revision</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>get-mq</code><br />
|
||
true</p>
|
||
</li>
|
||
<li>
|
||
<p><code>get-bookmarks</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>use-prompt-escapes</code><br />
|
||
true</p>
|
||
</li>
|
||
<li>
|
||
<p><code>debug</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>hooks</code><br />
|
||
(empty list)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>use-quilt</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>quilt-standalone</code><br />
|
||
false</p>
|
||
</li>
|
||
<li>
|
||
<p><code>quilt-patch-dir</code><br />
|
||
empty - use <code>$QUILT_PATCHES</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>quiltcommand</code><br />
|
||
quilt</p>
|
||
</li>
|
||
<li>
|
||
<p><code>patch-format</code><br />
|
||
<code>backend dependent</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>nopatch-format</code><br />
|
||
<code>backend dependent</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>get-unapplied</code><br />
|
||
false</p>
|
||
</li>
|
||
</ul>
|
||
<p>In normal <code>formats</code> and <code>actionformats</code> the following replacements are
|
||
done:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%s</code><br />
|
||
The VCS in use (git, hg, svn, etc.).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%b</code><br />
|
||
Information about the current branch.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%a</code><br />
|
||
An identifier that describes the action. Only makes sense in
|
||
<code>actionformats</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%i</code><br />
|
||
The current revision number or identifier. For <code>hg</code> the
|
||
<code>hgrevformat</code> style may be used to customize the output.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%c</code><br />
|
||
The string from the <code>stagedstr</code> style if there are staged changes in
|
||
the repository.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%u</code><br />
|
||
The string from the <code>unstagedstr</code> style if there are unstaged
|
||
changes in the repository.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%R</code><br />
|
||
The base directory of the repository.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%r</code><br />
|
||
The repository name. If <code>%R</code> is <code>/foo/bar/repoXY</code>, <code>%r</code> is <code>repoXY</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%S</code><br />
|
||
A subdirectory within a repository. If <code>$PWD</code> is
|
||
<code>/foo/bar/repoXY/beer/tasty</code>, <code>%S</code> is <code>beer/tasty</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<!-- end list -->
|
||
<ul>
|
||
<li>
|
||
<p><code>%m</code><br />
|
||
A "misc" replacement. It is at the discretion of the backend to
|
||
decide what this replacement expands to.</p>
|
||
<p>The <code>hg</code> and <code>git</code> backends use this expando to display patch
|
||
information. <code>hg</code> sources patch information from the <code>mq</code>
|
||
extensions; <code>git</code> from in-progress <code>rebase</code> and <code>cherry-pick</code>
|
||
operations and from the <code>stgit</code> extension. The <code>patch-format</code> and
|
||
<code>nopatch-format</code> styles control the generated string. The former is
|
||
used when at least one patch from the patch queue has been applied,
|
||
and the latter otherwise.</p>
|
||
<p>The <code>hg</code> backend displays bookmark information in this expando (in
|
||
addition to <code>mq</code> information). See the <code>get-mq</code> and <code>get-bookmarks</code>
|
||
styles. Both of these styles may be enabled at the same time. If
|
||
both are enabled, both resulting strings will be shown separated by
|
||
a semicolon (that cannot currently be customized).</p>
|
||
<p>The <code>quilt</code> ‘standalone’ backend sets this expando to the same value
|
||
as the <code>%Q</code> expando.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%Q</code><br />
|
||
Quilt series information. When quilt is used (either in ‘addon’ mode
|
||
or as a ‘standalone’ backend), this expando is set to quilt series’
|
||
<code>patch-format</code> string. The <code>set-patch-format</code> hook and
|
||
<code>nopatch-format</code> style are honoured.</p>
|
||
<p>See <a href="#vcs_005finfo-Quilt-Support">Quilt Support</a> below for details.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In <code>branchformat</code> these replacements are done:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%b</code><br />
|
||
The branch name.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%r</code><br />
|
||
The current revision number or the <code>hgrevformat</code> style for <code>hg</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In <code>hgrevformat</code> these replacements are done:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%r</code><br />
|
||
The current local revision number.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%h</code><br />
|
||
The current global revision identifier.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In <code>patch-format</code> and <code>nopatch-format</code> these replacements are done:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%p</code><br />
|
||
The name of the top-most applied patch; may be overridden by the
|
||
<code>applied-string</code> hook.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%u</code><br />
|
||
The number of unapplied patches; may be overridden by the
|
||
<code>unapplied-string</code> hook.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%n</code><br />
|
||
The number of applied patches.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%c</code><br />
|
||
The number of unapplied patches.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%a</code><br />
|
||
The number of all patches (<code>%a = %n + %c</code>).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%g</code><br />
|
||
The names of active <code>mq</code> guards (<code>hg</code> backend).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%G</code><br />
|
||
The number of active <code>mq</code> guards (<code>hg</code> backend).</p>
|
||
</li>
|
||
</ul>
|
||
<p>Not all VCS backends have to support all replacements. For <code>nvcsformats</code>
|
||
no replacements are performed at all, it is just a string.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Oddities"></span> <span id="Oddities"></span></p>
|
||
<h3 id="2653-oddities"><a class="header" href="#2653-oddities">26.5.3 Oddities</a></h3>
|
||
<p>If you want to use the <code>%b</code> (bold off) prompt expansion in <code>formats</code>,
|
||
which expands <code>%b</code> itself, use <code>%%b</code>. That will cause the <code>vcs_info</code>
|
||
expansion to replace <code>%%b</code> with <code>%b</code>, so that zsh’s prompt expansion
|
||
mechanism can handle it. Similarly, to hand down <code>%b</code> from
|
||
<code>branchformat</code>, use <code>%%%%b</code>. Sorry for this inconvenience, but it cannot
|
||
be easily avoided. Luckily we do not clash with a lot of prompt
|
||
expansions and this only needs to be done for those.</p>
|
||
<p>When one of the <code>gen-applied-string</code>, <code>gen-unapplied-string</code>, and
|
||
<code>set-patch-format</code> hooks is defined, applying <code>%</code>-escaping
|
||
(‘<code>foo=${foo//’%’/%%}</code>’) to the interpolated values for use in the
|
||
prompt is the responsibility of those hooks (jointly); when neither of
|
||
those hooks is defined, <code>vcs_info</code> handles escaping by itself. We regret
|
||
this coupling, but it was required for backwards compatibility.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Quilt-Support"></span>
|
||
<span id="Quilt-Support"></span></p>
|
||
<h3 id="2654-quilt-support"><a class="header" href="#2654-quilt-support">26.5.4 Quilt Support</a></h3>
|
||
<p>Quilt is not a version control system, therefore this is not implemented
|
||
as a backend. It can help keeping track of a series of patches. People
|
||
use it to keep a set of changes they want to use on top of software
|
||
packages (which is tightly integrated into the package build process -
|
||
the Debian project does this for a large number of packages). Quilt can
|
||
also help individual developers keep track of their own patches on top
|
||
of real version control systems.</p>
|
||
<p>The <code>vcs_info</code> integration tries to support both ways of using quilt by
|
||
having two slightly different modes of operation: ‘addon’ mode and
|
||
‘standalone’ mode).</p>
|
||
<p>Quilt integration is off by default; to enable it, set the <code>use-quilt</code>
|
||
style, and add <code>%Q</code> to your <code>formats</code> or <code>actionformats</code> style:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' use-quilt true
|
||
</code></pre>
|
||
</div>
|
||
<p>Styles looked up from the Quilt support code include
|
||
‘<code>.quilt-``quilt-mode</code>’ in the <code>vcs-string</code> part of the context, where
|
||
<code>quilt-mode</code> is either <code>addon</code> or <code>standalone</code>. Example:
|
||
<code>:vcs_info:git.quilt-addon:default:``repo-root-name</code>.</p>
|
||
<p>For ‘addon’ mode to become active <code>vcs_info</code> must have already detected
|
||
a real version control system controlling the directory. If that is the
|
||
case, a directory that holds quilt’s patches needs to be found. That
|
||
directory is configurable via the ‘<code>QUILT_PATCHES</code>’ environment
|
||
variable. If that variable exists its value is used, otherwise the value
|
||
‘<code>patches</code>’ is assumed. The value from <code>$QUILT_PATCHES</code> can be
|
||
overwritten using the ‘<code>quilt-patches</code>’ style. (Note: you can use
|
||
<code>vcs_info</code> to keep the value of <code>$QUILT_PATCHES</code> correct all the time
|
||
via the <code>post-quilt</code> hook).</p>
|
||
<p>When the directory in question is found, quilt is assumed to be active.
|
||
To gather more information, <code>vcs_info</code> looks for a directory called
|
||
‘.pc’; Quilt uses that directory to track its current state. If this
|
||
directory does not exist we know that quilt has not done anything to the
|
||
working directory (read: no patches have been applied yet).</p>
|
||
<p>If patches are applied, <code>vcs_info</code> will try to find out which. If you
|
||
want to know which patches of a series are not yet applied, you need to
|
||
activate the <code>get-unapplied</code> style in the appropriate context.</p>
|
||
<p><code>vcs_info</code> allows for very detailed control over how the gathered
|
||
information is presented (see
|
||
<a href="#vcs_005finfo-Configuration">Configuration</a> and <a href="#vcs_005finfo-Hooks">Hooks in
|
||
vcs_info</a>), all of which are documented below.
|
||
Note there are a number of other patch tracking systems that work on top
|
||
of a certain version control system (like <code>stgit</code> for git, or <code>mq</code> for
|
||
hg); the configuration for systems like that are generally configured
|
||
the same way as the quilt support.</p>
|
||
<p>If the quilt support is working in ‘addon’ mode, the produced string is
|
||
available as a simple format replacement (<code>%Q</code> to be precise), which can
|
||
be used in <code>formats</code> and <code>actionformats</code>; see below for details).</p>
|
||
<p>If, on the other hand, the support code is working in ‘standalone’ mode,
|
||
<code>vcs_info</code> will pretend as if <code>quilt</code> were an actual version control
|
||
system. That means that the version control system identifier (which
|
||
otherwise would be something like ‘svn’ or ‘cvs’) will be set to
|
||
‘<code>-quilt-</code>’. This has implications on the used style context where
|
||
this identifier is the second element. <code>vcs_info</code> will have filled in a
|
||
proper value for the "repository’s" root directory and the string
|
||
containing the information about quilt’s state will be available as the
|
||
‘misc’ replacement (and <code>%Q</code> for compatibility with ‘addon’ mode).</p>
|
||
<p>What is left to discuss is how ‘standalone’ mode is detected. The
|
||
detection itself is a series of searches for directories. You can have
|
||
this detection enabled all the time in every directory that is not
|
||
otherwise under version control. If you know there is only a limited set
|
||
of trees where you would like <code>vcs_info</code> to try and look for Quilt in
|
||
‘standalone’ mode to minimise the amount of searching on every call to
|
||
<code>vcs_info</code>, there are a number of ways to do that:</p>
|
||
<p>Essentially, ‘standalone’ mode detection is controlled by a style called
|
||
‘<code>quilt-standalone</code>’. It is a string style and its value can have
|
||
different effects. The simplest values are: ‘<code>always</code>’ to run detection
|
||
every time <code>vcs_info</code> is run, and ‘<code>never</code>’ to turn the detection off
|
||
entirely.</p>
|
||
<p>If the value of <code>quilt-standalone</code> is something else, it is interpreted
|
||
differently. If the value is the name of a scalar variable the value of
|
||
that variable is checked and that value is used in the same
|
||
‘always’/‘never’ way as described above.</p>
|
||
<p>If the value of <code>quilt-standalone</code> is an array, the elements of that
|
||
array are used as directory names under which you want the detection to
|
||
be active.</p>
|
||
<p>If <code>quilt-standalone</code> is an associative array, the keys are taken as
|
||
directory names under which you want the detection to be active, but
|
||
only if the corresponding value is the string ‘<code>true</code>’.</p>
|
||
<p>Last, but not least, if the value of <code>quilt-standalone</code> is the name of a
|
||
function, the function is called without arguments and the return value
|
||
decides whether detection should be active. A ‘0’ return value is true;
|
||
a non-zero return value is interpreted as false.</p>
|
||
<p>Note, if there is both a function and a variable by the name of
|
||
<code>quilt-standalone</code>, the function will take precedence.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-API"></span>
|
||
<span id="Function-Descriptions-_0028Public-API_0029"></span></p>
|
||
<h3 id="2655-function-descriptions-public-api"><a class="header" href="#2655-function-descriptions-public-api">26.5.5 Function Descriptions (Public API)</a></h3>
|
||
<p><span id="index-vcs_005finfo"></span></p>
|
||
<p><code>vcs_info</code> [<code>user-context</code>]</p>
|
||
<p>The main function, that runs all backends and assembles all data into
|
||
<code>${vcs_info_msg_*_}</code>. This is the function you want to call from
|
||
<code>precmd</code> if you want to include up-to-date information in your prompt
|
||
(see <a href="#vcs_005finfo-Variables">Variable Description</a> below). If an
|
||
argument is given, that string will be used instead of <code>default</code> in the
|
||
<code>user-context</code> field of the style context.</p>
|
||
<p><span id="index-vcs_005finfo_005fhookadd"></span></p>
|
||
<p><code>vcs_info_hookadd</code></p>
|
||
<p>Statically registers a number of functions to a given hook. The hook
|
||
needs to be given as the first argument; what follows is a list of
|
||
hook-function names to register to the hook. The ‘<code>+vi-</code>’ prefix needs
|
||
to be left out here. See <a href="#vcs_005finfo-Hooks">Hooks in vcs_info</a> below
|
||
for details.</p>
|
||
<p><span id="index-vcs_005finfo_005fhookdel"></span></p>
|
||
<p><code>vcs_info_hookdel</code></p>
|
||
<p>Remove hook-functions from a given hook. The hook needs to be given as
|
||
the first non-option argument; what follows is a list of hook-function
|
||
names to un-register from the hook. If ‘<code>-a</code>’ is used as the first
|
||
argument, <code>all</code> occurrences of the functions are unregistered. Otherwise
|
||
only the last occurrence is removed (if a function was registered to a
|
||
hook more than once). The ‘<code>+vi-</code>’ prefix needs to be left out here. See
|
||
<a href="#vcs_005finfo-Hooks">Hooks in vcs_info</a> below for details.</p>
|
||
<p><span id="index-vcs_005finfo_005flastmsg"></span></p>
|
||
<p><code>vcs_info_lastmsg</code></p>
|
||
<p>Outputs the last <code>${vcs_info_msg_*_}</code> value. Takes into account the
|
||
value of the <code>use-prompt-escapes</code> style in
|
||
<code>’:vcs_info:formats:command:-all-’</code>. It also only prints <code>max-exports</code>
|
||
values.</p>
|
||
<p><span id="index-vcs_005finfo_005fprintsys"></span></p>
|
||
<p><code>vcs_info_printsys</code> [<code>user-context</code>]</p>
|
||
<p>Prints a list of all supported version control systems. Useful to find
|
||
out possible contexts (and which of them are enabled) or values for the
|
||
<code>disable</code> style.</p>
|
||
<p><span id="index-vcs_005finfo_005fsetsys"></span></p>
|
||
<p><code>vcs_info_setsys</code></p>
|
||
<p>Initializes <code>vcs_info</code>’s internal list of available backends. With this
|
||
function, you can add support for new VCSs without restarting the shell.</p>
|
||
<p>All functions named <code>VCS_INFO_*</code> are for internal use only.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Variables"></span>
|
||
<span id="Variable-Description"></span></p>
|
||
<h3 id="2656-variable-description"><a class="header" href="#2656-variable-description">26.5.6 Variable Description</a></h3>
|
||
<ul>
|
||
<li><code>${vcs_info_msg_``N``_}</code> (Note the trailing underscore)<br />
|
||
Where <code>N</code> is an integer, e.g., <code>vcs_info_msg_0_</code>. These variables
|
||
are the storage for the informational message the last <code>vcs_info</code>
|
||
call has assembled. These are strongly connected to the <code>formats</code>,
|
||
<code>actionformats</code> and <code>nvcsformats</code> styles described above. Those
|
||
styles are lists. The first member of that list gets expanded into
|
||
<code>${vcs_info_msg_0_}</code>, the second into <code>${vcs_info_msg_1_}</code> and the
|
||
Nth into <code>${vcs_info_msg_N-1_}</code>. (See the <code>max-exports</code> style
|
||
above.)</li>
|
||
</ul>
|
||
<p>All variables named <code>VCS_INFO_*</code> are for internal use only.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Hooks"></span>
|
||
<span id="Hooks-in-vcs_005finfo"></span></p>
|
||
<h3 id="2657-hooks-in-vcs_info"><a class="header" href="#2657-hooks-in-vcs_info">26.5.7 Hooks in vcs_info</a></h3>
|
||
<p>Hooks are places in <code>vcs_info</code> where you can run your own code. That
|
||
code can communicate with the code that called it and through that,
|
||
change the system’s behaviour.</p>
|
||
<p>For configuration, hooks change the style context:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">:vcs_info:vcs-string+hook-name:user-context:repo-root-name
|
||
</code></pre>
|
||
</div>
|
||
<p>To register functions to a hook, you need to list them in the <code>hooks</code>
|
||
style in the appropriate context.</p>
|
||
<p>Example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*+foo:*' hooks bar baz
|
||
</code></pre>
|
||
</div>
|
||
<p>This registers functions to the hook ‘foo’ for all backends. In order to
|
||
avoid namespace problems, all registered function names are prepended by
|
||
a ‘<code>+vi-</code>’, so the actual functions called for the ‘foo’ hook are
|
||
‘<code>+vi-bar</code>’ and ‘<code>+vi-baz</code>’.</p>
|
||
<p>If you would like to register a function to a hook regardless of the
|
||
current context, you may use the <code>vcs_info_hookadd</code> function. To remove
|
||
a function that was added like that, the <code>vcs_info_hookdel</code> function can
|
||
be used.</p>
|
||
<p>If something seems weird, you can enable the ‘debug’ boolean style in
|
||
the proper context and the hook-calling code will print what it tried to
|
||
execute and whether the function in question existed.</p>
|
||
<p>When you register more than one function to a hook, all functions are
|
||
executed one after another until one function returns non-zero or until
|
||
all functions have been called. Context-sensitive hook functions are
|
||
executed <code>before</code> statically registered ones (the ones added by
|
||
<code>vcs_info_hookadd</code>).</p>
|
||
<p>You may pass data between functions via an associative array,
|
||
<code>user_data</code>. For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">+vi-git-myfirsthook(){
|
||
user_data[myval]=$myval
|
||
}
|
||
+vi-git-mysecondhook(){
|
||
# do something with ${user_data[myval]}
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>There are a number of variables that are special in hook contexts:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>ret</code><br />
|
||
The return value that the hooks system will return to the caller.
|
||
The default is an integer ‘zero’. If and how a changed <code>ret</code> value
|
||
changes the execution of the caller depends on the specific hook.
|
||
See the hook documentation below for details.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>hook_com</code><br />
|
||
An associated array which is used for bidirectional communication
|
||
from the caller to hook functions. The used keys depend on the
|
||
specific hook.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>context</code><br />
|
||
The active context of the hook. Functions that wish to change this
|
||
variable should make it local scope first.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>vcs</code><br />
|
||
The current VCS after it was detected. The same values as in the
|
||
enable/disable style are used. Available in all hooks except
|
||
<code>start-up</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Finally, the full list of currently available hooks:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>start-up</code><br />
|
||
Called after starting <code>vcs_info</code> but before the VCS in this
|
||
directory is determined. It can be used to deactivate <code>vcs_info</code>
|
||
temporarily if necessary. When <code>ret</code> is set to <code>1</code>, <code>vcs_info</code>
|
||
aborts and does nothing; when set to <code>2</code>, <code>vcs_info</code> sets up
|
||
everything as if no version control were active and exits.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pre-get-data</code><br />
|
||
Same as <code>start-up</code> but after the VCS was detected.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>gen-hg-bookmark-string</code><br />
|
||
Called in the Mercurial backend when a bookmark string is generated;
|
||
the <code>get-revision</code> and <code>get-bookmarks</code> styles must be true.</p>
|
||
<p>This hook gets the names of the Mercurial bookmarks that <code>vcs_info</code>
|
||
collected from ‘hg’.</p>
|
||
<p>If a bookmark is active, the key <code>${hook_com[hg-active-bookmark]}</code>
|
||
is set to its name. The key is otherwise unset.</p>
|
||
<p>When setting <code>ret</code> to non-zero, the string in
|
||
<code>${hook_com[hg-bookmark-string]}</code> will be used in the <code>%m</code> escape in
|
||
<code>formats</code> and <code>actionformats</code> and will be available in the global
|
||
<code>backend_misc</code> array as <code>${backend_misc[bookmarks]}</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>gen-applied-string</code><br />
|
||
Called in the <code>git</code> (with <code>stgit</code> or during rebase or merge), and
|
||
<code>hg</code> (with <code>mq</code>) backends and in <code>quilt</code> support when the
|
||
<code>applied-string</code> is generated; the <code>use-quilt</code> zstyle must be true
|
||
for <code>quilt</code> (the <code>mq</code> and <code>stgit</code> backends are active by default).</p>
|
||
<p>This hook gets the names of all applied patches which <code>vcs_info</code>
|
||
collected so far in the opposite order, which means that the first
|
||
argument is the top-most patch and so forth.</p>
|
||
<p>When setting <code>ret</code> to non-zero, the string in
|
||
<code>${hook_com[applied-string]}</code> will be available as <code>%p</code> in the
|
||
<code>patch-format</code> and <code>nopatch-format</code> styles. This hook is, in concert
|
||
with <code>set-patch-format</code>, responsible for <code>%</code>-escaping that value for
|
||
use in the prompt. (See <a href="#vcs_005finfo-Oddities">Oddities</a>.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>gen-unapplied-string</code><br />
|
||
Called in the <code>git</code> (with <code>stgit</code> or during rebase), and <code>hg</code> (with
|
||
<code>mq</code>) backend and in <code>quilt</code> support when the <code>unapplied-string</code> is
|
||
generated; the <code>get-unapplied</code> style must be true.</p>
|
||
<p>This hook gets the names of all unapplied patches which <code>vcs_info</code>
|
||
collected so far in order, which means that the first argument is
|
||
the patch next-in-line to be applied and so forth.</p>
|
||
<p>When setting <code>ret</code> to non-zero, the string in
|
||
<code>${hook_com[unapplied-string]}</code> will be available as <code>%u</code> in the
|
||
<code>patch-format</code> and <code>nopatch-format</code> styles. This hook is, in concert
|
||
with <code>set-patch-format</code>, responsible for <code>%</code>-escaping that value for
|
||
use in the prompt. (See <a href="#vcs_005finfo-Oddities">Oddities</a>.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>gen-mqguards-string</code><br />
|
||
Called in the <code>hg</code> backend when <code>guards-string</code> is generated; the
|
||
<code>get-mq</code> style must be true (default).</p>
|
||
<p>This hook gets the names of any active <code>mq</code> guards.</p>
|
||
<p>When setting <code>ret</code> to non-zero, the string in
|
||
<code>${hook_com[guards-string]}</code> will be used in the <code>%g</code> escape in the
|
||
<code>patch-format</code> and <code>nopatch-format</code> styles.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>no-vcs</code><br />
|
||
This hooks is called when no version control system was detected.</p>
|
||
<p>The ‘<code>hook_com</code>’ parameter is not used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>post-backend</code><br />
|
||
Called as soon as the backend has finished collecting information.</p>
|
||
<p>The ‘<code>hook_com</code>’ keys available are as for the <code>set-message</code> hook.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>post-quilt</code><br />
|
||
Called after the <code>quilt</code> support is done. The following information
|
||
is passed as arguments to the hook: 1. the quilt-support mode
|
||
(‘addon’ or ‘standalone’); 2. the directory that contains the
|
||
patch series; 3. the directory that holds quilt’s status information
|
||
(the ‘.pc’ directory) or the string <code>"-nopc-"</code> if that directory
|
||
wasn’t found.</p>
|
||
<p>The ‘hook_com’ parameter is not used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>set-branch-format</code><br />
|
||
Called before ‘<code>branchformat</code>’ is set. The only argument to the hook
|
||
is the format that is configured at this point.</p>
|
||
<p>The ‘<code>hook_com</code>’ keys considered are ‘<code>branch</code>’ and ‘<code>revision</code>’.
|
||
They are set to the values figured out so far by <code>vcs_info</code> and any
|
||
change will be used directly when the actual replacement is done.</p>
|
||
<p>If <code>ret</code> is set to non-zero, the string in
|
||
<code>${hook_com[branch-replace]}</code> will be used unchanged as the ‘<code>%b</code>’
|
||
replacement in the variables set by <code>vcs_info</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>set-hgrev-format</code><br />
|
||
Called before a ‘<code>hgrevformat</code>’ is set. The only argument to the
|
||
hook is the format that is configured at this point.</p>
|
||
<p>The ‘<code>hook_com</code>’ keys considered are ‘<code>hash</code>’ and ‘<code>localrev</code>’. They
|
||
are set to the values figured out so far by <code>vcs_info</code> and any
|
||
change will be used directly when the actual replacement is done.</p>
|
||
<p>If <code>ret</code> is set to non-zero, the string in
|
||
<code>${hook_com[rev-replace]}</code> will be used unchanged as the ‘<code>%i</code>’
|
||
replacement in the variables set by <code>vcs_info</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pre-addon-quilt</code><br />
|
||
This hook is used when <code>vcs_info</code>’s quilt functionality is active in
|
||
"addon" mode (quilt used on top of a real version control system).
|
||
It is activated right before any quilt specific action is taken.</p>
|
||
<p>Setting the ‘<code>ret</code>’ variable in this hook to a non-zero value avoids
|
||
any quilt specific actions from being run at all.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>set-patch-format</code><br />
|
||
This hook is used to control some of the possible expansions in
|
||
<code>patch-format</code> and <code>nopatch-format</code> styles with patch queue systems
|
||
such as quilt, mqueue and the like.</p>
|
||
<p>This hook is used in the <code>git</code>, <code>hg</code> and <code>quilt</code> backends.</p>
|
||
<p>The hook allows the control of the <code>%p</code> (<code>${hook_com[applied]}</code>) and
|
||
<code>%u</code> (<code>${hook_com[unapplied]}</code>) expansion in all backends that use
|
||
the hook. With the mercurial backend, the <code>%g</code>
|
||
(<code>${hook_com[guards]}</code>) expansion is controllable in addition to
|
||
that.</p>
|
||
<p>If <code>ret</code> is set to non-zero, the string in
|
||
<code>${hook_com[patch-replace]}</code> will be used unchanged instead of an
|
||
expanded format from <code>patch-format</code> or <code>nopatch-format</code>.</p>
|
||
<p>This hook is, in concert with the <code>gen-applied-string</code> or
|
||
<code>gen-unapplied-string</code> hooks if they are defined, responsible for
|
||
<code>%</code>-escaping the final <code>patch-format</code> value for use in the prompt.
|
||
(See <a href="#vcs_005finfo-Oddities">Oddities</a>.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>set-message</code><br />
|
||
Called each time before a ‘<code>vcs_info_msg_``N``_</code>’ message is set. It
|
||
takes two arguments; the first being the ‘<code>N</code>’ in the message
|
||
variable name, the second is the currently configured <code>formats</code> or
|
||
<code>actionformats</code>.</p>
|
||
<p>There are a number of ‘<code>hook_com</code>’ keys, that are used here:
|
||
‘<code>action</code>’, ‘<code>branch</code>’, ‘<code>base</code>’, ‘<code>base-name</code>’, ‘<code>subdir</code>’,
|
||
‘<code>staged</code>’, ‘<code>unstaged</code>’, ‘<code>revision</code>’, ‘<code>misc</code>’, ‘<code>vcs</code>’ and one
|
||
‘<code>miscN</code>’ entry for each backend-specific data field (<code>N</code> starting
|
||
at zero). They are set to the values figured out so far by
|
||
<code>vcs_info</code> and any change will be used directly when the actual
|
||
replacement is done.</p>
|
||
<p>Since this hook is triggered multiple times (once for each
|
||
configured <code>formats</code> or <code>actionformats</code>), each of the ‘<code>hook_com</code>’
|
||
keys mentioned above (except for the <code>miscN</code> entries) has an
|
||
‘<code>_orig</code>’ counterpart, so even if you changed a value to your
|
||
liking you can still get the original value in the next run.
|
||
Changing the ‘<code>_orig</code>’ values is probably not a good idea.</p>
|
||
<p>If <code>ret</code> is set to non-zero, the string in <code>${hook_com[message]}</code>
|
||
will be used unchanged as the message by <code>vcs_info</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>If all of this sounds rather confusing, take a look at
|
||
<a href="#vcs_005finfo-Examples">Examples</a> and also in the
|
||
<code>Misc/vcs_info-examples</code> file in the Zsh source. They contain some
|
||
explanatory code.</p>
|
||
<hr />
|
||
<p><span id="vcs_005finfo-Examples"></span> <span id="Examples"></span></p>
|
||
<h3 id="2658-examples"><a class="header" href="#2658-examples">26.5.8 Examples</a></h3>
|
||
<p>Don’t use <code>vcs_info</code> at all (even though it’s in your prompt):</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' enable NONE
|
||
</code></pre>
|
||
</div>
|
||
<p>Disable the backends for <code>bzr</code> and <code>svk</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' disable bzr svk
|
||
</code></pre>
|
||
</div>
|
||
<p>Disable everything <em>but</em> <code>bzr</code> and <code>svk</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*' enable bzr svk
|
||
</code></pre>
|
||
</div>
|
||
<p>Provide a special formats for <code>git</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:git:*' formats ' GIT, BABY! [%b]'
|
||
zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'
|
||
</code></pre>
|
||
</div>
|
||
<p>All <code>%x</code> expansion in all sorts of formats (<code>formats</code>, <code>actionformats</code>,
|
||
<code>branchformat</code>, you name it) are done using the ‘<code>zformat</code>’ builtin from
|
||
the ‘<code>zsh/zutil</code>’ module. That means you can do everything with these
|
||
<code>%x</code> items what zformat supports. In particular, if you want something
|
||
that is really long to have a fixed width, like a hash in a mercurial
|
||
branchformat, you can do this: <code>%12.12i</code>. That’ll shrink the 40
|
||
character hash to its 12 leading characters. The form is actually
|
||
‘<code>%``min``.``max``x</code>’. More is possible. See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a> for details.</p>
|
||
<p>Use the quicker <code>bzr</code> backend</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:bzr:*' use-simple true
|
||
</code></pre>
|
||
</div>
|
||
<p>If you do use <code>use-simple</code>, please report if it does
|
||
‘the-right-thing[tm]’.</p>
|
||
<p>Display the revision number in yellow for <code>bzr</code> and <code>svn</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:(svn|bzr):*' \
|
||
branchformat '%b%{'${fg[yellow]}'%}:%r'
|
||
</code></pre>
|
||
</div>
|
||
<p>If you want colors, make sure you enclose the color codes in
|
||
<code>%{``...``%}</code> if you want to use the string provided by <code>vcs_info</code> in
|
||
prompts.</p>
|
||
<p>Here is how to print the VCS information as a command (not in a prompt):</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">alias vcsi='vcs_info command; vcs_info_lastmsg'
|
||
</code></pre>
|
||
</div>
|
||
<p>This way, you can even define different formats for output via
|
||
<code>vcs_info_lastmsg</code> in the ’<code>:vcs_info:*:command:*</code>’ namespace.</p>
|
||
<p>Now as promised, some code that uses hooks: say, you’d like to replace
|
||
the string ‘svn’ by ‘subversion’ in <code>vcs_info</code>’s <code>%s</code> <code>formats</code>
|
||
replacement.</p>
|
||
<p>First, we will tell <code>vcs_info</code> to call a function when populating the
|
||
message variables with the gathered information:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*+set-message:*' hooks svn2subversion
|
||
</code></pre>
|
||
</div>
|
||
<p>Nothing happens. Which is reasonable, since we didn’t define the actual
|
||
function yet. To see what the hooks subsystem is trying to do, enable
|
||
the ‘<code>debug</code>’ style:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*+*:*' debug true
|
||
</code></pre>
|
||
</div>
|
||
<p>That should give you an idea what is going on. Specifically, the
|
||
function that we are looking for is ‘<code>+vi-svn2subversion</code>’. Note, the
|
||
‘<code>+vi-</code>’ prefix. So, everything is in order, just as documented. When
|
||
you are done checking out the debugging output, disable it again:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:*+*:*' debug false
|
||
</code></pre>
|
||
</div>
|
||
<p>Now, let’s define the function:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">function +vi-svn2subversion() {
|
||
[[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>Simple enough. And it could have even been simpler, if only we had
|
||
registered our function in a less generic context. If we do it only in
|
||
the ‘<code>svn</code>’ backend’s context, we don’t need to test which the active
|
||
backend is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion
|
||
</code></pre>
|
||
</div>
|
||
<div class="example">
|
||
<pre><code class="language-example">function +vi-svn2subversion() {
|
||
hook_com[vcs]=subversion
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>And finally a little more elaborate example, that uses a hook to create
|
||
a customised bookmark string for the <code>hg</code> backend.</p>
|
||
<p>Again, we start off by registering a function:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks
|
||
</code></pre>
|
||
</div>
|
||
<p>And then we define the ‘<code>+vi-hgbookmarks</code>’ function:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">function +vi-hgbookmarks() {
|
||
# The default is to connect all bookmark names by
|
||
# commas. This mixes things up a little.
|
||
# Imagine, there's one type of bookmarks that is
|
||
# special to you. Say, because it's *your* work.
|
||
# Those bookmarks look always like this: "sh/*"
|
||
# (because your initials are sh, for example).
|
||
# This makes the bookmarks string use only those
|
||
# bookmarks. If there's more than one, it
|
||
# concatenates them using commas.
|
||
# The bookmarks returned by `hg' are available in
|
||
# the function's positional parameters.
|
||
local s="${(Mj:,:)@:#sh/*}"
|
||
# Now, the communication with the code that calls
|
||
# the hook functions is done via the hook_com[]
|
||
# hash. The key at which the `gen-hg-bookmark-string'
|
||
# hook looks is `hg-bookmark-string'. So:
|
||
hook_com[hg-bookmark-string]=$s
|
||
# And to signal that we want to use the string we
|
||
# just generated, set the special variable `ret' to
|
||
# something other than the default zero:
|
||
ret=1
|
||
return 0
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>Some longer examples and code snippets which might be useful are
|
||
available in the examples file located at Misc/vcs_info-examples in the
|
||
Zsh source directory.</p>
|
||
<p>This concludes our guided tour through zsh’s <code>vcs_info</code>.</p>
|
||
<hr />
|
||
<p><span id="Prompt-Themes"></span> <span id="Prompt-Themes-1"></span></p>
|
||
<h2 id="266-prompt-themes"><a class="header" href="#266-prompt-themes">26.6 Prompt Themes</a></h2>
|
||
<hr />
|
||
<p><span id="Installation-2"></span></p>
|
||
<h3 id="2661-installation"><a class="header" href="#2661-installation">26.6.1 Installation</a></h3>
|
||
<p>You should make sure all the functions from the <code>Functions/Prompts</code>
|
||
directory of the source distribution are available; they all begin with
|
||
the string ‘<code>prompt_</code>’ except for the special function‘<code>promptinit</code>’.
|
||
You also need the ‘<code>colors</code>’ and ‘<code>add-zsh-hook</code>’ functions from
|
||
<code>Functions/Misc</code>. All these functions may already be installed on your
|
||
system; if not, you will need to find them and copy them. The directory
|
||
should appear as one of the elements of the <code>fpath</code> array (this should
|
||
already be the case if they were installed), and at least the function
|
||
<code>promptinit</code> should be autoloaded; it will autoload the rest. Finally,
|
||
to initialize the use of the system you need to call the <code>promptinit</code>
|
||
function. The following code in your <code>.zshrc</code> will arrange for this;
|
||
assume the functions are stored in the directory <code>~/myfns</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">fpath=(~/myfns $fpath)
|
||
autoload -U promptinit
|
||
promptinit
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Theme-Selection"></span></p>
|
||
<h3 id="2662-theme-selection"><a class="header" href="#2662-theme-selection">26.6.2 Theme Selection</a></h3>
|
||
<p>Use the <code>prompt</code> command to select your preferred theme. This command
|
||
may be added to your <code>.zshrc</code> following the call to <code>promptinit</code> in
|
||
order to start zsh with a theme already selected.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>prompt</code> [ <code>-c</code> | <code>-l</code> ]<br />
|
||
<code>prompt</code> [ <code>-p</code> | <code>-h</code> ] [ <code>theme</code> ... ]<br />
|
||
<code>prompt</code> [ <code>-s</code> ] <code>theme</code> [ <code>arg</code> ... ]<br />
|
||
Set or examine the prompt theme. With no options and a <code>theme</code>
|
||
argument, the theme with that name is set as the current theme. The
|
||
available themes are determined at run time; use the <code>-l</code> option to
|
||
see a list. The special <code>theme</code> ‘<code>random</code>’ selects at random one of
|
||
the available themes and sets your prompt to that.</p>
|
||
<p>In some cases the <code>theme</code> may be modified by one or more arguments,
|
||
which should be given after the theme name. See the help for each
|
||
theme for descriptions of these arguments.</p>
|
||
<p>Options are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-c</code><br />
|
||
Show the currently selected theme and its parameters, if any.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-l</code><br />
|
||
List all available prompt themes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-p</code><br />
|
||
Preview the theme named by <code>theme</code>, or all themes if no <code>theme</code>
|
||
is given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-h</code><br />
|
||
Show help for the theme named by <code>theme</code>, or for the <code>prompt</code>
|
||
function if no <code>theme</code> is given.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
Set <code>theme</code> as the current theme and save state.</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>prompt_``theme``_setup</code><br />
|
||
Each available <code>theme</code> has a setup function which is called by the
|
||
<code>prompt</code> function to install that theme. This function may define
|
||
other functions as necessary to maintain the prompt, including
|
||
functions used to preview the prompt or provide help for its use.
|
||
You should not normally call a theme’s setup function directly.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Utility-Themes"></span></p>
|
||
<h3 id="2663-utility-themes"><a class="header" href="#2663-utility-themes">26.6.3 Utility Themes</a></h3>
|
||
<ul>
|
||
<li>
|
||
<p><code>prompt off</code><br />
|
||
The theme ‘<code>off</code>’ sets all the prompt variables to minimal values
|
||
with no special effects.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>prompt default</code><br />
|
||
The theme ‘<code>default</code>’ sets all prompt variables to the same state as
|
||
if an interactive zsh was started with no initialization files.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>prompt restore</code><br />
|
||
The special theme ‘<code>restore</code>’ erases all theme settings and sets
|
||
prompt variables to their state before the first time the ‘<code>prompt</code>’
|
||
function was run, provided each theme has properly defined its
|
||
cleanup (see below).</p>
|
||
<p>Note that you can undo ‘<code>prompt off</code>’ and ‘<code>prompt default</code>’ with
|
||
‘<code>prompt restore</code>’, but a second restore does not undo the first.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Writing-Themes"></span></p>
|
||
<h3 id="2664-writing-themes"><a class="header" href="#2664-writing-themes">26.6.4 Writing Themes</a></h3>
|
||
<p>The first step for adding your own theme is to choose a name for it, and
|
||
create a file ‘<code>prompt_name_setup</code>’ in a directory in your <code>fpath</code>, such
|
||
as <code>~/myfns</code> in the example above. The file should at minimum contain
|
||
assignments for the prompt variables that your theme wishes to modify.
|
||
By convention, themes use <code>PS1</code>, <code>PS2</code>, <code>RPS1</code>, etc., rather than the
|
||
longer <code>PROMPT</code> and <code>RPROMPT</code>.</p>
|
||
<p>The file is autoloaded as a function in the current shell context, so it
|
||
may contain any necessary commands to customize your theme, including
|
||
defining additional functions. To make some complex tasks easier, your
|
||
setup function may also do any of the following:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Assign <code>prompt_opts</code><br />
|
||
The array <code>prompt_opts</code> may be assigned any of <code>"bang"</code>, <code>"cr"</code>,
|
||
<code>"percent"</code>, <code>"sp"</code>, and/or <code>"subst"</code> as values. The corresponding
|
||
setopts (<code>promptbang</code>, etc.) are turned on, all other prompt-related
|
||
options are turned off. The <code>prompt_opts</code> array preserves setopts
|
||
even beyond the scope of <code>localoptions</code>, should your function need
|
||
that.</p>
|
||
</li>
|
||
<li>
|
||
<p>Modify precmd and preexec<br />
|
||
Use of <code>add-zsh-hook</code> is recommended. The <code>precmd</code> and <code>preexec</code>
|
||
hooks are automatically adjusted if the prompt theme changes or is
|
||
disabled.</p>
|
||
</li>
|
||
<li>
|
||
<p>Declare cleanup<br />
|
||
If your function makes any other changes that should be undone when
|
||
the theme is disabled, your setup function may call</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">prompt_cleanup command
|
||
</code></pre>
|
||
</div>
|
||
<p>where <code>command</code> should be suitably quoted. If your theme is ever
|
||
disabled or replaced by another, <code>command</code> is executed with <code>eval</code>.
|
||
You may declare more than one such cleanup hook.</p>
|
||
</li>
|
||
<li>
|
||
<p>Define preview<br />
|
||
Define or autoload a function <code>prompt_name_preview</code> to display a
|
||
simulated version of your prompt. A simple default previewer is
|
||
defined by <code>promptinit</code> for themes that do not define their own.
|
||
This preview function is called by ‘<code>prompt -p</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p>Provide help<br />
|
||
Define or autoload a function <code>prompt_name_help</code> to display
|
||
documentation or help text for your theme. This help function is
|
||
called by ‘<code>prompt -h</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="ZLE-Functions"></span> <span id="ZLE-Functions-1"></span></p>
|
||
<h2 id="267-zle-functions"><a class="header" href="#267-zle-functions">26.7 ZLE Functions</a></h2>
|
||
<hr />
|
||
<p><span id="Widgets"></span></p>
|
||
<h3 id="2671-widgets"><a class="header" href="#2671-widgets">26.7.1 Widgets</a></h3>
|
||
<p>These functions all implement user-defined ZLE widgets (see <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>) which can be bound to
|
||
keystrokes in interactive shells. To use them, your <code>.zshrc</code> should
|
||
contain lines of the form</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload function
|
||
zle -N function
|
||
</code></pre>
|
||
</div>
|
||
<p>followed by an appropriate <code>bindkey</code> command to associate the function
|
||
with a key sequence. Suggested bindings are described below.</p>
|
||
<ul>
|
||
<li>
|
||
<p>bash-style word functions<br />
|
||
If you are looking for functions to implement moving over and
|
||
editing words in the manner of bash, where only alphanumeric
|
||
characters are considered word characters, you can use the functions
|
||
described in the next section. The following is sufficient:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U select-word-style
|
||
select-word-style bash
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-forward_002dword_002dmatch"></span>
|
||
<span id="index-backward_002dword_002dmatch"></span>
|
||
<span id="index-kill_002dword_002dmatch"></span>
|
||
<span id="index-backward_002dkill_002dword_002dmatch"></span>
|
||
<span id="index-transpose_002dwords_002dmatch"></span>
|
||
<span id="index-capitalize_002dword_002dmatch"></span>
|
||
<span id="index-up_002dcase_002dword_002dmatch"></span>
|
||
<span id="index-down_002dcase_002dword_002dmatch"></span>
|
||
<span id="index-delete_002dwhole_002dword_002dmatch"></span>
|
||
<span id="index-select_002dword_002dmatch"></span>
|
||
<span id="index-select_002dword_002dstyle"></span>
|
||
<span id="index-match_002dword_002dcontext"></span>
|
||
<span id="index-match_002dwords_002dby_002dstyle"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>forward-word-match</code>, <code>backward-word-match</code><br />
|
||
<code>kill-word-match</code>, <code>backward-kill-word-match</code><br />
|
||
<code>transpose-words-match</code>, <code>capitalize-word-match</code><br />
|
||
<code>up-case-word-match</code>, <code>down-case-word-match</code><br />
|
||
<code>delete-whole-word-match</code>, <code>select-word-match</code><br />
|
||
<code>select-word-style</code>, <code>match-word-context</code>, <code>match-words-by-style</code><br />
|
||
The first eight ‘<code>-match</code>’ functions are drop-in replacements for
|
||
the builtin widgets without the suffix. By default they behave in a
|
||
similar way. However, by the use of styles and the function
|
||
<code>select-word-style</code>, the way words are matched can be altered.
|
||
<code>select-word-match</code> is intended to be used as a text object in vi
|
||
mode but with custom word styles. For comparison, the widgets
|
||
described in <a href="Zsh-Line-Editor.html#Text-Objects">Text Objects</a> use
|
||
fixed definitions of words, compatible with the <code>vim</code> editor.</p>
|
||
<p>The simplest way of configuring the functions is to use
|
||
<code>select-word-style</code>, which can either be called as a normal function
|
||
with the appropriate argument, or invoked as a user-defined widget
|
||
that will prompt for the first character of the word style to be
|
||
used. The first time it is invoked, the first eight <code>-match</code>
|
||
functions will automatically replace the builtin versions, so they
|
||
do not need to be loaded explicitly.</p>
|
||
<p>The word styles available are as follows. Only the first character
|
||
is examined.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>bash</code><br />
|
||
Word characters are alphanumeric characters only.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>normal</code><br />
|
||
As in normal shell operation: word characters are alphanumeric
|
||
characters plus any characters present in the string given by
|
||
the parameter <code>$WORDCHARS</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>shell</code><br />
|
||
Words are complete shell command arguments, possibly including
|
||
complete quoted strings, or any tokens special to the shell.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>whitespace</code><br />
|
||
Words are any set of characters delimited by whitespace.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>default</code><br />
|
||
Restore the default settings; this is usually the same as
|
||
‘<code>normal</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
<p>All but ‘<code>default</code>’ can be input as an upper case character, which
|
||
has the same effect but with subword matching turned on. In this
|
||
case, words with upper case characters are treated specially: each
|
||
separate run of upper case characters, or an upper case character
|
||
followed by any number of other characters, is considered a word.
|
||
The style <code>subword-range</code> can supply an alternative character range
|
||
to the default ‘<code>[:upper:]</code>’; the value of the style is treated as
|
||
the contents of a ‘<code>[``...``]</code>’ pattern (note that the outer
|
||
brackets should not be supplied, only those surrounding named
|
||
ranges).</p>
|
||
<p>More control can be obtained using the <code>zstyle</code> command, as
|
||
described in <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>. Each style is
|
||
looked up in the context <code>:zle:``widget</code> where <code>widget</code> is the name
|
||
of the user-defined widget, not the name of the function
|
||
implementing it, so in the case of the definitions supplied by
|
||
<code>select-word-style</code> the appropriate contexts are
|
||
<code>:zle:forward-word</code>, and so on. The function <code>select-word-style</code>
|
||
itself always defines styles for the context ‘<code>:zle:*</code>’ which can be
|
||
overridden by more specific (longer) patterns as well as explicit
|
||
contexts.</p>
|
||
<p>The style <code>word-style</code> specifies the rules to use. This may have the
|
||
following values.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>normal</code><br />
|
||
Use the standard shell rules, i.e. alphanumerics and
|
||
<code>$WORDCHARS</code>, unless overridden by the styles <code>word-chars</code> or
|
||
<code>word-class</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>specified</code><br />
|
||
Similar to <code>normal</code>, but <em>only</em> the specified characters, and
|
||
not also alphanumerics, are considered word characters.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>unspecified</code><br />
|
||
The negation of specified. The given characters are those which
|
||
will <em>not</em> be considered part of a word.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>shell</code><br />
|
||
Words are obtained by using the syntactic rules for generating
|
||
shell command arguments. In addition, special tokens which are
|
||
never command arguments such as ‘<code>()</code>’ are also treated as
|
||
words.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>whitespace</code><br />
|
||
Words are whitespace-delimited strings of characters.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The first three of those rules usually use <code>$WORDCHARS</code>, but the
|
||
value in the parameter can be overridden by the style <code>word-chars</code>,
|
||
which works in exactly the same way as <code>$WORDCHARS</code>. In addition,
|
||
the style <code>word-class</code> uses character class syntax to group
|
||
characters and takes precedence over <code>word-chars</code> if both are set.
|
||
The <code>word-class</code> style does not include the surrounding brackets of
|
||
the character class; for example, ‘<code>-:[:alnum:]</code>’ is a valid
|
||
<code>word-class</code> to include all alphanumerics plus the characters ‘<code>-</code>’
|
||
and ‘<code>:</code>’. Be careful including ‘<code>]</code>’, ‘<code>^</code>’ and ‘<code>-</code>’ as these are
|
||
special inside character classes.</p>
|
||
<p><code>word-style</code> may also have ‘<code>-subword</code>’ appended to its value to
|
||
turn on subword matching, as described above.</p>
|
||
<p>The style <code>skip-chars</code> is mostly useful for <code>transpose-words</code> and
|
||
similar functions. If set, it gives a count of characters starting
|
||
at the cursor position which will not be considered part of the word
|
||
and are treated as space, regardless of what they actually are. For
|
||
example, if</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':zle:transpose-words' skip-chars 1
|
||
</code></pre>
|
||
</div>
|
||
<p>has been set, and <code>transpose-words-match</code> is called with the cursor
|
||
on the <code>X</code> of <code>foo``X``bar</code>, where <code>X</code> can be any character, then
|
||
the resulting expression is <code>bar``X``foo</code>.</p>
|
||
<p>Finer grained control can be obtained by setting the style
|
||
<code>word-context</code> to an array of pairs of entries. Each pair of entries
|
||
consists of a <code>pattern</code> and a <code>subcontext</code>. The shell argument the
|
||
cursor is on is matched against each <code>pattern</code> in turn until one
|
||
matches; if it does, the context is extended by a colon and the
|
||
corresponding <code>subcontext</code>. Note that the test is made against the
|
||
original word on the line, with no stripping of quotes. Special
|
||
handling is done between words: the current context is examined and
|
||
if it contains the string <code>between</code> the word is set to a single
|
||
space; else if it is contains the string <code>back</code>, the word before the
|
||
cursor is considered, else the word after cursor is considered. Some
|
||
examples are given below.</p>
|
||
<p>The style <code>skip-whitespace-first</code> is only used with the
|
||
<code>forward-word</code> widget. If it is set to true, then <code>forward-word</code>
|
||
skips any non-word-characters, followed by any non-word-characters:
|
||
this is similar to the behaviour of other word-orientated widgets,
|
||
and also that used by other editors, however it differs from the
|
||
standard zsh behaviour. When using <code>select-word-style</code> the widget is
|
||
set in the context <code>:zle:*</code> to <code>true</code> if the word style is <code>bash</code>
|
||
and <code>false</code> otherwise. It may be overridden by setting it in the
|
||
more specific context <code>:zle:forward-word*</code>.</p>
|
||
<p>It is possible to create widgets with specific behaviour by defining
|
||
a new widget implemented by the appropriate generic function, then
|
||
setting a style for the context of the specific widget. For example,
|
||
the following defines a widget <code>backward-kill-space-word</code> using
|
||
<code>backward-kill-word-match</code>, the generic widget implementing
|
||
<code>backward-kill-word</code> behaviour, and ensures that the new widget
|
||
always implements space-delimited behaviour.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N backward-kill-space-word backward-kill-word-match
|
||
zstyle :zle:backward-kill-space-word word-style space
|
||
</code></pre>
|
||
</div>
|
||
<p>The widget <code>backward-kill-space-word</code> can now be bound to a key.</p>
|
||
<p>Here are some further examples of use of the styles, actually taken
|
||
from the simplified interface in <code>select-word-style</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':zle:*' word-style standard
|
||
zstyle ':zle:*' word-chars ''
|
||
</code></pre>
|
||
</div>
|
||
<p>Implements bash-style word handling for all widgets, i.e. only
|
||
alphanumerics are word characters; equivalent to setting the
|
||
parameter <code>WORDCHARS</code> empty for the given context.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">style ':zle:*kill*' word-style space
|
||
</code></pre>
|
||
</div>
|
||
<p>Uses space-delimited words for widgets with the word ‘kill’ in the
|
||
name. Neither of the styles <code>word-chars</code> nor <code>word-class</code> is used in
|
||
this case.</p>
|
||
<p>Here are some examples of use of the <code>word-context</code> style to extend
|
||
the context.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':zle:*' word-context \
|
||
"*/*" filename "[[:space:]]" whitespace
|
||
zstyle ':zle:transpose-words:whitespace' word-style shell
|
||
zstyle ':zle:transpose-words:filename' word-style normal
|
||
zstyle ':zle:transpose-words:filename' word-chars ''
|
||
</code></pre>
|
||
</div>
|
||
<p>This provides two different ways of using <code>transpose-words</code>
|
||
depending on whether the cursor is on whitespace between words or on
|
||
a filename, here any word containing a <code>/</code>. On whitespace, complete
|
||
arguments as defined by standard shell rules will be transposed. In
|
||
a filename, only alphanumerics will be transposed. Elsewhere, words
|
||
will be transposed using the default style for
|
||
<code>:zle:transpose-words</code>.</p>
|
||
<p>The word matching and all the handling of <code>zstyle</code> settings is
|
||
actually implemented by the function <code>match-words-by-style</code>. This
|
||
can be used to create new user-defined widgets. The calling function
|
||
should set the local parameter <code>curcontext</code> to <code>:zle:``widget</code>,
|
||
create the local parameter <code>matched_words</code> and call
|
||
<code>match-words-by-style</code> with no arguments. On return, <code>matched_words</code>
|
||
will be set to an array with the elements: (1) the start of the line
|
||
(2) the word before the cursor (3) any non-word characters between
|
||
that word and the cursor (4) any non-word character at the cursor
|
||
position plus any remaining non-word characters before the next
|
||
word, including all characters specified by the <code>skip-chars</code> style,
|
||
(5) the word at or following the cursor (6) any non-word characters
|
||
following that word (7) the remainder of the line. Any of the
|
||
elements may be an empty string; the calling function should test
|
||
for this to decide whether it can perform its function.</p>
|
||
<p>If the variable <code>matched_words</code> is defined by the caller to
|
||
<code>match-words-by-style</code> as an associative array (<code>local -A matched_words</code>), then the seven values given above should be
|
||
retrieved from it as elements named <code>start</code>, <code>word-before-cursor</code>,
|
||
<code>ws-before-cursor</code>, <code>ws-after-cursor</code>, <code>word-after-cursor</code>,
|
||
<code>ws-after-word</code>, and <code>end</code>. In addition the element <code>is-word-start</code>
|
||
is 1 if the cursor is on the start of a word or subword, or on white
|
||
space before it (the cases can be distinguished by testing the
|
||
<code>ws-after-cursor</code> element) and 0 otherwise. This form is recommended
|
||
for future compatibility.</p>
|
||
<p>It is possible to pass options with arguments to
|
||
<code>match-words-by-style</code> to override the use of styles. The options
|
||
are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-w</code><br />
|
||
<code>word-style</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
<code>skip-chars</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>-c</code><br />
|
||
<code>word-class</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>-C</code><br />
|
||
<code>word-chars</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><br />
|
||
<code>subword-range</code></p>
|
||
</li>
|
||
</ul>
|
||
<p>For example, <code>match-words-by-style -w shell -c 0</code> may be used to
|
||
extract the command argument around the cursor.</p>
|
||
<p>The <code>word-context</code> style is implemented by the function
|
||
<code>match-word-context</code>. This should not usually need to be called
|
||
directly.</p>
|
||
<p><span id="index-bracketed_002dpaste_002dmagic"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>bracketed-paste-magic</code><br />
|
||
The <code>bracketed-paste</code> widget (see
|
||
<a href="Zsh-Line-Editor.html#Miscellaneous">Miscellaneous</a> in
|
||
<a href="Zsh-Line-Editor.html#Zle-Widgets">Widgets</a>) inserts pasted text
|
||
literally into the editor buffer rather than interpret it as
|
||
keystrokes. This disables some common usages where the self-insert
|
||
widget is replaced in order to accomplish some extra processing. An
|
||
example is the contributed <code>url-quote-magic</code> widget described below.</p>
|
||
<p>The <code>bracketed-paste-magic</code> widget is meant to replace
|
||
<code>bracketed-paste</code> with a wrapper that re-enables these self-insert
|
||
actions, and other actions as selected by zstyles. Therefore this
|
||
widget is installed with</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -Uz bracketed-paste-magic
|
||
zle -N bracketed-paste bracketed-paste-magic
|
||
</code></pre>
|
||
</div>
|
||
<p>Other than enabling some widget processing, <code>bracketed-paste-magic</code>
|
||
attempts to replicate <code>bracketed-paste</code> as faithfully as possible.</p>
|
||
<p>The following zstyles may be set to control processing of pasted
|
||
text. All are looked up in the context ‘<code>:bracketed-paste-magic</code>’.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>active-widgets</code><br />
|
||
A list of patterns matching widget names that should be
|
||
activated during the paste. All other key sequences are
|
||
processed as self-insert-unmeta. The default is ‘<code>self-*</code>’ so
|
||
any user-defined widgets named with that prefix are active along
|
||
with the builtin self-insert.</p>
|
||
<p>If this style is not set (explicitly deleted) or set to an empty
|
||
value, no widgets are active and the pasted text is inserted
|
||
literally. If the value includes ‘<code>undefined-key</code>’, any unknown
|
||
sequences are discarded from the pasted text.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>inactive-keys</code><br />
|
||
The inverse of <code>active-widgets</code>, a list of key sequences that
|
||
always use <code>self-insert-unmeta</code> even when bound to an active
|
||
widget. Note that this is a list of literal key sequences, not
|
||
patterns.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>paste-init</code><br />
|
||
A list of function names, called in widget context (but not as
|
||
widgets). The functions are called in order until one of them
|
||
returns a non-zero status. The parameter ‘<code>PASTED</code>’ contains the
|
||
initial state of the pasted text. All other ZLE parameters such
|
||
as ‘<code>BUFFER</code>’ have their normal values and side-effects, and
|
||
full history is available, so for example <code>paste-init</code> functions
|
||
may move words from <code>BUFFER</code> into <code>PASTED</code> to make those words
|
||
visible to the <code>active-widgets</code>.</p>
|
||
<p>A non-zero return from a <code>paste-init</code> function does <em>not</em>
|
||
prevent the paste itself from proceeding.</p>
|
||
<p>Loading <code>bracketed-paste-magic</code> defines <code>backward-extend-paste</code>,
|
||
a helper function for use in <code>paste-init</code>.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :bracketed-paste-magic paste-init \
|
||
backward-extend-paste
|
||
</code></pre>
|
||
</div>
|
||
<p>When a paste would insert into the middle of a word or append
|
||
text to a word already on the line, <code>backward-extend-paste</code>
|
||
moves the prefix from <code>LBUFFER</code> into <code>PASTED</code> so that the
|
||
<code>active-widgets</code> see the full word so far. This may be useful
|
||
with <code>url-quote-magic</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>paste-finish</code><br />
|
||
Another list of function names called in order until one returns
|
||
non-zero. These functions are called <em>after</em> the pasted text has
|
||
been processed by the <code>active-widgets</code>, but <em>before</em> it is
|
||
inserted into ‘<code>BUFFER</code>’. ZLE parameters have their normal
|
||
values and side-effects.</p>
|
||
<p>A non-zero return from a <code>paste-finish</code> function does <em>not</em>
|
||
prevent the paste itself from proceeding.</p>
|
||
<p>Loading <code>bracketed-paste-magic</code> also defines <code>quote-paste</code>, a
|
||
helper function for use in <code>paste-finish</code>.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :bracketed-paste-magic paste-finish \
|
||
quote-paste
|
||
zstyle :bracketed-paste-magic:finish quote-style \
|
||
qqq
|
||
</code></pre>
|
||
</div>
|
||
<p>When the pasted text is inserted into <code>BUFFER</code>, it is quoted per
|
||
the <code>quote-style</code> value. To forcibly turn off the built-in
|
||
numeric prefix quoting of <code>bracketed-paste</code>, use:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :bracketed-paste-magic:finish quote-style \
|
||
none
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p><em>Important:</em> During <code>active-widgets</code> processing of the paste (after
|
||
<code>paste-init</code> and before <code>paste-finish</code>), <code>BUFFER</code> starts empty and
|
||
history is restricted, so cursor motions, etc., may not pass outside
|
||
of the pasted content. Text assigned to <code>BUFFER</code> by the active
|
||
widgets is copied back into <code>PASTED</code> before <code>paste-finish</code>.</p>
|
||
<p><span id="index-copy_002dearlier_002dword"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>copy-earlier-word</code><br />
|
||
This widget works like a combination of <code>insert-last-word</code> and
|
||
<code>copy-prev-shell-word</code>. Repeated invocations of the widget retrieve
|
||
earlier words on the relevant history line. With a numeric argument
|
||
<code>N</code>, insert the <code>N</code>th word from the history line; <code>N</code> may be
|
||
negative to count from the end of the line.</p>
|
||
<p>If <code>insert-last-word</code> has been used to retrieve the last word on a
|
||
previous history line, repeated invocations will replace that word
|
||
with earlier words from the same line.</p>
|
||
<p>Otherwise, the widget applies to words on the line currently being
|
||
edited. The <code>widget</code> style can be set to the name of another widget
|
||
that should be called to retrieve words. This widget must accept the
|
||
same three arguments as <code>insert-last-word</code>.</p>
|
||
<p><span id="index-cycle_002dcompletion_002dpositions"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>cycle-completion-positions</code><br />
|
||
After inserting an unambiguous string into the command line, the new
|
||
function based completion system may know about multiple places in
|
||
this string where characters are missing or differ from at least one
|
||
of the possible matches. It will then place the cursor on the
|
||
position it considers to be the most interesting one, i.e. the one
|
||
where one can disambiguate between as many matches as possible with
|
||
as little typing as possible.</p>
|
||
<p>This widget allows the cursor to be easily moved to the other
|
||
interesting spots. It can be invoked repeatedly to cycle between all
|
||
positions reported by the completion system.</p>
|
||
<p><span id="index-delete_002dwhole_002dword_002dmatch-1"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>delete-whole-word-match</code><br />
|
||
This is another function which works like the <code>-match</code> functions
|
||
described immediately above, i.e. using styles to decide the word
|
||
boundaries. However, it is not a replacement for any existing
|
||
function.</p>
|
||
<p>The basic behaviour is to delete the word around the cursor. There
|
||
is no numeric argument handling; only the single word around the
|
||
cursor is considered. If the widget contains the string <code>kill</code>, the
|
||
removed text will be placed in the cutbuffer for future yanking.
|
||
This can be obtained by defining <code>kill-whole-word-match</code> as follows:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N kill-whole-word-match delete-whole-word-match
|
||
</code></pre>
|
||
</div>
|
||
<p>and then binding the widget <code>kill-whole-word-match</code>.</p>
|
||
<p><span id="index-down_002dline_002dor_002dbeginning_002dsearch"></span>
|
||
<span id="index-up_002dline_002dor_002dbeginning_002dsearch"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>up-line-or-beginning-search</code>, <code>down-line-or-beginning-search</code><br />
|
||
These widgets are similar to the builtin functions
|
||
<code>up-line-or-search</code> and <code>down-line-or-search</code>: if in a multiline
|
||
buffer they move up or down within the buffer, otherwise they search
|
||
for a history line matching the start of the current line. In this
|
||
case, however, they search for a line which matches the current line
|
||
up to the current cursor position, in the manner of
|
||
<code>history-beginning-search-backward</code> and <code>-forward</code>, rather than the
|
||
first word on the line.</p>
|
||
<p><span id="index-edit_002dcommand_002dline"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>edit-command-line</code><br />
|
||
Edit the command line using your visual editor, as in <code>ksh</code>.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey -M vicmd v edit-command-line
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-expand_002dabsolute_002dpath"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>expand-absolute-path</code><br />
|
||
Expand the file name under the cursor to an absolute path, resolving
|
||
symbolic links. Where possible, the initial path segment is turned
|
||
into a named directory or reference to a user’s home directory.</p>
|
||
<p><span id="index-history_002dbeginning_002dsearch_002dbackward_002dend"></span>
|
||
<span id="index-history_002dbeginning_002dsearch_002dforward_002dend"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>history-search-end</code><br />
|
||
This function implements the widgets
|
||
<code>history-beginning-search-backward-end</code> and
|
||
<code>history-beginning-search-forward-end</code>. These commands work by first
|
||
calling the corresponding builtin widget (see <a href="Zsh-Line-Editor.html#History-Control">History
|
||
Control</a>) and then moving the
|
||
cursor to the end of the line. The original cursor position is
|
||
remembered and restored before calling the builtin widget a second
|
||
time, so that the same search is repeated to look farther through
|
||
the history.</p>
|
||
<p>Although you <code>autoload</code> only one function, the commands to use it
|
||
are slightly different because it implements two widgets.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N history-beginning-search-backward-end \
|
||
history-search-end
|
||
zle -N history-beginning-search-forward-end \
|
||
history-search-end
|
||
bindkey '\e^P' history-beginning-search-backward-end
|
||
bindkey '\e^N' history-beginning-search-forward-end
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-history_002dbeginning_002dsearch_002dmenu"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>history-beginning-search-menu</code><br />
|
||
This function implements yet another form of history searching. The
|
||
text before the cursor is used to select lines from the history, as
|
||
for <code>history-beginning-search-backward</code> except that all matches are
|
||
shown in a numbered menu. Typing the appropriate digits inserts the
|
||
full history line. Note that leading zeroes must be typed (they are
|
||
only shown when necessary for removing ambiguity). The entire
|
||
history is searched; there is no distinction between forwards and
|
||
backwards.</p>
|
||
<p>With a numeric argument, the search is not anchored to the start of
|
||
the line; the string typed by the use may appear anywhere in the
|
||
line in the history.</p>
|
||
<p>If the widget name contains ‘<code>-end</code>’ the cursor is moved to the end
|
||
of the line inserted. If the widget name contains ‘<code>-space</code>’ any
|
||
space in the text typed is treated as a wildcard and can match
|
||
anything (hence a leading space is equivalent to giving a numeric
|
||
argument). Both forms can be combined, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N history-beginning-search-menu-space-end \
|
||
history-beginning-search-menu
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-history_002dpattern_002dsearch"></span>
|
||
<span id="index-history_002dpattern_002dsearch_002dbackward"></span>
|
||
<span id="index-history_002dpattern_002dsearch_002dforward"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>history-pattern-search</code><br />
|
||
The function <code>history-pattern-search</code> implements widgets which
|
||
prompt for a pattern with which to search the history backwards or
|
||
forwards. The pattern is in the usual zsh format, however the first
|
||
character may be <code>^</code> to anchor the search to the start of the line,
|
||
and the last character may be <code>$</code> to anchor the search to the end of
|
||
the line. If the search was not anchored to the end of the line the
|
||
cursor is positioned just after the pattern found.</p>
|
||
<p>The commands to create bindable widgets are similar to those in the
|
||
example immediately above:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U history-pattern-search
|
||
zle -N history-pattern-search-backward history-pattern-search
|
||
zle -N history-pattern-search-forward history-pattern-search
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-incarg"></span>
|
||
<span id="index-incarg_002c-use-of"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>incarg</code><br />
|
||
Typing the keystrokes for this widget with the cursor placed on or
|
||
to the left of an integer causes that integer to be incremented by
|
||
one. With a numeric argument, the number is incremented by the
|
||
amount of the argument (decremented if the numeric argument is
|
||
negative). The shell parameter <code>incarg</code> may be set to change the
|
||
default increment to something other than one.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey '^X+' incarg
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-incremental_002dcomplete_002dword"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>incremental-complete-word</code><br />
|
||
This allows incremental completion of a word. After starting this
|
||
command, a list of completion choices can be shown after every
|
||
character you type, which you can delete with <code>^H</code> or <code>DEL</code>.
|
||
Pressing return accepts the completion so far and returns you to
|
||
normal editing (that is, the command line is <em>not</em> immediately
|
||
executed). You can hit <code>TAB</code> to do normal completion, <code>^G</code> to abort
|
||
back to the state when you started, and <code>^D</code> to list the matches.</p>
|
||
<p>This works only with the new function based completion system.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey '^Xi' incremental-complete-word
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-insert_002dcomposed_002dchar"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>insert-composed-char</code><br />
|
||
This function allows you to compose characters that don’t appear on
|
||
the keyboard to be inserted into the command line. The command is
|
||
followed by two keys corresponding to ASCII characters (there is no
|
||
prompt). For accented characters, the two keys are a base character
|
||
followed by a code for the accent, while for other special
|
||
characters the two characters together form a mnemonic for the
|
||
character to be inserted. The two-character codes are a subset of
|
||
those given by RFC 1345 (see for example
|
||
<code>http://www.faqs.org/rfcs/rfc1345.html</code>).</p>
|
||
<p>The function may optionally be followed by up to two characters
|
||
which replace one or both of the characters read from the keyboard;
|
||
if both characters are supplied, no input is read. For example,
|
||
<code>insert-composed-char a:</code> can be used within a widget to insert an a
|
||
with umlaut into the command line. This has the advantages over use
|
||
of a</p>
|
||
<p>For best results zsh should have been built with support for
|
||
multibyte characters (configured with <code>–enable-multibyte</code>); however,
|
||
the function works for the limited range of characters available in
|
||
single-byte character sets such as ISO-8859-1.</p>
|
||
<p>The character is converted into the local representation and
|
||
inserted into the command line at the cursor position. (The
|
||
conversion is done within the shell, using whatever facilities the C
|
||
library provides.) With a numeric argument, the character and its
|
||
code are previewed in the status line</p>
|
||
<p>The function may be run outside zle in which case it prints the
|
||
character (together with a newline) to standard output. Input is
|
||
still read from keystrokes.</p>
|
||
<p>See <code>insert-unicode-char</code> for an alternative way of inserting
|
||
Unicode characters using their hexadecimal character number.</p>
|
||
<p>The set of accented characters is reasonably complete up to Unicode
|
||
character U+0180, the set of special characters less so. However, it
|
||
is very sporadic from that point. Adding new characters is easy,
|
||
however; see the function <code>define-composed-chars</code>. Please send any
|
||
additions to <code>zsh-workers@zsh.org</code>.</p>
|
||
<p>The codes for the second character when used to accent the first are
|
||
as follows. Note that not every character can take every accent.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>!</code><br />
|
||
Grave.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’</code><br />
|
||
Acute.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>></code><br />
|
||
Circumflex.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>?</code><br />
|
||
Tilde. (This is not <code>~</code> as RFC 1345 does not assume that
|
||
character is present on the keyboard.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-</code><br />
|
||
Macron. (A horizontal bar over the base character.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>(</code><br />
|
||
Breve. (A shallow dish shape over the base character.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>.</code><br />
|
||
Dot above the base character, or in the case of <code>i</code> no dot, or
|
||
in the case of <code>L</code> and <code>l</code> a centered dot.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:</code><br />
|
||
Diaeresis (Umlaut).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>c</code><br />
|
||
Cedilla.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>_</code><br />
|
||
Underline, however there are currently no underlined characters.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>/</code><br />
|
||
Stroke through the base character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>"</code><br />
|
||
Double acute (only supported on a few letters).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>;</code><br />
|
||
Ogonek. (A little forward facing hook at the bottom right of the
|
||
character.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code><</code><br />
|
||
Caron. (A little v over the letter.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>0</code><br />
|
||
Circle over the base character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>2</code><br />
|
||
Hook over the base character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>9</code><br />
|
||
Horn over the base character.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The most common characters from the Arabic, Cyrillic, Greek and
|
||
Hebrew alphabets are available; consult RFC 1345 for the appropriate
|
||
sequences. In addition, a set of two letter codes not in RFC 1345
|
||
are available for the double-width characters corresponding to ASCII
|
||
characters from <code>!</code> to <code>~</code> (0x21 to 0x7e) by preceding the character
|
||
with <code>^</code>, for example <code>^A</code> for a double-width <code>A</code>.</p>
|
||
<p>The following other two-character sequences are understood.</p>
|
||
<ul>
|
||
<li>
|
||
<p>ASCII characters<br />
|
||
These are already present on most keyboards:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code><(</code><br />
|
||
Left square bracket</p>
|
||
</li>
|
||
<li>
|
||
<p><code>//</code><br />
|
||
Backslash (solidus)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>)></code><br />
|
||
Right square bracket</p>
|
||
</li>
|
||
<li>
|
||
<p><code>(!</code><br />
|
||
Left brace (curly bracket)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!!</code><br />
|
||
Vertical bar (pipe symbol)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!)</code><br />
|
||
Right brace (curly bracket)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’?</code><br />
|
||
Tilde</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Special letters<br />
|
||
Characters found in various variants of the Latin alphabet:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>ss</code><br />
|
||
Eszett (scharfes S)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>D-</code>, <code>d-</code><br />
|
||
Eth</p>
|
||
</li>
|
||
<li>
|
||
<p><code>TH</code>, <code>th</code><br />
|
||
Thorn</p>
|
||
</li>
|
||
<li>
|
||
<p><code>kk</code><br />
|
||
Kra</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’n</code><br />
|
||
’n</p>
|
||
</li>
|
||
<li>
|
||
<p><code>NG</code>, <code>ng</code><br />
|
||
Ng</p>
|
||
</li>
|
||
<li>
|
||
<p><code>OI</code>, <code>oi</code><br />
|
||
Oi</p>
|
||
</li>
|
||
<li>
|
||
<p><code>yr</code><br />
|
||
yr</p>
|
||
</li>
|
||
<li>
|
||
<p><code>ED</code><br />
|
||
ezh</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Currency symbols</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>Ct</code><br />
|
||
Cent</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Pd</code><br />
|
||
Pound sterling (also lira and others)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Cu</code><br />
|
||
Currency</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Ye</code><br />
|
||
Yen</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Eu</code><br />
|
||
Euro (N.B. not in RFC 1345)</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Punctuation characters<br />
|
||
References to "right" quotes indicate the shape (like a 9 rather
|
||
than 6) rather than their grammatical use. (For example, a
|
||
"right" low double quote is used to open quotations in German.)</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>!I</code><br />
|
||
Inverted exclamation mark</p>
|
||
</li>
|
||
<li>
|
||
<p><code>BB</code><br />
|
||
Broken vertical bar</p>
|
||
</li>
|
||
<li>
|
||
<p><code>SE</code><br />
|
||
Section</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Co</code><br />
|
||
Copyright</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-a</code><br />
|
||
Spanish feminine ordinal indicator</p>
|
||
</li>
|
||
<li>
|
||
<p><code><<</code><br />
|
||
Left guillemet</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-``-</code><br />
|
||
Soft hyphen</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Rg</code><br />
|
||
Registered trade mark</p>
|
||
</li>
|
||
<li>
|
||
<p><code>PI</code><br />
|
||
Pilcrow (paragraph)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-o</code><br />
|
||
Spanish masculine ordinal indicator</p>
|
||
</li>
|
||
<li>
|
||
<p><code>>></code><br />
|
||
Right guillemet</p>
|
||
</li>
|
||
<li>
|
||
<p><code>?I</code><br />
|
||
Inverted question mark</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-1</code><br />
|
||
Hyphen</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-N</code><br />
|
||
En dash</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-M</code><br />
|
||
Em dash</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-3</code><br />
|
||
Horizontal bar</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:3</code><br />
|
||
Vertical ellipsis</p>
|
||
</li>
|
||
<li>
|
||
<p><code>.3</code><br />
|
||
Horizontal midline ellipsis</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!2</code><br />
|
||
Double vertical line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>=2</code><br />
|
||
Double low line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’6</code><br />
|
||
Left single quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’9</code><br />
|
||
Right single quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>.9</code><br />
|
||
"Right" low quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>9’</code><br />
|
||
Reversed "right" quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>"6</code><br />
|
||
Left double quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>"9</code><br />
|
||
Right double quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:9</code><br />
|
||
"Right" low double quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>9"</code><br />
|
||
Reversed "right" double quote</p>
|
||
</li>
|
||
<li>
|
||
<p><code>/-</code><br />
|
||
Dagger</p>
|
||
</li>
|
||
<li>
|
||
<p><code>/=</code><br />
|
||
Double dagger</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Mathematical symbols</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>DG</code><br />
|
||
Degree</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-2</code>, <code>+-</code>, <code>-+</code><br />
|
||
- sign, +/- sign, -/+ sign</p>
|
||
</li>
|
||
<li>
|
||
<p><code>2S</code><br />
|
||
Superscript 2</p>
|
||
</li>
|
||
<li>
|
||
<p><code>3S</code><br />
|
||
Superscript 3</p>
|
||
</li>
|
||
<li>
|
||
<p><code>1S</code><br />
|
||
Superscript 1</p>
|
||
</li>
|
||
<li>
|
||
<p><code>My</code><br />
|
||
Micro</p>
|
||
</li>
|
||
<li>
|
||
<p><code>.M</code><br />
|
||
Middle dot</p>
|
||
</li>
|
||
<li>
|
||
<p><code>14</code><br />
|
||
Quarter</p>
|
||
</li>
|
||
<li>
|
||
<p><code>12</code><br />
|
||
Half</p>
|
||
</li>
|
||
<li>
|
||
<p><code>34</code><br />
|
||
Three quarters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*X</code><br />
|
||
Multiplication</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-:</code><br />
|
||
Division</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%0</code><br />
|
||
Per mille</p>
|
||
</li>
|
||
<li>
|
||
<p><code>FA</code>, <code>TE</code>, <code>/0</code><br />
|
||
For all, there exists, empty set</p>
|
||
</li>
|
||
<li>
|
||
<p><code>dP</code>, <code>DE</code>, <code>NB</code><br />
|
||
Partial derivative, delta (increment), del (nabla)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>(-</code>, <code>-)</code><br />
|
||
Element of, contains</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*P</code>, <code>+Z</code><br />
|
||
Product, sum</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*-</code>, <code>Ob</code>, <code>Sb</code><br />
|
||
Asterisk, ring, bullet</p>
|
||
</li>
|
||
<li>
|
||
<p><code>RT</code>, <code>0(</code>, <code>00</code><br />
|
||
Root sign, proportional to, infinity</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Other symbols</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>cS</code>, <code>cH</code>, <code>cD</code>, <code>cC</code><br />
|
||
Card suits: spades, hearts, diamonds, clubs</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Md</code>, <code>M8</code>, <code>M2</code>, <code>Mb</code>, <code>Mx</code>, <code>MX</code><br />
|
||
Musical notation: crotchet (quarter note), quaver (eighth
|
||
note), semiquavers (sixteenth notes), flag sign, natural
|
||
sign, sharp sign</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Fm</code>, <code>Ml</code><br />
|
||
Female, male</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>Accents on their own</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>’></code><br />
|
||
Circumflex (same as caret, <code>^</code>)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’!</code><br />
|
||
Grave (same as backtick, <code>‘</code>)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’,</code><br />
|
||
Cedilla</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’:</code><br />
|
||
Diaeresis (Umlaut)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>’m</code><br />
|
||
Macron</p>
|
||
</li>
|
||
<li>
|
||
<p><code>”</code><br />
|
||
Acute</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-insert_002dfiles"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>insert-files</code><br />
|
||
This function allows you type a file pattern, and see the results of
|
||
the expansion at each step. When you hit return, all expansions are
|
||
inserted into the command line.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey '^Xf' insert-files
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-insert_002dunicode_002dchar"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>insert-unicode-char</code><br />
|
||
When first executed, the user inputs a set of hexadecimal digits.
|
||
This is terminated with another call to <code>insert-unicode-char</code>. The
|
||
digits are then turned into the corresponding Unicode character. For
|
||
example, if the widget is bound to <code>^XU</code>, the character sequence
|
||
‘<code>^XU 4 c ^XU</code>’ inserts <code>L</code> (Unicode U+004c).</p>
|
||
<p>See <code>insert-composed-char</code> for a way of inserting characters using a
|
||
two-character mnemonic.</p>
|
||
<p><span id="index-narrow_002dto_002dregion"></span>
|
||
<span id="index-narrow_002dto_002dregion_002dinvisible"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>narrow-to-region </code>[ <code>-p</code> <code>pre</code> ] [ <code>-P</code> <code>post</code> ]<br />
|
||
<code> </code>[ <code>-S</code> <code>statepm</code> | <code>-R</code> <code>statepm</code> | [ <code>-l</code>
|
||
<code>lbufvar</code> ] [ <code>-r</code> <code>rbufvar</code> ] ]<br />
|
||
<code> </code>[ <code>-n</code> ] [ <code>start</code> <code>end</code> ]<br />
|
||
<code>narrow-to-region-invisible</code><br />
|
||
<code>predict-on</code><br />
|
||
This set of functions implements predictive typing using history
|
||
search. After <code>predict-on</code>, typing characters causes the editor to
|
||
look backward in the history for the first line beginning with what
|
||
you have typed so far. After <code>predict-off</code>, editing returns to
|
||
normal for the line found. In fact, you often don’t even need to use
|
||
<code>predict-off</code>, because if the line doesn’t match something in the
|
||
history, adding a key performs standard completion, and then inserts
|
||
itself if no completions were found. However, editing in the middle
|
||
of a line is liable to confuse prediction; see the <code>toggle</code> style
|
||
below.</p>
|
||
<p>With the function based completion system (which is needed for
|
||
this), you should be able to type <code>TAB</code> at almost any point to
|
||
advance the cursor to the next ‘‘interesting’’ character position
|
||
(usually the end of the current word, but sometimes somewhere in the
|
||
middle of the word). And of course as soon as the entire line is
|
||
what you want, you can accept with return, without needing to move
|
||
the cursor to the end first.</p>
|
||
<p>The first time <code>predict-on</code> is used, it creates several additional
|
||
widget functions:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>delete-backward-and-predict</code><br />
|
||
Replaces the <code>backward-delete-char</code> widget. You do not need to
|
||
bind this yourself.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>insert-and-predict</code><br />
|
||
Implements predictive typing by replacing the <code>self-insert</code>
|
||
widget. You do not need to bind this yourself.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>predict-off</code><br />
|
||
Turns off predictive typing.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Although you <code>autoload</code> only the <code>predict-on</code> function, it is
|
||
necessary to create a keybinding for <code>predict-off</code> as well.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N predict-on
|
||
zle -N predict-off
|
||
bindkey '^X^Z' predict-on
|
||
bindkey '^Z' predict-off
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-read_002dfrom_002dminibuffer"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>read-from-minibuffer</code><br />
|
||
This is most useful when called as a function from inside a widget,
|
||
but will work correctly as a widget in its own right. It prompts for
|
||
a value below the current command line; a value may be input using
|
||
all of the standard zle operations (and not merely the restricted
|
||
set available when executing, for example, <code>execute-named-cmd</code>). The
|
||
value is then returned to the calling function in the parameter
|
||
<code>$REPLY</code> and the editing buffer restored to its previous state. If
|
||
the read was aborted by a keyboard break (typically <code>^G</code>), the
|
||
function returns status 1 and <code>$REPLY</code> is not set.</p>
|
||
<p>If one argument is supplied to the function it is taken as a prompt,
|
||
otherwise ‘<code>? </code>’ is used. If two arguments are supplied, they are
|
||
the prompt and the initial value of <code>$LBUFFER</code>, and if a third
|
||
argument is given it is the initial value of <code>$RBUFFER</code>. This
|
||
provides a default value and starting cursor placement. Upon return
|
||
the entire buffer is the value of <code>$REPLY</code>.</p>
|
||
<p>One option is available: ‘<code>-k</code> <code>num</code>’ specifies that <code>num</code>
|
||
characters are to be read instead of a whole line. The line editor
|
||
is not invoked recursively in this case, so depending on the
|
||
terminal settings the input may not be visible, and only the input
|
||
keys are placed in <code>$REPLY</code>, not the entire buffer. Note that unlike
|
||
the <code>read</code> builtin <code>num</code> must be given; there is no default.</p>
|
||
<p>The name is a slight misnomer, as in fact the shell’s own minibuffer
|
||
is not used. Hence it is still possible to call <code>executed-named-cmd</code>
|
||
and similar functions while reading a value.</p>
|
||
<p><span id="index-replace_002dargument"></span>
|
||
<span id="index-replace_002dargument_002dedit"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>replace-argument</code>, <code>replace-argument-edit</code><br />
|
||
The function <code>replace-argument</code> can be used to replace a command
|
||
line argument in the current command line or, if the current command
|
||
line is empty, in the last command line executed (the new command
|
||
line is not executed). Arguments are as delimited by standard shell
|
||
syntax,</p>
|
||
<p>If a numeric argument is given, that specifies the argument to be
|
||
replaced. 0 means the command name, as in history expansion. A
|
||
negative numeric argument counts backward from the last word.</p>
|
||
<p>If no numeric argument is given, the current argument is replaced;
|
||
this is the last argument if the previous history line is being
|
||
used.</p>
|
||
<p>The function prompts for a replacement argument.</p>
|
||
<p>If the widget contains the string <code>edit</code>, for example is defined as</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N replace-argument-edit replace-argument
|
||
</code></pre>
|
||
</div>
|
||
<p>then the function presents the current value of the argument for
|
||
editing, otherwise the editing buffer for the replacement is
|
||
initially empty.</p>
|
||
<p><span id="index-replace_002dstring"></span>
|
||
<span id="index-replace_002dstring_002dagain"></span>
|
||
<span id="index-replace_002dpattern"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>replace-string</code>, <code>replace-pattern</code><br />
|
||
<code>replace-string-again</code>, <code>replace-pattern-again</code><br />
|
||
The function <code>replace-string</code> implements three widgets. If defined
|
||
under the same name as the function, it prompts for two strings; the
|
||
first (source) string will be replaced by the second everywhere it
|
||
occurs in the line editing buffer.</p>
|
||
<p>If the widget name contains the word ‘<code>pattern</code>’, for example by
|
||
defining the widget using the command ‘<code>zle -N replace-pattern replace-string</code>’, then the matching is performed using zsh patterns.
|
||
All zsh extended globbing patterns can be used in the source string;
|
||
note that unlike filename generation the pattern does not need to
|
||
match an entire word, nor do glob qualifiers have any effect. In
|
||
addition, the replacement string can contain parameter or command
|
||
substitutions. Furthermore, a ‘<code>&</code>’ in the replacement string will
|
||
be replaced with the matched source string, and a backquoted digit
|
||
‘<code>\``N</code>’ will be replaced by the <code>N</code>th parenthesised expression
|
||
matched. The form ‘<code>\{``N``}</code>’ may be used to protect the digit from
|
||
following digits.</p>
|
||
<p>If the widget instead contains the word ‘<code>regex</code>’ (or ‘<code>regexp</code>’),
|
||
then the matching is performed using regular expressions, respecting
|
||
the setting of the option <code>RE_MATCH_PCRE</code> (see the description of
|
||
the function <code>regexp-replace</code> below). The special replacement
|
||
facilities described above for pattern matching are available.</p>
|
||
<p>By default the previous source or replacement string will not be
|
||
offered for editing. However, this feature can be activated by
|
||
setting the style <code>edit-previous</code> in the context <code>:zle:``widget</code>
|
||
(for example, <code>:zle:replace-string</code>) to <code>true</code>. In addition, a
|
||
positive numeric argument forces the previous values to be offered,
|
||
a negative or zero argument forces them not to be.</p>
|
||
<p>The function <code>replace-string-again</code> can be used to repeat the
|
||
previous replacement; no prompting is done. As with
|
||
<code>replace-string</code>, if the name of the widget contains the word
|
||
‘<code>pattern</code>’ or ‘<code>regex</code>’, pattern or regular expression matching
|
||
is performed, else a literal string replacement. Note that the
|
||
previous source and replacement text are the same whether pattern,
|
||
regular expression or string matching is used.</p>
|
||
<p>In addition, <code>replace-string</code> shows the previous replacement above
|
||
the prompt, so long as there was one during the current session; if
|
||
the source string is empty, that replacement will be repeated
|
||
without the widget prompting for a replacement string.</p>
|
||
<p>For example, starting from the line:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print This line contains fan and fond
|
||
</code></pre>
|
||
</div>
|
||
<p>and invoking <code>replace-pattern</code> with the source string ‘<code>f(?)n</code>’ and
|
||
the replacement string ‘<code>c\1r</code>’ produces the not very useful line:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print This line contains car and cord
|
||
</code></pre>
|
||
</div>
|
||
<p>The range of the replacement string can be limited by using the
|
||
<code>narrow-to-region-invisible</code> widget. One limitation of the current
|
||
version is that <code>undo</code> will cycle through changes to the replacement
|
||
and source strings before undoing the replacement itself.</p>
|
||
<p><span id="index-send_002dinvisible"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>send-invisible</code><br />
|
||
This is similar to read-from-minibuffer in that it may be called as
|
||
a function from a widget or as a widget of its own, and
|
||
interactively reads input from the keyboard. However, the input
|
||
being typed is concealed and a string of asterisks (‘<code>*</code>’) is shown
|
||
instead. The value is saved in the parameter <code>$INVISIBLE</code> to which a
|
||
reference is inserted into the editing buffer at the restored cursor
|
||
position. If the read was aborted by a keyboard break (typically
|
||
<code>^G</code>) or another escape from editing such as <code>push-line</code>,
|
||
<code>$INVISIBLE</code> is set to empty and the original buffer is restored
|
||
unchanged.</p>
|
||
<p>If one argument is supplied to the function it is taken as a prompt,
|
||
otherwise ‘<code>Non-echoed text: </code>’ is used (as in emacs). If a second
|
||
and third argument are supplied they are used to begin and end the
|
||
reference to <code>$INVISIBLE</code> that is inserted into the buffer. The
|
||
default is to open with <code>${</code>, then <code>INVISIBLE</code>, and close with <code>}</code>,
|
||
but many other effects are possible.</p>
|
||
<p><span id="index-smart_002dinsert_002dlast_002dword"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>smart-insert-last-word</code><br />
|
||
This function may replace the <code>insert-last-word</code> widget, like so:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N insert-last-word smart-insert-last-word
|
||
</code></pre>
|
||
</div>
|
||
<p>With a numeric argument, or when passed command line arguments in a
|
||
call from another widget, it behaves like <code>insert-last-word</code>, except
|
||
that words in comments are ignored when <code>INTERACTIVE_COMMENTS</code> is
|
||
set.</p>
|
||
<p>Otherwise, the rightmost ‘‘interesting’’ word from the previous
|
||
command is found and inserted. The default definition of
|
||
‘‘interesting’’ is that the word contains at least one
|
||
alphabetic character, slash, or backslash. This definition may be
|
||
overridden by use of the <code>match</code> style. The context used to look up
|
||
the style is the widget name, so usually the context is
|
||
<code>:insert-last-word</code>. However, you can bind this function to
|
||
different widgets to use different patterns:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zle -N insert-last-assignment smart-insert-last-word
|
||
zstyle :insert-last-assignment match '[[:alpha:]][][[:alnum:]]#=*'
|
||
bindkey '\e=' insert-last-assignment
|
||
</code></pre>
|
||
</div>
|
||
<p>If no interesting word is found and the <code>auto-previous</code> style is set
|
||
to a true value, the search continues upward through the history.
|
||
When <code>auto-previous</code> is unset or false (the default), the widget
|
||
must be invoked repeatedly in order to search earlier history lines.</p>
|
||
<p><span id="index-transpose_002dlines"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>transpose-lines</code><br />
|
||
Only useful with a multi-line editing buffer; the lines here are
|
||
lines within the current on-screen buffer, not history lines. The
|
||
effect is similar to the function of the same name in Emacs.</p>
|
||
<p>Transpose the current line with the previous line and move the
|
||
cursor to the start of the next line. Repeating this (which can be
|
||
done by providing a positive numeric argument) has the effect of
|
||
moving the line above the cursor down by a number of lines.</p>
|
||
<p>With a negative numeric argument, requires two lines above the
|
||
cursor. These two lines are transposed and the cursor moved to the
|
||
start of the previous line. Using a numeric argument less than -1
|
||
has the effect of moving the line above the cursor up by minus that
|
||
number of lines.</p>
|
||
<p><span id="index-url_002dquote_002dmagic"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>url-quote-magic</code><br />
|
||
This widget replaces the built-in <code>self-insert</code> to make it easier to
|
||
type URLs as command line arguments. As you type, the input
|
||
character is analyzed and, if it may need quoting, the current word
|
||
is checked for a URI scheme. If one is found and the current word is
|
||
not already in quotes, a backslash is inserted before the input
|
||
character.</p>
|
||
<p>Styles to control quoting behavior:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>url-metas</code><br />
|
||
This style is looked up in the context
|
||
‘<code>:url-quote-magic:``scheme</code>’ (where <code>scheme</code> is that of the
|
||
current URL, e.g. "<code>ftp</code>"). The value is a string listing the
|
||
characters to be treated as globbing metacharacters when
|
||
appearing in a URL using that scheme. The default is to quote
|
||
all zsh extended globbing characters, excluding ’<code><</code>’ and ’<code>></code>’
|
||
but including braces (as in brace expansion). See also
|
||
<code>url-seps</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>url-seps</code><br />
|
||
Like <code>url-metas</code>, but lists characters that should be considered
|
||
command separators, redirections, history references, etc. The
|
||
default is to quote the standard set of shell separators,
|
||
excluding those that overlap with the extended globbing
|
||
characters, but including ’<code><</code>’ and ’<code>></code>’ and the first
|
||
character of <code>$histchars</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>url-globbers</code><br />
|
||
This style is looked up in the context ‘<code>:url-quote-magic</code>’. The
|
||
values form a list of command names that are expected to do
|
||
their own globbing on the URL string. This implies that they are
|
||
aliased to use the ‘<code>noglob</code>’ modifier. When the first word on
|
||
the line matches one of the values <em>and</em> the URL refers to a
|
||
local file (see <code>url-local-schema</code>), only the <code>url-seps</code>
|
||
characters are quoted; the <code>url-metas</code> are left alone, allowing
|
||
them to affect command-line parsing, completion, etc. The
|
||
default values are a literal ‘<code>noglob</code>’ plus (when the
|
||
<code>zsh/parameter</code> module is available) any commands aliased to the
|
||
helper function ‘<code>urlglobber</code>’ or its alias ‘<code>globurl</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>url-local-schema</code><br />
|
||
This style is always looked up in the context ‘<code>:urlglobber</code>’,
|
||
even though it is used by both url-quote-magic and urlglobber.
|
||
The values form a list of URI schema that should be treated as
|
||
referring to local files by their real local path names, as
|
||
opposed to files which are specified relative to a
|
||
web-server-defined document root. The defaults are "<code>ftp</code>" and
|
||
"<code>file</code>".</p>
|
||
</li>
|
||
<li>
|
||
<p><code>url-other-schema</code><br />
|
||
Like <code>url-local-schema</code>, but lists all other URI schema upon
|
||
which <code>urlglobber</code> and <code>url-quote-magic</code> should act. If the URI
|
||
on the command line does not have a scheme appearing either in
|
||
this list or in <code>url-local-schema</code>, it is not magically quoted.
|
||
The default values are "<code>http</code>", "<code>https</code>", and "<code>ftp</code>". When a
|
||
scheme appears both here and in <code>url-local-schema</code>, it is quoted
|
||
differently depending on whether the command name appears in
|
||
<code>url-globbers</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Loading <code>url-quote-magic</code> also defines a helper function
|
||
‘<code>urlglobber</code>’ and aliases ‘<code>globurl</code>’ to ‘<code>noglob urlglobber</code>’.
|
||
This function takes a local URL apart, attempts to pattern-match the
|
||
local file portion of the URL path, and then puts the results back
|
||
into URL format again.</p>
|
||
<p><span id="index-vi_002dpipe"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>vi-pipe</code><br />
|
||
This function reads a movement command from the keyboard and then
|
||
prompts for an external command. The part of the buffer covered by
|
||
the movement is piped to the external command and then replaced by
|
||
the command’s output. If the movement command is bound to vi-pipe,
|
||
the current line is used.</p>
|
||
<p>The function serves as an example for reading a vi movement command
|
||
from within a user-defined widget.</p>
|
||
<p><span id="index-which_002dcommand-1"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>which-command</code><br />
|
||
This function is a drop-in replacement for the builtin widget
|
||
<code>which-command</code>. It has enhanced behaviour, in that it correctly
|
||
detects whether or not the command word needs to be expanded as an
|
||
alias; if so, it continues tracing the command word from the
|
||
expanded alias until it reaches the command that will be executed.</p>
|
||
<p>The style <code>whence</code> is available in the context <code>:zle:$WIDGET</code>; this
|
||
may be set to an array to give the command and options that will be
|
||
used to investigate the command word found. The default is <code>whence -c</code>.</p>
|
||
<p><span id="index-zcalc_002dauto_002dinsert"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>zcalc-auto-insert</code><br />
|
||
This function is useful together with the <code>zcalc</code> function described
|
||
in <a href="#Mathematical-Functions">Mathematical Functions</a>. It should be
|
||
bound to a key representing a binary operator such as ‘<code>+</code>’, ‘<code>-</code>’,
|
||
‘<code>*</code>’ or ‘<code>/</code>’. When running in zcalc, if the key occurs at the
|
||
start of the line or immediately following an open parenthesis, the
|
||
text <code>"ans "</code> is inserted before the representation of the key
|
||
itself. This allows easy use of the answer from the previous
|
||
calculation in the current line. The text to be inserted before the
|
||
symbol typed can be modified by setting the variable
|
||
<code>ZCALC_AUTO_INSERT_PREFIX</code>.</p>
|
||
<p>Hence, for example, typing ‘<code>+12</code>’ followed by return adds 12 to the
|
||
previous result.</p>
|
||
<p>If zcalc is in RPN mode (<code>-r</code> option) the effect of this binding is
|
||
automatically suppressed as operators alone on a line are
|
||
meaningful.</p>
|
||
<p>When not in zcalc, the key simply inserts the symbol itself.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Utility-Functions"></span></p>
|
||
<h3 id="2672-utility-functions"><a class="header" href="#2672-utility-functions">26.7.2 Utility Functions</a></h3>
|
||
<p>These functions are useful in constructing widgets. They should be
|
||
loaded with ‘<code>autoload -U</code> <code>function</code>’ and called as indicated from
|
||
user-defined widgets.</p>
|
||
<p><span id="index-split_002dshell_002darguments"></span></p>
|
||
<p><code>split-shell-arguments</code></p>
|
||
<p>This function splits the line currently being edited into shell
|
||
arguments and whitespace. The result is stored in the array <code>reply</code>. The
|
||
array contains all the parts of the line in order, starting with any
|
||
whitespace before the first argument, and finishing with any whitespace
|
||
after the last argument. Hence (so long as the option <code>KSH_ARRAYS</code> is
|
||
not set) whitespace is given by odd indices in the array and arguments
|
||
by even indices. Note that no stripping of quotes is done; joining
|
||
together all the elements of <code>reply</code> in order is guaranteed to produce
|
||
the original line.</p>
|
||
<p>The parameter <code>REPLY</code> is set to the index of the word in <code>reply</code> which
|
||
contains the character after the cursor, where the first element has
|
||
index 1. The parameter <code>REPLY2</code> is set to the index of the character
|
||
under the cursor in that word, where the first character has index 1.</p>
|
||
<p>Hence <code>reply</code>, <code>REPLY</code> and <code>REPLY2</code> should all be made local to the
|
||
enclosing function.</p>
|
||
<p>See the function <code>modify-current-argument</code>, described below, for an
|
||
example of how to call this function.</p>
|
||
<p><span id="index-modify_002dcurrent_002dargument"></span></p>
|
||
<p><code>modify-current-argument</code> [ <code>expr-using-``$ARG</code> | <code>func</code> ]</p>
|
||
<p>This function provides a simple method of allowing user-defined widgets
|
||
to modify the command line argument under the cursor (or immediately to
|
||
the left of the cursor if the cursor is between arguments).</p>
|
||
<p>The argument can be an expression which when evaluated operates on the
|
||
shell parameter <code>ARG</code>, which will have been set to the command line
|
||
argument under the cursor. The expression should be suitably quoted to
|
||
prevent it being evaluated too early.</p>
|
||
<p>Alternatively, if the argument does not contain the string <code>ARG</code>, it is
|
||
assumed to be a shell function, to which the current command line
|
||
argument is passed as the only argument. The function should set the
|
||
variable <code>REPLY</code> to the new value for the command line argument. If the
|
||
function returns non-zero status, so does the calling function.</p>
|
||
<p>For example, a user-defined widget containing the following code
|
||
converts the characters in the argument under the cursor into all upper
|
||
case:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">modify-current-argument '${(U)ARG}'
|
||
</code></pre>
|
||
</div>
|
||
<p>The following strips any quoting from the current word (whether
|
||
backslashes or one of the styles of quotes), and replaces it with single
|
||
quoting throughout:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">modify-current-argument '${(qq)${(Q)ARG}}'
|
||
</code></pre>
|
||
</div>
|
||
<p>The following performs directory expansion on the command line argument
|
||
and replaces it by the absolute path:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">expand-dir() {
|
||
REPLY=${~1}
|
||
REPLY=${REPLY:a}
|
||
}
|
||
modify-current-argument expand-dir
|
||
</code></pre>
|
||
</div>
|
||
<p>In practice the function <code>expand-dir</code> would probably not be defined
|
||
within the widget where <code>modify-current-argument</code> is called.</p>
|
||
<hr />
|
||
<p><span id="Styles"></span></p>
|
||
<h3 id="2673-styles"><a class="header" href="#2673-styles">26.7.3 Styles</a></h3>
|
||
<p>The behavior of several of the above widgets can be controlled by the
|
||
use of the <code>zstyle</code> mechanism. In particular, widgets that interact with
|
||
the completion system pass along their context to any completions that
|
||
they invoke.</p>
|
||
<p><span id="index-break_002dkeys_002c-widget-style"></span></p>
|
||
<p><code>break-keys</code></p>
|
||
<p>This style is used by the <code>incremental-complete-word</code> widget. Its value
|
||
should be a pattern, and all keys matching this pattern will cause the
|
||
widget to stop incremental completion without the key having any further
|
||
effect. Like all styles used directly by <code>incremental-complete-word</code>,
|
||
this style is looked up using the context ‘<code>:incremental</code>’.</p>
|
||
<p><span id="index-completer_002c-completion-style-1"></span></p>
|
||
<p><code>completer</code></p>
|
||
<p>The <code>incremental-complete-word</code> and <code>insert-and-predict</code> widgets set up
|
||
their top-level context name before calling completion. This allows one
|
||
to define different sets of completer functions for normal completion
|
||
and for these widgets. For example, to use completion, approximation and
|
||
correction for normal completion, completion and correction for
|
||
incremental completion and only completion for prediction one could use:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':completion:*' completer \
|
||
_complete _correct _approximate
|
||
zstyle ':completion:incremental:*' completer \
|
||
_complete _correct
|
||
zstyle ':completion:predict:*' completer \
|
||
_complete
|
||
</code></pre>
|
||
</div>
|
||
<p>It is a good idea to restrict the completers used in prediction, because
|
||
they may be automatically invoked as you type. The <code>_list</code> and <code>_menu</code>
|
||
completers should never be used with prediction. The <code>_approximate</code>,
|
||
<code>_correct</code>, <code>_expand</code>, and <code>_match</code> completers may be used, but be aware
|
||
that they may change characters anywhere in the word behind the cursor,
|
||
so you need to watch carefully that the result is what you intended.</p>
|
||
<p><span id="index-cursor_002c-completion-style"></span></p>
|
||
<p><code>cursor</code></p>
|
||
<p>The <code>insert-and-predict</code> widget uses this style, in the context
|
||
‘<code>:predict</code>’, to decide where to place the cursor after completion has
|
||
been tried. Values are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>complete</code><br />
|
||
The cursor is left where it was when completion finished, but only
|
||
if it is after a character equal to the one just inserted by the
|
||
user. If it is after another character, this value is the same as
|
||
‘<code>key</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>key</code><br />
|
||
The cursor is left after the <code>n</code>th occurrence of the character just
|
||
inserted, where <code>n</code> is the number of times that character appeared
|
||
in the word before completion was attempted. In short, this has the
|
||
effect of leaving the cursor after the character just typed even if
|
||
the completion code found out that no other characters need to be
|
||
inserted at that position.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Any other value for this style unconditionally leaves the cursor at the
|
||
position where the completion code left it.</p>
|
||
<p><span id="index-list_002c-widget-style"></span></p>
|
||
<p><code>list</code></p>
|
||
<p>When using the <code>incremental-complete-word</code> widget, this style says if
|
||
the matches should be listed on every key press (if they fit on the
|
||
screen). Use the context prefix ‘<code>:completion:incremental</code>’.</p>
|
||
<p>The <code>insert-and-predict</code> widget uses this style to decide if the
|
||
completion should be shown even if there is only one possible
|
||
completion. This is done if the value of this style is the string
|
||
<code>always</code>. In this case the context is ‘<code>:predict</code>’ (<em>not</em>
|
||
‘<code>:completion:predict</code>’).</p>
|
||
<p><span id="index-match_002c-widget-style"></span></p>
|
||
<p><code>match</code></p>
|
||
<p>This style is used by <code>smart-insert-last-word</code> to provide a pattern
|
||
(using full <code>EXTENDED_GLOB</code> syntax) that matches an interesting word.
|
||
The context is the name of the widget to which <code>smart-insert-last-word</code>
|
||
is bound (see above). The default behavior of <code>smart-insert-last-word</code>
|
||
is equivalent to:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :insert-last-word match '*[[:alpha:]/\\]*'
|
||
</code></pre>
|
||
</div>
|
||
<p>However, you might want to include words that contain spaces:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'
|
||
</code></pre>
|
||
</div>
|
||
<p>Or include numbers as long as the word is at least two characters long:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'
|
||
</code></pre>
|
||
</div>
|
||
<p>The above example causes redirections like "2>" to be included.</p>
|
||
<p><span id="index-prompt_002c-widget-style"></span></p>
|
||
<p><code>prompt</code></p>
|
||
<p>The <code>incremental-complete-word</code> widget shows the value of this style in
|
||
the status line during incremental completion. The string value may
|
||
contain any of the following substrings in the manner of the <code>PS1</code> and
|
||
other prompt parameters:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%c</code><br />
|
||
Replaced by the name of the completer function that generated the
|
||
matches (without the leading underscore).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%l</code><br />
|
||
When the <code>list</code> style is set, replaced by ‘<code>...</code>’ if the list of
|
||
matches is too long to fit on the screen and with an empty string
|
||
otherwise. If the <code>list</code> style is ‘false’ or not set, ‘<code>%l</code>’ is
|
||
always removed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%n</code><br />
|
||
Replaced by the number of matches generated.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%s</code><br />
|
||
Replaced by ‘<code>-no match-</code>’, ‘<code>-no prefix-</code>’, or an empty string if
|
||
there is no completion matching the word on the line, if the matches
|
||
have no common prefix different from the word on the line, or if
|
||
there is such a common prefix, respectively.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%u</code><br />
|
||
Replaced by the unambiguous part of all matches, if there is any,
|
||
and if it is different from the word on the line.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Like ‘<code>break-keys</code>’, this uses the ‘<code>:incremental</code>’ context.</p>
|
||
<p><span id="index-stop_002dkeys_002c-widget-style"></span></p>
|
||
<p><code>stop-keys</code></p>
|
||
<p>This style is used by the <code>incremental-complete-word</code> widget. Its value
|
||
is treated similarly to the one for the <code>break-keys</code> style (and uses the
|
||
same context: ‘<code>:incremental</code>’). However, in this case all keys matching
|
||
the pattern given as its value will stop incremental completion and will
|
||
then execute their usual function.</p>
|
||
<p><span id="index-toggle_002c-widget-style"></span></p>
|
||
<p><code>toggle</code></p>
|
||
<p>This boolean style is used by <code>predict-on</code> and its related widgets in
|
||
the context ‘<code>:predict</code>’. If set to one of the standard ‘true’ values,
|
||
predictive typing is automatically toggled off in situations where it is
|
||
unlikely to be useful, such as when editing a multi-line buffer or after
|
||
moving into the middle of a line and then deleting a character. The
|
||
default is to leave prediction turned on until an explicit call to
|
||
<code>predict-off</code>.</p>
|
||
<p><span id="index-verbose_002c-widget-style"></span></p>
|
||
<p><code>verbose</code></p>
|
||
<p>This boolean style is used by <code>predict-on</code> and its related widgets in
|
||
the context ‘<code>:predict</code>’. If set to one of the standard ‘true’ values,
|
||
these widgets display a message below the prompt when the predictive
|
||
state is toggled. This is most useful in combination with the <code>toggle</code>
|
||
style. The default does not display these messages.</p>
|
||
<p><span id="index-widget_002c-widget-style"></span></p>
|
||
<p><code>widget</code></p>
|
||
<p>This style is similar to the <code>command</code> style: For widget functions that
|
||
use <code>zle</code> to call other widgets, this style can sometimes be used to
|
||
override the widget which is called. The context for this style is the
|
||
name of the calling widget (<em>not</em> the name of the calling function,
|
||
because one function may be bound to multiple widget names).</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle :copy-earlier-word widget smart-insert-last-word
|
||
</code></pre>
|
||
</div>
|
||
<p>Check the documentation for the calling widget or function to determine
|
||
whether the <code>widget</code> style is used.</p>
|
||
<hr />
|
||
<p><span id="Exception-Handling"></span>
|
||
<span id="Exception-Handling-1"></span></p>
|
||
<h2 id="268-exception-handling"><a class="header" href="#268-exception-handling">26.8 Exception Handling</a></h2>
|
||
<p>Two functions are provided to enable zsh to provide exception handling
|
||
in a form that should be familiar from other languages.</p>
|
||
<p><span id="index-throw"></span></p>
|
||
<p><code>throw</code> <code>exception</code></p>
|
||
<p>The function <code>throw</code> throws the named <code>exception</code>. The name is an
|
||
arbitrary string and is only used by the <code>throw</code> and <code>catch</code> functions.
|
||
An exception is for the most part treated the same as a shell error,
|
||
i.e. an unhandled exception will cause the shell to abort all processing
|
||
in a function or script and to return to the top level in an interactive
|
||
shell.</p>
|
||
<p><code>catch</code> <code>exception-pattern</code></p>
|
||
<p>The function <code>catch</code> returns status zero if an exception was thrown and
|
||
the pattern <code>exception-pattern</code> matches its name. Otherwise it returns
|
||
status 1. <code>exception-pattern</code> is a standard shell pattern, respecting
|
||
the current setting of the <code>EXTENDED_GLOB</code> option. An alias <code>catch</code> is
|
||
also defined to prevent the argument to the function from matching
|
||
filenames, so patterns may be used unquoted. Note that as exceptions are
|
||
not fundamentally different from other shell errors it is possible to
|
||
catch shell errors by using an empty string as the exception name. The
|
||
shell variable <code>CAUGHT</code> is set by <code>catch</code> to the name of the exception
|
||
caught. It is possible to rethrow an exception by calling the <code>throw</code>
|
||
function again once an exception has been caught.
|
||
<span id="index-catch"></span></p>
|
||
<p>The functions are designed to be used together with the <code>always</code>
|
||
construct described in <a href="Shell-Grammar.html#Complex-Commands">Complex
|
||
Commands</a>. This is important as
|
||
only this construct provides the required support for exceptions. A
|
||
typical example is as follows.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">{
|
||
# "try" block
|
||
# ... nested code here calls "throw MyExcept"
|
||
} always {
|
||
# "always" block
|
||
if catch MyExcept; then
|
||
print "Caught exception MyExcept"
|
||
elif catch ''; then
|
||
print "Caught a shell error. Propagating..."
|
||
throw ''
|
||
fi
|
||
# Other exceptions are not handled but may be caught further
|
||
# up the call stack.
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>If all exceptions should be caught, the following idiom might be
|
||
preferable.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">{
|
||
# ... nested code here throws an exception
|
||
} always {
|
||
if catch *; then
|
||
case $CAUGHT in
|
||
(MyExcept)
|
||
print "Caught my own exception"
|
||
;;
|
||
(*)
|
||
print "Caught some other exception"
|
||
;;
|
||
esac
|
||
fi
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>In common with exception handling in other languages, the exception may
|
||
be thrown by code deeply nested inside the ‘try’ block. However, note
|
||
that it must be thrown inside the current shell, not in a subshell
|
||
forked for a pipeline, parenthesised current-shell construct, or some
|
||
form of command or process substitution.</p>
|
||
<p>The system internally uses the shell variable <code>EXCEPTION</code> to record the
|
||
name of the exception between throwing and catching. One drawback of
|
||
this scheme is that if the exception is not handled the variable
|
||
<code>EXCEPTION</code> remains set and may be incorrectly recognised as the name of
|
||
an exception if a shell error subsequently occurs. Adding <code>unset EXCEPTION</code> at the start of the outermost layer of any code that uses
|
||
exception handling will eliminate this problem.</p>
|
||
<hr />
|
||
<p><span id="MIME-Functions"></span> <span id="MIME-Functions-1"></span></p>
|
||
<h2 id="269-mime-functions"><a class="header" href="#269-mime-functions">26.9 MIME Functions</a></h2>
|
||
<p>Three functions are available to provide handling of files recognised by
|
||
extension, for example to dispatch a file <code>text.ps</code> when executed as a
|
||
command to an appropriate viewer.</p>
|
||
<p><span id="index-zsh_002dmime_002dsetup"></span>
|
||
<span id="index-zsh_002dmime_002dhandler"></span></p>
|
||
<p><code>zsh-mime-setup</code> [ <code>-fv</code> ] [ <code>-l</code> [ <code>suffix</code> ... ] ]</p>
|
||
<p><code>zsh-mime-handler</code> [ <code>-l</code> ] <code>command argument</code> ...</p>
|
||
<p>These two functions use the files <code>~/.mime.types</code> and <code>/etc/mime.types</code>,
|
||
which associate types and extensions, as well as <code>~/.mailcap</code> and
|
||
<code>/etc/mailcap</code> files, which associate types and the programs that handle
|
||
them. These are provided on many systems with the Multimedia Internet
|
||
Mail Extensions.</p>
|
||
<p>To enable the system, the function <code>zsh-mime-setup</code> should be autoloaded
|
||
and run. This allows files with extensions to be treated The function
|
||
<code>zsh-mime-handler</code> should not need to be called by the user.</p>
|
||
<p>The system works by setting up suffix aliases with ‘<code>alias -s</code>’. Suffix
|
||
aliases already installed by the user will not be overwritten.</p>
|
||
<p>For suffixes defined in lower case, upper case variants will also
|
||
automatically be handled (e.g. <code>PDF</code> is automatically handled if
|
||
handling for the suffix <code>pdf</code> is defined), but not vice versa.</p>
|
||
<p>Repeated calls to <code>zsh-mime-setup</code> do not override the existing is
|
||
given. Note, however, that this does not override existing suffix
|
||
aliases assigned to handlers other than <code>zsh-mime-handler</code>.</p>
|
||
<p>Calling <code>zsh-mime-setup</code> with the option <code>-l</code> lists the existing
|
||
mappings without altering them. Suffixes to list (which may contain
|
||
pattern characters that should be quoted from immediate interpretation
|
||
on the command line) may be given as additional arguments, otherwise all
|
||
suffixes are listed.</p>
|
||
<p>Calling <code>zsh-mime-setup</code> with the option <code>-v</code> causes verbose output to
|
||
be shown during the setup operation.</p>
|
||
<p>The system respects the <code>mailcap</code> flags <code>needsterminal</code> and
|
||
<code>copiousoutput</code>, see man page mailcap(4).</p>
|
||
<p>The functions use the following styles, which are defined with the
|
||
<code>zstyle</code> builtin command (<a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil
|
||
Module</a>). They should be
|
||
defined before <code>zsh-mime-setup</code> is run. The contexts used all start with
|
||
<code>:mime:</code>, with additional components in some cases. It is recommended
|
||
that a trailing <code>*</code> (suitably quoted) be appended to style patterns in
|
||
case the system is extended in future. Some examples are given below.</p>
|
||
<p>For files that have multiple suffixes, e.g. <code>.pdf.gz</code>, where the context
|
||
includes the suffix it will be looked up starting with the longest
|
||
possible suffix until a match for the style is found. For example, if
|
||
<code>.pdf.gz</code> produces a match for the handler, that will be used; otherwise
|
||
the handler for <code>.gz</code> will be used. Note that, owing to the way suffix
|
||
aliases work, it is always required that there be a handler for the
|
||
shortest possible suffix, so in this example <code>.pdf.gz</code> can only be
|
||
handled if <code>.gz</code> is also handled (though not necessarily in the same
|
||
way). Alternatively, if no handling for <code>.gz</code> on its own is needed,
|
||
simply adding the command</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">alias -s gz=zsh-mime-handler
|
||
</code></pre>
|
||
</div>
|
||
<p>to the initialisation code is sufficient; <code>.gz</code> will not be handled on
|
||
its own, but may be in combination with other suffixes.</p>
|
||
<p><span id="index-current_002dshell_002c-MIME-style"></span></p>
|
||
<p><code>current-shell</code></p>
|
||
<p>If this boolean style is true, the mailcap handler for the context in
|
||
question is run using the <code>eval</code> builtin instead of by starting a new
|
||
<code>sh</code> process. This is more efficient, but may not work in the occasional
|
||
cases where the mailcap handler uses strict POSIX syntax.</p>
|
||
<p><span id="index-disown_002c-MIME-style"></span></p>
|
||
<p><code>disown</code></p>
|
||
<p>If this boolean style is true, mailcap handlers started in the
|
||
background will be disowned, i.e. not subject to job control within the
|
||
parent shell. Such handlers nearly always produce their own windows, so
|
||
the only likely harmful side effect of setting the style is that it
|
||
becomes harder to kill jobs from within the shell.</p>
|
||
<p><span id="index-execute_002das_002dis_002c-MIME-style"></span></p>
|
||
<p><code>execute-as-is</code></p>
|
||
<p>This style gives a list of patterns to be matched against files passed
|
||
for execution with a handler program. If the file matches the pattern,
|
||
the entire command line is executed in its current form, with no
|
||
handler. This is useful for files which might have suffixes is not set,
|
||
the pattern <code>*(*) *(/)</code> is used; handler, and the option <code>AUTO_CD</code> may
|
||
be used to change to directories that happen to have MIME suffixes.</p>
|
||
<p><span id="index-execute_002dnever_002c-MIME-style"></span></p>
|
||
<p><code>execute-never</code></p>
|
||
<p>This style is useful in combination with <code>execute-as-is</code>. It is set to
|
||
an array of patterns corresponding to full paths to files that the MIME
|
||
handler matches <code>execute-as-is</code>. This is useful for file from another
|
||
operating system. For example, if <code>/mnt/windows</code> is a Windows mount,
|
||
then</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':mime:*' execute-never '/mnt/windows/*'
|
||
</code></pre>
|
||
</div>
|
||
<p>will ensure that any files found in that area will be executed as MIME
|
||
file name is matched against the pattern, regardless of how the file was
|
||
passed to the handler. The file is resolved to a full path using the
|
||
<code>:P</code> modifier described in <a href="Expansion.html#Modifiers">Modifiers</a>; this
|
||
means that symbolic links are resolved where possible, so that links
|
||
into other file systems behave in the correct fashion.</p>
|
||
<p><span id="index-file_002dpath_002c-MIME-style"></span></p>
|
||
<p><code>file-path</code></p>
|
||
<p>Used if the style <code>find-file-in-path</code> is true for the same context. Set
|
||
to an array of directories that are used for searching for the file to
|
||
be handled; the default is the command path given by the special
|
||
parameter <code>path</code>. The shell option <code>PATH_DIRS</code> is respected; if that is
|
||
set, the appropriate path will be searched even if the name of the file
|
||
to be handled as it appears on the command line contains a ‘<code>/</code>’. The
|
||
full context is <code>:mime:.``suffix``:</code>, as described for the style
|
||
<code>handler</code>.</p>
|
||
<p><span id="index-find_002dfile_002din_002dpath_002c-MIME-style"></span></p>
|
||
<p><code>find-file-in-path</code></p>
|
||
<p>If set, allows files whose names do not contain absolute paths to be
|
||
searched for in the command path or the path specified by the
|
||
<code>file-path</code> style. If the file is not found in the path, it is looked
|
||
for locally (whether or not the current directory is in the path); if it
|
||
is not found locally, the handler will abort unless the
|
||
<code>handle-nonexistent</code> style is set. Files found in the path are tested as
|
||
described for the style <code>execute-as-is</code>. The full context is
|
||
<code>:mime:.``suffix``:</code>, as described for the style <code>handler</code>.</p>
|
||
<p><span id="index-flags_002c-MIME-style"></span></p>
|
||
<p><code>flags</code></p>
|
||
<p>Defines flags to go with a handler; the context is as for the <code>handler</code>
|
||
style, and the format is as for the flags in <code>mailcap</code>.</p>
|
||
<p><span id="index-handle_002dnonexistent_002c-MIME-style"></span></p>
|
||
<p><code>handle-nonexistent</code></p>
|
||
<p>By default, arguments that don’t correspond to files are not passed to
|
||
the MIME handler in order to prevent it from intercepting commands found
|
||
in the path that happen to have suffixes. This style may be set to an
|
||
array of extended glob patterns for arguments that will be passed to the
|
||
handler even if they don’t exist. If it is not explicitly set it
|
||
defaults to <code>[[:alpha:]]#:/*</code> which allows URLs to be passed to the MIME
|
||
handler even though they don’t exist in that format in the file system.
|
||
The full context is <code>:mime:.``suffix``:</code>, as described for the style
|
||
<code>handler</code>.</p>
|
||
<p><span id="index-handler_002c-MIME-style"></span></p>
|
||
<p><code>handler</code></p>
|
||
<p>Specifies a handler for a suffix; the suffix is given by the context as
|
||
<code>:mime:.``suffix``:</code>, and the format of the handler is exactly that in
|
||
<code>mailcap</code>. Note in particular the ‘<code>.</code>’ and trailing colon to
|
||
distinguish this use of the context. This overrides any handler
|
||
specified by the <code>mailcap</code> files. If the handler requires a terminal,
|
||
the <code>flags</code> style should be set to include the word <code>needsterminal</code>, or
|
||
if the output is to be displayed through a pager (but not if the handler
|
||
is itself a pager), it should include <code>copiousoutput</code>.</p>
|
||
<p><span id="index-mailcap_002c-MIME-style"></span></p>
|
||
<p><code>mailcap</code></p>
|
||
<p>A list of files in the format of <code>~/.mailcap</code> and <code>/etc/mailcap</code> to be
|
||
read during setup, replacing the default list which consists of those
|
||
two files. The context is <code>:mime:</code>. A <code>+</code> in the list will be replaced
|
||
by the default files.</p>
|
||
<p><span id="index-mailcap_002dpriorities_002c-MIME-style"></span></p>
|
||
<p><code>mailcap-priorities</code></p>
|
||
<p>This style is used to resolve multiple mailcap entries for the same MIME
|
||
type. It consists of an array of the following elements, in descending
|
||
order of priority; later entries will be used if earlier entries are
|
||
unable to resolve the entries being compared. If none of the tests
|
||
resolve the entries, the first entry encountered is retained.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>files</code><br />
|
||
The order of files (entries in the <code>mailcap</code> style) read. Earlier
|
||
files are preferred. (Note this does not resolve entries in the same
|
||
file.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>priority</code><br />
|
||
The priority flag from the mailcap entry. The priority is an integer
|
||
from 0 to 9 with the default value being 5.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>flags</code><br />
|
||
The test given by the <code>mailcap-prio-flags</code> option is used to resolve
|
||
entries.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>place</code><br />
|
||
Later entries are preferred; as the entries are strictly ordered,
|
||
this test always succeeds.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Note that as this style is handled during initialisation, the context is
|
||
always <code>:mime:</code>, with no discrimination by suffix.</p>
|
||
<p><span id="index-mailcap_002dprio_002dflags_002c-MIME-style"></span></p>
|
||
<p><code>mailcap-prio-flags</code></p>
|
||
<p>This style is used when the keyword <code>flags</code> is encountered in the list
|
||
of tests specified by the <code>mailcap-priorities</code> style. It should be set
|
||
to a list of patterns, each of which is tested against the flags
|
||
specified in the mailcap entry (in other words, the sets of assignments
|
||
found with some entries in the mailcap file). Earlier patterns in the
|
||
list are preferred to later ones, and matched patterns are preferred to
|
||
unmatched ones.</p>
|
||
<p><span id="index-mime_002dtypes_002c-MIME-style"></span></p>
|
||
<p><code>mime-types</code></p>
|
||
<p>A list of files in the format of <code>~/.mime.types</code> and <code>/etc/mime.types</code>
|
||
to be read during setup, replacing the default list which consists of
|
||
those two files. The context is <code>:mime:</code>. A <code>+</code> in the list will be
|
||
replaced by the default files.</p>
|
||
<p><span id="index-never_002dbackground_002c-MIME-style"></span></p>
|
||
<p><code>never-background</code></p>
|
||
<p>If this boolean style is set, the handler for the given context is
|
||
always run in the foreground, even if the flags provided in the mailcap
|
||
entry suggest it need not be (for example, it doesn’t require a
|
||
terminal).</p>
|
||
<p><span id="index-pager_002c-MIME-style"></span></p>
|
||
<p><code>pager</code></p>
|
||
<p>If set, will be used instead of <code>$PAGER</code> or <code>more</code> to handle suffixes
|
||
where the <code>copiousoutput</code> flag is set. The context is as for <code>handler</code>,
|
||
i.e. <code>:mime:.``suffix``:</code> for handling a file with the given <code>suffix</code>.</p>
|
||
<p>Examples:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':mime:*' mailcap ~/.mailcap /usr/local/etc/mailcap
|
||
zstyle ':mime:.txt:' handler less %s
|
||
zstyle ':mime:.txt:' flags needsterminal
|
||
</code></pre>
|
||
</div>
|
||
<p>When <code>zsh-mime-setup</code> is subsequently run, it will look for <code>mailcap</code>
|
||
entries in the two files given. Files of suffix <code>.txt</code> will be handled
|
||
by running ‘<code>less</code> <code>file.txt</code>’. The flag <code>needsterminal</code> is set to show
|
||
that this program must run attached to a terminal.</p>
|
||
<p>As there are several steps to dispatching a command, the following
|
||
should be checked if attempting to execute a file by extension <code>.``ext</code>
|
||
does not have the expected effect.</p>
|
||
<p>The command ‘<code>alias -s</code> <code>ext</code>’ should show ‘<code>ps=zsh-mime-handler</code>’. If
|
||
it shows something else, another suffix alias was already installed and
|
||
was not overwritten. If it shows nothing, no handler was installed: this
|
||
is most likely because no handler was found in the <code>.mime.types</code> and
|
||
<code>mailcap</code> combination for <code>.ext</code> files. In that case, appropriate
|
||
handling should be added to <code>~/.mime.types</code> and <code>mailcap</code>.</p>
|
||
<p>If the extension is handled by <code>zsh-mime-handler</code> but the file is not
|
||
opened correctly, either the handler defined for the type is incorrect,
|
||
or the flags associated with it are in appropriate. Running
|
||
<code>zsh-mime-setup -l</code> will show the handler and, if there are any, the
|
||
flags. A <code>%s</code> in the handler is replaced by the file (suitably quoted if
|
||
necessary). Check that the handler program listed lists and can be run
|
||
in the way shown. Also check that the flags <code>needsterminal</code> or
|
||
<code>copiousoutput</code> are set if the handler needs to be run under a terminal;
|
||
the second flag is used if the output should be sent to a pager.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">text/html; /usr/bin/lynx '%s'; needsterminal
|
||
</code></pre>
|
||
</div>
|
||
<p>Running ‘<code>zsh-mime-handler -l</code> <code>command line</code>’ prints the command line
|
||
that would be executed, simplified to remove the effect of any flags,
|
||
and quoted so that the output can be run as a complete zsh command line.
|
||
This is used by the completion system to decide how to complete after a
|
||
file handled by <code>zsh-mime-setup</code>.</p>
|
||
<p><span id="index-pick_002dweb_002dbrowser"></span></p>
|
||
<p><code>pick-web-browser</code></p>
|
||
<p>This function is separate from the two MIME functions described above
|
||
and can be assigned directly to a suffix:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U pick-web-browser
|
||
alias -s html=pick-web-browser
|
||
</code></pre>
|
||
</div>
|
||
<p>It is provided as an intelligent front end to dispatch a web browser. It
|
||
may be run as either a function or a shell script. The status 255 is
|
||
returned if no browser could be started.</p>
|
||
<p>Various styles are available to customize the choice of browsers:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>browser-style</code><br />
|
||
The value of the style is an array giving preferences in decreasing
|
||
order for the type of browser to use. The values of elements may be</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>running</code><br />
|
||
Use a GUI browser that is already running when an X Window
|
||
display is available. The browsers listed in the <code>x-browsers</code>
|
||
style are tried in order until one is found; if it is, the file
|
||
will be displayed in that browser, so the user may need to check
|
||
whether it has appeared. If no running browser is found, one is
|
||
not started. Browsers other than Firefox, Opera and Konqueror
|
||
are assumed to understand the Mozilla syntax for opening a URL
|
||
remotely.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x</code><br />
|
||
Start a new GUI browser when an X Window display is available.
|
||
Search for the availability of one of the browsers listed in the
|
||
<code>x-browsers</code> style and start the first one that is found. No
|
||
check is made for an already running browser.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>tty</code><br />
|
||
Start a terminal-based browser. Search for the availability of
|
||
one of the browsers listed in the <code>tty-browsers</code> style and start
|
||
the first one that is found.</p>
|
||
</li>
|
||
</ul>
|
||
<p>If the style is not set the default <code>running x tty</code> is used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x-browsers</code><br />
|
||
An array in decreasing order of preference of browsers to use when
|
||
running under the X Window System. The array consists of the command
|
||
name under which to start the browser. They are looked up in the
|
||
context <code>:mime:</code> (which may be extended in future, so appending
|
||
‘<code>*</code>’ is recommended). For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':mime:*' x-browsers opera konqueror firefox
|
||
</code></pre>
|
||
</div>
|
||
<p>specifies that <code>pick-web-browser</code> should first look for a running
|
||
instance of Opera, Konqueror or Firefox, in that order, and if it
|
||
fails to find any should attempt to start Opera. The default is
|
||
<code>firefox mozilla netscape opera konqueror</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>tty-browsers</code><br />
|
||
An array similar to <code>x-browsers</code>, except that it gives browsers to
|
||
use when no X Window display is available. The default is <code>elinks links lynx</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>command</code><br />
|
||
If it is set this style is used to pick the command used to open a
|
||
page for a browser. The context is <code>:mime:browser:new:$browser:</code> to
|
||
start a new browser or <code>:mime:browser:running:$browser:</code> to open a
|
||
URL in a browser already running on the current X display, where
|
||
<code>$browser</code> is the value matched in the <code>x-browsers</code> or
|
||
<code>tty-browsers</code> style. The escape sequence <code>%b</code> in the style’s value
|
||
will be replaced by the browser, while <code>%u</code> will be replaced by the
|
||
URL. If the style is not set, the default for all new instances is
|
||
equivalent to <code>%b %u</code> and the defaults for using running browsers
|
||
are equivalent to the values <code>kfmclient openURL %u</code> for Konqueror,
|
||
<code>firefox -new-tab %u</code> for Firefox, <code>opera -newpage %u</code> for Opera,
|
||
and <code>%b -remote "openUrl(%u)"</code> for all others.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Mathematical-Functions"></span>
|
||
<span id="Mathematical-Functions-1"></span></p>
|
||
<h2 id="2610-mathematical-functions"><a class="header" href="#2610-mathematical-functions">26.10 Mathematical Functions</a></h2>
|
||
<p><span id="index-zcalc"></span></p>
|
||
<p><code>zcalc</code> [ <code>-erf</code> ] [ <code>expression</code> ... ]</p>
|
||
<p>A reasonably powerful calculator based on zsh’s arithmetic evaluation
|
||
facility. The syntax is similar to that of formulae in most programming
|
||
languages; see <a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a> for
|
||
details.</p>
|
||
<p>Non-programmers should note that, as in many other programming
|
||
languages, expressions involving only integers (whether constants
|
||
without a ‘<code>.</code>’, variables containing such constants as strings, or
|
||
variables declared to be integers) are by default evaluated using
|
||
integer arithmetic, which is not how an ordinary desk calculator
|
||
operates. To force floating point operation, pass the option <code>-f</code>; see
|
||
further notes below.</p>
|
||
<p>If the file <code>~/.zcalcrc</code> exists it will be sourced inside the function
|
||
once it is set up and about to process the command line. This can be
|
||
used, for example, to set shell options; <code>emulate -L zsh</code> and <code>setopt extendedglob</code> are in effect at this point. Any failure to source the
|
||
file if it exists is treated as fatal. As with other initialisation
|
||
files, the directory <code>$ZDOTDIR</code> is used instead of <code>$HOME</code> if it is set.</p>
|
||
<p>The mathematical library <code>zsh/mathfunc</code> will be loaded if it is
|
||
available; see <a href="Zsh-Modules.html#The-zsh_002fmathfunc-Module">The zsh/mathfunc
|
||
Module</a>. The mathematical
|
||
functions correspond to the raw system libraries, so trigonometric
|
||
functions are evaluated using radians, and so on.</p>
|
||
<p>Each line typed is evaluated as an expression. The prompt shows a
|
||
number, which corresponds to a positional parameter where the result of
|
||
that calculation is stored. For example, the result of the calculation
|
||
on the line preceded by ‘<code>4> </code>’ is available as <code>$4</code>. The last value
|
||
calculated is available as <code>ans</code>. Full command line editing, including
|
||
the history of previous calculations, is available; the history is saved
|
||
in the file <code>~/.zcalc_history</code>. To exit, enter a blank line or type
|
||
‘<code>:q</code>’ on its own (‘<code>q</code>’ is allowed for historical compatibility).</p>
|
||
<p>A line ending with a single backslash is treated in the same fashion as
|
||
it is in command line editing: the backslash is removed, the function
|
||
prompts for more input (the prompt is preceded by ‘<code>...</code>’ to indicate
|
||
this), and the lines are combined into one to get the final result. In
|
||
addition, if the input so far contains more open than close parentheses
|
||
<code>zcalc</code> will prompt for more input.</p>
|
||
<p>If arguments are given to <code>zcalc</code> on start up, they are used to prime
|
||
the first few positional parameters. A visual indication of this is
|
||
given when the calculator starts.</p>
|
||
<p>The constants <code>PI</code> (3.14159...) and <code>E</code> (2.71828...) are provided.
|
||
Parameter assignment is possible, but note that all parameters will be
|
||
put into the global namespace unless the <code>:local</code> special command is
|
||
used. The function creates local variables whose names start with <code>_</code>,
|
||
so users should avoid doing so. The variables <code>ans</code> (the last answer)
|
||
and <code>stack</code> (the stack in RPN mode) may be referred to directly; <code>stack</code>
|
||
is an array but elements of it are numeric. Various other special
|
||
variables are used locally with their standard meaning, for example
|
||
<code>compcontext</code>, <code>match</code>, <code>mbegin</code>, <code>mend</code>, <code>psvar</code>.</p>
|
||
<p>The output base can be initialised by passing the option ‘<code>-#``base</code>’,
|
||
for example ‘<code>zcalc -#16</code>’ (the ‘<code>#</code>’ may have to be quoted, depending
|
||
on the globbing options set).</p>
|
||
<p>If the option ‘<code>-e</code>’ is set, the function runs non-interactively: the
|
||
arguments are treated as expressions to be evaluated as if entered
|
||
interactively line by line.</p>
|
||
<p>If the option ‘<code>-f</code>’ is set, all numbers are treated as floating point,
|
||
hence for example the expression ‘<code>3/4</code>’ evaluates to 0.75 rather than</p>
|
||
<ol start="0">
|
||
<li>Options must appear in separate words.</li>
|
||
</ol>
|
||
<p>If the option ‘<code>-r</code>’ is set, RPN (Reverse Polish Notation) mode is
|
||
entered. This has various additional properties:</p>
|
||
<ul>
|
||
<li>
|
||
<p>Stack<br />
|
||
Evaluated values are maintained in a stack; this is contained in an
|
||
array named <code>stack</code> with the most recent value in <code>${stack[1]}</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Operators and functions<br />
|
||
If the line entered matches an operator (<code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>**</code>,
|
||
<code>^</code>, <code>|</code> or <code>&</code>) or a function supplied by the <code>zsh/mathfunc</code>
|
||
library, the bottom element or elements of the stack are popped to
|
||
use as the argument or arguments. The higher elements of stack
|
||
(least recent) are used as earlier arguments. The result is then
|
||
pushed into <code>${stack[1]}</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Expressions<br />
|
||
Other expressions are evaluated normally, printed, and added to the
|
||
stack as numeric values. The syntax within expressions on a single
|
||
line is normal shell arithmetic (not RPN).</p>
|
||
</li>
|
||
<li>
|
||
<p>Stack listing<br />
|
||
If an integer follows the option <code>-r</code> with no space, then on every
|
||
evaluation that many elements of the stack, where available, are
|
||
printed instead of just the most recent result. Hence, for example,
|
||
<code>zcalc -r4</code> shows <code>$stack[4]</code> to <code>$stack[1]</code> each time results are
|
||
printed.</p>
|
||
</li>
|
||
<li>
|
||
<p>Duplication: <code>=</code><br />
|
||
The pseudo-operator <code>=</code> causes the most recent element of the stack
|
||
to be duplicated onto the stack.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pop</code><br />
|
||
The pseudo-function <code>pop</code> causes the most recent element of the
|
||
stack to be popped. A ‘<code>></code>’ on its own has the same effect.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>>``ident</code><br />
|
||
The expression <code>></code> followed (with no space) by a shell identifier
|
||
causes the most recent element of the stack to be popped and
|
||
assigned to the variable with that name. The variable is local to
|
||
the <code>zcalc</code> function.</p>
|
||
</li>
|
||
<li>
|
||
<p><code><``ident</code><br />
|
||
The expression <code><</code> followed (with no space) by a shell identifier
|
||
causes the value of the variable with that name to be pushed onto
|
||
the stack. <code>ident</code> may be an integer, in which case the previous
|
||
result with that number (as shown before the <code>></code> in the standard
|
||
<code>zcalc</code> prompt) is put on the stack.</p>
|
||
</li>
|
||
<li>
|
||
<p>Exchange: <code>xy</code><br />
|
||
The pseudo-function <code>xy</code> causes the most recent two elements of the
|
||
stack to be exchanged. ‘<code><></code>’ has the same effect.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The prompt is configurable via the parameter <code>ZCALCPROMPT</code>, which
|
||
undergoes standard prompt expansion. The index of the current entry is
|
||
stored locally in the first element of the array <code>psvar</code>, which can be
|
||
referred to in <code>ZCALCPROMPT</code> as ‘<code>%1v</code>’. The default prompt is ‘<code>%1v>
|
||
</code>’.</p>
|
||
<p>The variable <code>ZCALC_ACTIVE</code> is set within the function and can be tested
|
||
by nested functions; it has the value <code>rpn</code> if RPN mode is active, else</p>
|
||
<ol>
|
||
<li></li>
|
||
</ol>
|
||
<p>A few special commands are available; these are introduced by a colon.
|
||
For backward compatibility, the colon may be omitted for certain
|
||
commands. Completion is available if <code>compinit</code> has been run.</p>
|
||
<p>The output precision may be specified within zcalc by special commands
|
||
familiar from many calculators.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>:norm</code><br />
|
||
The default output format. It corresponds to the printf <code>%g</code>
|
||
specification. Typically this shows six decimal digits.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:sci</code> <code>digits</code><br />
|
||
Scientific notation, corresponding to the printf <code>%g</code> output format
|
||
with the precision given by <code>digits</code>. This produces either fixed
|
||
point or exponential notation depending on the value output.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:fix</code> <code>digits</code><br />
|
||
Fixed point notation, corresponding to the printf <code>%f</code> output format
|
||
with the precision given by <code>digits</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:eng</code> <code>digits</code><br />
|
||
Exponential notation, corresponding to the printf <code>%E</code> output format
|
||
with the precision given by <code>digits</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:raw</code><br />
|
||
Raw output: this is the default form of the output from a math
|
||
evaluation. This may show more precision than the number actually
|
||
possesses.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Other special commands:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>:!``line...</code><br />
|
||
Execute <code>line...</code> as a normal shell command line. Note that it is
|
||
executed in the context of the function, i.e. with local variables.
|
||
Space is optional after <code>:!</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:local</code> <code>arg</code> ...<br />
|
||
Declare variables local to the function. Other variables may be
|
||
used, too, but they will be taken from or put into the global scope.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>:function</code> <code>name</code> [ <code>body</code> ]<br />
|
||
Define a mathematical function or (with no <code>body</code>) delete it.
|
||
<code>:function</code> may be abbreviated to <code>:func</code> or simply <code>:f</code>. The <code>name</code>
|
||
may contain the same characters as a shell function name. The
|
||
function is defined using <code>zmathfuncdef</code>, see below.</p>
|
||
<p>Note that <code>zcalc</code> takes care of all quoting. Hence for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">:f cube $1 * $1 * $1
|
||
</code></pre>
|
||
</div>
|
||
<p>defines a function to cube the sole argument. Functions so defined,
|
||
or indeed any functions defined directly or indirectly using
|
||
<code>functions -M</code>, are available to execute by typing only the name on
|
||
the line in RPN mode; this pops the appropriate number of arguments
|
||
off the stack to pass to the function, i.e. 1 in the case of the
|
||
example <code>cube</code> function. If there are optional arguments only the
|
||
mandatory arguments are supplied by this means.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[#``base``]</code><br />
|
||
This is not a special command, rather part of normal arithmetic
|
||
syntax; however, when this form appears on a line by itself the
|
||
default output radix is set to <code>base</code>. Use, for example, ‘<code>[#16]</code>’
|
||
to display hexadecimal output preceded by an indication of the base,
|
||
or ‘<code>[##16]</code>’ just to display the raw number in the given base.
|
||
Bases themselves are always specified in decimal. ‘<code>[#]</code>’ restores
|
||
the normal output format. Note that setting an output base
|
||
suppresses floating point output; use ‘<code>[#]</code>’ to return to normal
|
||
operation.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>$``var</code><br />
|
||
Print out the value of var literally; does not affect the
|
||
calculation. To use the value of var, omit the leading ‘<code>$</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
<p>See the comments in the function for a few extra tips.</p>
|
||
<p><span id="index-max"></span> <span id="index-min"></span>
|
||
<span id="index-sum"></span> <span id="index-zmathfunc"></span></p>
|
||
<p><code>min(``arg``, ...)</code></p>
|
||
<p><code>max(``arg``, ...)</code></p>
|
||
<p><code>sum(``arg``, ...)</code></p>
|
||
<p><code>zmathfunc</code></p>
|
||
<p>The function <code>zmathfunc</code> defines the three mathematical functions <code>min</code>,
|
||
<code>max</code>, and <code>sum</code>. The functions <code>min</code> and <code>max</code> take one or more
|
||
arguments. The function <code>sum</code> takes zero or more arguments. Arguments
|
||
can be of different types (ints and floats).</p>
|
||
<p>Not to be confused with the <code>zsh/mathfunc</code> module, described in <a href="Zsh-Modules.html#The-zsh_002fmathfunc-Module">The
|
||
zsh/mathfunc Module</a>.</p>
|
||
<p><span id="index-zmathfuncdef"></span></p>
|
||
<p><code>zmathfuncdef</code> [ <code>mathfunc</code> [ <code>body</code> ] ]</p>
|
||
<p>A convenient front end to <code>functions -M</code>.</p>
|
||
<p>With two arguments, define a mathematical function named <code>mathfunc</code>
|
||
which can be used in any form of arithmetic evaluation. <code>body</code> is a
|
||
mathematical expression to implement the function. It may contain
|
||
references to position parameters <code>$1</code>, <code>$2</code>, ... to refer to mandatory
|
||
parameters and <code>${1:-``defvalue``}</code> ... to refer to optional parameters.
|
||
Note that the forms must be strictly adhered to for the function to
|
||
calculate the correct number of arguments. The implementation is held in
|
||
a shell function named <code>zsh_math_func_``mathfunc</code>; usually the user will
|
||
not need to refer to the shell function directly. Any existing function
|
||
of the same name is silently replaced.</p>
|
||
<p>With one argument, remove the mathematical function <code>mathfunc</code> as well
|
||
as the shell function implementation.</p>
|
||
<p>With no arguments, list all <code>mathfunc</code> functions in a form The functions
|
||
have not necessarily been defined by <code>zmathfuncdef</code>.</p>
|
||
<hr />
|
||
<p><span id="User-Configuration-Functions"></span>
|
||
<span id="User-Configuration-Functions-1"></span></p>
|
||
<h2 id="2611-user-configuration-functions"><a class="header" href="#2611-user-configuration-functions">26.11 User Configuration Functions</a></h2>
|
||
<p>The <code>zsh/newuser</code> module comes with a function to aid in configuring
|
||
shell options for new users. If the module is installed, this function
|
||
can also be run by hand. It is available even if the module’s default
|
||
behaviour, namely running the function for a new user logging in without
|
||
startup files, is inhibited.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zsh-newuser-install</code> [ <code>-f</code> ]<br />
|
||
The function presents the user with various options for customizing
|
||
their initialization scripts. Currently only <code>~/.zshrc</code> is handled.
|
||
<code>$ZDOTDIR/.zshrc</code> is used instead if the parameter <code>ZDOTDIR</code> is set;
|
||
this provides a way for the user to configure a file without
|
||
altering an existing <code>.zshrc</code>.</p>
|
||
<p>By default the function exits immediately if it finds any of the
|
||
files <code>.zshenv</code>, <code>.zprofile</code>, <code>.zshrc</code>, or <code>.zlogin</code> in the
|
||
appropriate directory. The option <code>-f</code> is required in order to force
|
||
the function to continue. Note this may happen even if <code>.zshrc</code>
|
||
itself does not exist.</p>
|
||
<p>As currently configured, the function will exit immediately if the
|
||
user has root privileges; this behaviour cannot be overridden.</p>
|
||
<p>Once activated, the function’s behaviour is supposed to be
|
||
self-explanatory. Menus are present allowing the user to alter the
|
||
value of options and parameters. Suggestions for improvements are
|
||
always welcome.</p>
|
||
<p>When the script exits, the user is given the opportunity to save the
|
||
new file or not; changes are not irreversible until this point.
|
||
However, the script is careful to restrict changes to the file only
|
||
to a group marked by the lines ‘<code># Lines configured by zsh-newuser-install</code>’ and ‘<code># End of lines configured by zsh-newuser-install</code>’. In addition, the old version of <code>.zshrc</code> is
|
||
saved to a file with the suffix <code>.zni</code> appended.</p>
|
||
<p>If the function edits an existing <code>.zshrc</code>, it is up to the user to
|
||
ensure that the changes made will take effect. For example, if
|
||
control usually returns early from the existing <code>.zshrc</code> the lines
|
||
will not be executed; or a later initialization file may override
|
||
options or parameters, and so on. The function itself does not
|
||
attempt to detect any such conflicts.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Other-Functions"></span> <span id="Other-Functions-1"></span></p>
|
||
<h2 id="2612-other-functions"><a class="header" href="#2612-other-functions">26.12 Other Functions</a></h2>
|
||
<p>There are a large number of helpful functions in the <code>Functions/Misc</code>
|
||
directory of the zsh distribution. Most are very simple and do not
|
||
require documentation here, but a few are worthy of special mention.</p>
|
||
<hr />
|
||
<p><span id="Descriptions"></span></p>
|
||
<h3 id="26121-descriptions"><a class="header" href="#26121-descriptions">26.12.1 Descriptions</a></h3>
|
||
<p><span id="index-colors"></span></p>
|
||
<p><code>colors</code></p>
|
||
<p>This function initializes several associative arrays to map color names
|
||
to (and from) the ANSI standard eight-color terminal codes. These are
|
||
used by the prompt theme system (<a href="#Prompt-Themes">Prompt Themes</a>). You
|
||
seldom should need to run <code>colors</code> more than once.</p>
|
||
<p>The eight base colors are: <code>black</code>, <code>red</code>, <code>green</code>, <code>yellow</code>, <code>blue</code>,
|
||
<code>magenta</code>, <code>cyan</code>, and <code>white</code>. Each of these has codes for foreground
|
||
and background. In addition there are seven intensity attributes:
|
||
<code>bold</code>, <code>faint</code>, <code>standout</code>, <code>underline</code>, <code>blink</code>, <code>reverse</code>, and
|
||
<code>conceal</code>. Finally, there are seven codes used to negate attributes:
|
||
<code>none</code> (reset all attributes to the defaults), <code>normal</code> (neither bold
|
||
nor faint), <code>no-standout</code>, <code>no-underline</code>, <code>no-blink</code>, <code>no-reverse</code>, and
|
||
<code>no-conceal</code>.</p>
|
||
<p>Some terminals do not support all combinations of colors and
|
||
intensities.</p>
|
||
<p>The associative arrays are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>color</code><br />
|
||
<code>colour</code><br />
|
||
Map all the color names to their integer codes, and integer codes to
|
||
the color names. The eight base names map to the foreground color
|
||
codes, as do names prefixed with ‘<code>fg-</code>’, such as ‘<code>fg-red</code>’. Names
|
||
prefixed with ‘<code>bg-</code>’, such as ‘<code>bg-blue</code>’, refer to the background
|
||
codes. The reverse mapping from code to color yields base name for
|
||
foreground codes and the <code>bg-</code> form for backgrounds.</p>
|
||
<p>Although it is a misnomer to call them ‘colors’, these arrays also
|
||
map the other fourteen attributes from names to codes and codes to
|
||
names.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>fg</code><br />
|
||
<code>fg_bold</code><br />
|
||
<code>fg_no_bold</code><br />
|
||
Map the eight basic color names to ANSI terminal escape sequences
|
||
that set the corresponding foreground text properties. The <code>fg</code>
|
||
sequences change the color without changing the eight intensity
|
||
attributes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>bg</code><br />
|
||
<code>bg_bold</code><br />
|
||
<code>bg_no_bold</code><br />
|
||
Map the eight basic color names to ANSI terminal escape sequences
|
||
that set the corresponding background properties. The <code>bg</code> sequences
|
||
change the color without changing the eight intensity attributes.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In addition, the scalar parameters <code>reset_color</code> and <code>bold_color</code> are
|
||
set to the ANSI terminal escapes that turn off all attributes and turn
|
||
on bold intensity, respectively.</p>
|
||
<p><span id="index-fned"></span></p>
|
||
<p><code>fned</code> [ <code>-x</code> <code>num</code> ] <code>name</code></p>
|
||
<p>Same as <code>zed -f</code>. This function does not appear in the zsh distribution,
|
||
but can be created by linking <code>zed</code> to the name <code>fned</code> in some directory
|
||
in your <code>fpath</code>.</p>
|
||
<p><span id="index-is_002dat_002dleast"></span></p>
|
||
<p><code>is-at-least</code> <code>needed</code> [ <code>present</code> ]</p>
|
||
<p>Perform a greater-than-or-equal-to comparison of two strings having the
|
||
format of a zsh version number; that is, a string of numbers and text
|
||
with segments separated by dots or dashes. If the <code>present</code> string is
|
||
not provided, <code>$ZSH_VERSION</code> is used. Segments are paired left-to-right
|
||
in the two strings with leading non-number parts ignored. If one string
|
||
has fewer segments than the other, the missing segments are considered
|
||
zero.</p>
|
||
<p>This is useful in startup files to set options and other state that are
|
||
not available in all versions of zsh.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">is-at-least 3.1.6-15 && setopt NO_GLOBAL_RCS
|
||
is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
|
||
is-at-least 2.6-17 || print "You can't use is-at-least here."
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-nslookup"></span></p>
|
||
<p><code>nslookup</code> [ <code>arg</code> ... ]</p>
|
||
<p>This wrapper function for the <code>nslookup</code> command requires the <code>zsh/zpty</code>
|
||
module (see <a href="Zsh-Modules.html#The-zsh_002fzpty-Module">The zsh/zpty
|
||
Module</a>). It behaves exactly
|
||
like the standard <code>nslookup</code> except that it provides customizable
|
||
prompts (including a right-side prompt) and completion of nslookup
|
||
commands, host names, etc. (if you use the function-based completion
|
||
system). Completion styles may be set with the context prefix
|
||
‘<code>:completion:nslookup</code>’.</p>
|
||
<p>See also the <code>pager</code>, <code>prompt</code> and <code>rprompt</code> styles below.</p>
|
||
<p><span id="index-regexp_002dreplace"></span></p>
|
||
<p><code>regexp-replace</code> <code>var</code> <code>regexp</code> <code>replace</code></p>
|
||
<p>Use regular expressions to perform a global search and replace operation
|
||
on a variable. POSIX extended regular expressions are used, unless the
|
||
option <code>RE_MATCH_PCRE</code> has been set, in which case Perl-compatible
|
||
regular expressions are used (this requires the shell to be linked
|
||
against the <code>pcre</code> library).</p>
|
||
<p><code>var</code> is the name of the variable containing the string to be matched.
|
||
The variable will be modified directly by the function. The variables
|
||
<code>MATCH</code>, <code>MBEGIN</code>, <code>MEND</code>, <code>match</code>, <code>mbegin</code>, <code>mend</code> should be avoided
|
||
as these are used by the regular expression code.</p>
|
||
<p><code>regexp</code> is the regular expression to match against the string.</p>
|
||
<p><code>replace</code> is the replacement text. This can contain parameter, command
|
||
and arithmetic expressions which will be replaced: in particular, a
|
||
reference to <code>$MATCH</code> will be replaced by the text matched by the
|
||
pattern.</p>
|
||
<p>The return status is 0 if at least one match was performed, else 1.</p>
|
||
<p><span id="index-run_002dhelp-1"></span></p>
|
||
<p><code>run-help</code> <code>cmd</code></p>
|
||
<p>This function is designed to be invoked by the <code>run-help</code> ZLE widget, in
|
||
place of the default alias. See ‘Accessing On-Line Help’
|
||
(<a href="#Utilities">Utilities</a>) for setup instructions.</p>
|
||
<p>In the discussion which follows, if <code>cmd</code> is a file system path, it is
|
||
first reduced to its rightmost component (the file name).</p>
|
||
<p>Help is first sought by looking for a file named <code>cmd</code> in the directory
|
||
named by the <code>HELPDIR</code> parameter. If no file is found, an assistant
|
||
function, alias, or command named <code>run-help-cmd</code> is sought. If found,
|
||
the assistant is executed with the rest of the current command line
|
||
(everything after the command name <code>cmd</code>) as its arguments. When neither
|
||
file nor assistant is found, the external command ‘<code>man</code> <code>cmd</code>’ is run.</p>
|
||
<p>An example assistant for the "ssh" command:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">run-help-ssh() {
|
||
emulate -LR zsh
|
||
local -a args
|
||
# Delete the "-l username" option
|
||
zparseopts -D -E -a args l:
|
||
# Delete other options, leaving: host command
|
||
args=(${@:#-*})
|
||
if [[ ${#args} -lt 2 ]]; then
|
||
man ssh
|
||
else
|
||
run-help $args[2]
|
||
fi
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>Several of these assistants are provided in the <code>Functions/Misc</code> your
|
||
search path, in order to be found and used by <code>run-help</code>.</p>
|
||
<p><span id="index-run_002dhelp_002dgit"></span>
|
||
<span id="index-run_002dhelp_002dip"></span>
|
||
<span id="index-run_002dhelp_002dopenssl"></span>
|
||
<span id="index-run_002dhelp_002dp4"></span>
|
||
<span id="index-run_002dhelp_002dsudo"></span>
|
||
<span id="index-run_002dhelp_002dsvk"></span>
|
||
<span id="index-run_002dhelp_002dsvn"></span></p>
|
||
<p>run-help-git</p>
|
||
<p>run-help-ip</p>
|
||
<p>run-help-openssl</p>
|
||
<p>run-help-p4</p>
|
||
<p>run-help-sudo</p>
|
||
<p>run-help-svk</p>
|
||
<p><code>run-help-svn</code></p>
|
||
<p>Assistant functions for the <code>git</code>, <code>ip</code>, <code>openssl</code>, <code>p4</code>, <code>sudo</code>, <code>svk</code>,
|
||
and <code>svn</code>, commands.</p>
|
||
<p><code>tetris</code></p>
|
||
<p>Zsh was once accused of not being as complete as Emacs, because it
|
||
lacked a Tetris game. This function was written to refute this vicious
|
||
slander.</p>
|
||
<p>This function must be used as a ZLE widget:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U tetris
|
||
zle -N tetris
|
||
bindkey keys tetris
|
||
</code></pre>
|
||
</div>
|
||
<p>To start a game, execute the widget by typing the <code>keys</code>. Whatever
|
||
command line you were editing disappears temporarily, and your keymap is
|
||
also temporarily replaced by the Tetris control keys. The previous
|
||
editor state is restored when you quit the game (by pressing ‘<code>q</code>’) or
|
||
when you lose.</p>
|
||
<p>If you quit in the middle of a game, the next invocation of the <code>tetris</code>
|
||
widget will continue where you left off. If you lost, it will start a
|
||
new game.</p>
|
||
<p><code>tetriscurses</code></p>
|
||
<p>This is a port of the above to zcurses. The input handling is improved a
|
||
bit so that moving a block sideways doesn’t automatically advance a
|
||
timestep, and the graphics use unicode block graphics.</p>
|
||
<p>This version does not save the game state between invocations, and is
|
||
not invoked as a widget, but rather as:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U tetriscurses
|
||
tetriscurses
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-zargs"></span></p>
|
||
<p><code>zargs</code> [ <code>option</code> ... <code>-``-</code> ] [ <code>input</code> ... ] [ <code>-``-</code> <code>command</code>
|
||
[ <code>arg</code> ... ] ]</p>
|
||
<p>This function has a similar purpose to GNU xargs. Instead of reading
|
||
lines of arguments from the standard input, it takes them from the
|
||
command line. This is useful because zsh, especially with recursive glob
|
||
operators, often can construct a command line for a shell function that
|
||
is longer than can be accepted by an external command.</p>
|
||
<p>The <code>option</code> list represents options of the <code>zargs</code> command itself,
|
||
which are the same as those of <code>xargs</code>. The <code>input</code> list is the
|
||
collection of strings (often file names) that become the arguments of
|
||
the <code>command</code>, analogous to the standard input of <code>xargs</code>. Finally, the
|
||
<code>arg</code> list consists of those arguments (usually options) that are passed
|
||
to the <code>command</code> each time it runs. The <code>arg</code> list precedes the elements
|
||
from the <code>input</code> list in each run. If no <code>command</code> is provided, then no
|
||
<code>arg</code> list may be provided, and in that event the default command is
|
||
‘<code>print</code>’ with arguments ‘<code>-r -``-</code>’.</p>
|
||
<p>For example, to get a long <code>ls</code> listing of all non-hidden plain files in
|
||
the current directory or its subdirectories:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload -U zargs
|
||
zargs -- **/*(.) -- ls -ld --
|
||
</code></pre>
|
||
</div>
|
||
<p>The first and third occurrences of ‘<code>-``-</code>’ are used to mark the end of
|
||
options for <code>zargs</code> and <code>ls</code> respectively to guard against filenames
|
||
starting with ‘<code>-</code>’, while the second is used to separate the list of
|
||
files from the command to run (‘<code>ls -ld –</code>’).</p>
|
||
<p>The first ‘<code>-``-</code>’ would also be needed if there was a chance the list
|
||
might be empty as in:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zargs -r -- ./*.back(#qN) -- rm -f
|
||
</code></pre>
|
||
</div>
|
||
<p>In the event that the string ‘<code>-``-</code>’ is or may be an <code>input</code>, the <code>-e</code>
|
||
option may be used to change the end-of-inputs marker. Note that this
|
||
does <em>not</em> change the end-of-options marker. For example, to use ‘<code>..</code>’
|
||
as the marker:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zargs -e.. -- **/*(.) .. ls -ld --
|
||
</code></pre>
|
||
</div>
|
||
<p>This is a good choice in that example because no plain file can be named
|
||
‘<code>..</code>’, but the best end-marker depends on the circumstances.</p>
|
||
<p>The options <code>-i</code>, <code>-I</code>, <code>-l</code>, <code>-L</code>, and <code>-n</code> differ slightly from their
|
||
usage in <code>xargs</code>. There are no input lines for <code>zargs</code> to count, so <code>-l</code>
|
||
and <code>-L</code> count through the <code>input</code> list, and <code>-n</code> counts the number of
|
||
arguments passed to each execution of <code>command</code>, <em>including</em> any <code>arg</code>
|
||
list. Also, any time <code>-i</code> or <code>-I</code> is used, each <code>input</code> is processed
|
||
separately as if by ‘<code>-L</code> <code>1</code>’.</p>
|
||
<p>For details of the other <code>zargs</code> options, see man page xargs(1) (but
|
||
note the difference in function between <code>zargs</code> and <code>xargs</code>) or run
|
||
<code>zargs</code> with the <code>-``-help</code> option.</p>
|
||
<p><span id="index-zed"></span></p>
|
||
<p><code>zed</code> [ <code>-f</code> [ <code>-x</code> <code>num</code> ] ] <code>name</code></p>
|
||
<p><code>zed -b</code></p>
|
||
<p>This function uses the ZLE editor to edit a file or function.</p>
|
||
<p>Only one <code>name</code> argument is allowed. If the <code>-f</code> option is given, the
|
||
name is taken to be that of a function; if the function is marked for
|
||
autoloading, <code>zed</code> searches for it in the <code>fpath</code> and loads it. Note
|
||
that functions edited this way are installed into the current shell, but
|
||
<em>not</em> written back to the autoload file. In this case the <code>-x</code> option
|
||
specifies that leading tabs indenting the function according to syntax
|
||
should be converted into the given number of spaces; ‘<code>-x 2</code>’ is
|
||
consistent with the layout of functions distributed with the shell.</p>
|
||
<p>Without <code>-f</code>, <code>name</code> is the path name of the file to edit, which need
|
||
not exist; it is created on write, if necessary.</p>
|
||
<p>While editing, the function sets the main keymap to <code>zed</code> and the vi
|
||
command keymap to <code>zed-vicmd</code>. These will be copied from the existing
|
||
<code>main</code> and <code>vicmd</code> keymaps if they do not exist the first time <code>zed</code> is
|
||
run. They can be used to provide special key bindings used only in zed.</p>
|
||
<p>If it creates the keymap, <code>zed</code> rebinds the return key to insert a line
|
||
break and ‘<code>^X^W</code>’ to accept the edit in the <code>zed</code> keymap, and binds
|
||
‘<code>ZZ</code>’ to accept the edit in the <code>zed-vicmd</code> keymap.</p>
|
||
<p>The bindings alone can be installed by running ‘<code>zed -b</code>’. This is this
|
||
will overwrite the existing <code>zed</code> and <code>zed-vicmd</code> keymaps.</p>
|
||
<p>Completion is available, and styles may be set with the context prefix
|
||
‘<code>:completion:zed</code>’.</p>
|
||
<p>A zle widget <code>zed-set-file-name</code> is available. This can be called by
|
||
name from within zed using ‘<code>\ex zed-set-file-name</code>’ (note, however,
|
||
that because of zed’s rebindings you will have to type <code>^j</code> at the end
|
||
instead of the return key), or can be bound to a key in either of the
|
||
<code>zed</code> or <code>zed-vicmd</code> keymaps after ‘<code>zed -b</code>’ has been run. When the
|
||
widget is called, it prompts for a new name for the file being edited.
|
||
When zed exits the file will be written under that name and the original
|
||
file will be left alone. The widget has no effect with ‘<code>zed -f</code>’.</p>
|
||
<p>While <code>zed-set-file-name</code> is running, zed uses the keymap
|
||
<code>zed-normal-keymap</code>, which is linked from the main keymap in effect at
|
||
the time zed initialised its bindings. (This is to make the return key
|
||
operate normally.) The result is that if the main keymap has been
|
||
changed, the widget won’t notice. This is not a concern for most users.</p>
|
||
<p><span id="index-zcp"></span> <span id="index-zln"></span></p>
|
||
<p><code>zcp</code> [ <code>-finqQvwW</code> ] <code>srcpat</code> <code>dest</code></p>
|
||
<p><code>zln</code> [ <code>-finqQsvwW</code> ] <code>srcpat</code> <code>dest</code></p>
|
||
<p>Same as <code>zmv -C</code> and <code>zmv -L</code>, respectively. These functions do not
|
||
appear in the zsh distribution, but can be created by linking <code>zmv</code> to
|
||
the names <code>zcp</code> and <code>zln</code> in some directory in your <code>fpath</code>.</p>
|
||
<p><code>zkbd</code></p>
|
||
<p>See ‘Keyboard Definition’ (<a href="#Utilities">Utilities</a>).</p>
|
||
<p><span id="index-zmv"></span></p>
|
||
<p><code>zmv</code> [ <code>-finqQsvwW</code> ] [ <code>-C</code> | <code>-L</code> | <code>-M</code> | -{<code>p</code>|<code>P</code>} <code>program</code> ]
|
||
[ <code>-o</code> <code>optstring</code> ]</p>
|
||
<p><code> ``srcpat</code> <code>dest</code></p>
|
||
<p>Move (usually, rename) files matching the pattern <code>srcpat</code> to
|
||
corresponding files having names of the form given by <code>dest</code>, where
|
||
<code>srcpat</code> contains parentheses surrounding patterns which will be
|
||
replaced in turn by <code>$1</code>, <code>$2</code>, ... in <code>dest</code>. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmv '(*).lis' '$1.txt'
|
||
</code></pre>
|
||
</div>
|
||
<p>renames ‘<code>foo.lis</code>’ to ‘<code>foo.txt</code>’, ‘<code>my.old.stuff.lis</code>’ to
|
||
‘<code>my.old.stuff.txt</code>’, and so on.</p>
|
||
<p>The pattern is always treated as an <code>EXTENDED_GLOB</code> pattern. Any file
|
||
whose name is not changed by the substitution is simply ignored. Any
|
||
error (a substitution resulted in an empty string, two substitutions
|
||
gave the same result, the destination was an existing regular file and
|
||
<code>-f</code> was not given) causes the entire function to abort without doing
|
||
anything.</p>
|
||
<p>In addition to pattern replacement, the variable <code>$f</code> can be referrred
|
||
to in the second (replacement) argument. This makes it possible to use
|
||
variable substitution to alter the argument; see examples below.</p>
|
||
<p>Options:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-f</code><br />
|
||
Force overwriting of destination files. Not currently passed down to
|
||
the <code>mv</code>/<code>cp</code>/<code>ln</code> command due to vagaries of implementations (but
|
||
you can use <code>-o-f</code> to do that).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-i</code><br />
|
||
Interactive: show each line to be executed and ask the user whether
|
||
to execute it. ‘<code>Y</code>’ or ‘<code>y</code>’ will execute it, anything else will
|
||
skip it. Note that you just need to type one character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code><br />
|
||
No execution: print what would happen, but don’t do it.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-q</code><br />
|
||
Turn bare glob qualifiers off: now assumed by default, so this has
|
||
no effect.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-Q</code><br />
|
||
Force bare glob qualifiers on. Don’t turn this on unless you are
|
||
actually using glob qualifiers in a pattern.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
Symbolic, passed down to <code>ln</code>; only works with <code>-L</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-v</code><br />
|
||
Verbose: print each command as it’s being executed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-w</code><br />
|
||
Pick out wildcard parts of the pattern, as described above, and
|
||
implicitly add parentheses for referring to them.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-W</code><br />
|
||
Just like <code>-w</code>, with the addition of turning wildcards in the
|
||
replacement pattern into sequential <code>${1}</code> .. <code>${N}</code> references.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-C</code><br />
|
||
<code>-L</code><br />
|
||
<code>-M</code><br />
|
||
Force <code>cp</code>, <code>ln</code> or <code>mv</code>, respectively, regardless of the name of
|
||
the function.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-p</code> <code>program</code><br />
|
||
Call <code>program</code> instead of <code>cp</code>, <code>ln</code> or <code>mv</code>. Whatever it does, it
|
||
should at least understand the form</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">program -- oldname newname
|
||
</code></pre>
|
||
</div>
|
||
<p>where <code>oldname</code> and <code>newname</code> are filenames generated by <code>zmv</code>.
|
||
<code>program</code> will be split into words, so might be e.g. the name of an
|
||
archive tool plus a copy or rename subcommand.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-P</code> <code>program</code><br />
|
||
As <code>-p</code> <code>program</code>, except that <code>program</code> does not accept a following
|
||
<code>-``-</code> to indicate the end of options. In this case filenames must
|
||
already be in a sane form for the program in question.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-o</code> <code>optstring</code><br />
|
||
The <code>optstring</code> is split into words and passed down verbatim to the
|
||
<code>cp</code>, <code>ln</code> or <code>mv</code> command called to perform the work. It should
|
||
probably begin with a ‘<code>-</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Further examples:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmv -v '(* *)' '${1// /_}'
|
||
</code></pre>
|
||
</div>
|
||
<p>For any file in the current directory with at least one space in the
|
||
name, replace every space by an underscore and display the commands
|
||
executed.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmv -v '* *' '${f// /_}'
|
||
</code></pre>
|
||
</div>
|
||
<p>This does exactly the same by referring to the file name stored in <code>$f</code>.</p>
|
||
<p>For more complete examples and other implementation details, see the
|
||
<code>zmv</code> source file, usually located in one of the directories named in
|
||
your <code>fpath</code>, or in <code>Functions/Misc/zmv</code> in the zsh distribution.</p>
|
||
<p><code>zrecompile</code></p>
|
||
<p>See ‘Recompiling Functions’ (<a href="#Utilities">Utilities</a>).</p>
|
||
<p><span id="index-zstyle_002b"></span></p>
|
||
<p><code>zstyle+</code> <code>context</code> <code>style</code> <code>value</code> [ <code>+</code> <code>subcontext</code> <code>style</code> <code>value</code>
|
||
... ]</p>
|
||
<p>This makes defining styles a bit simpler by using a single ‘<code>+</code>’ as a
|
||
special token that allows you to append a context name to the previously
|
||
used context name. Like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle+ ':foo:bar' style1 value1 \
|
||
+':baz' style2 value2 \
|
||
+':frob' style3 value3
|
||
</code></pre>
|
||
</div>
|
||
<p>This defines <code>style1</code> with <code>value1</code> for the context <code>:foo:bar</code> as usual,
|
||
but it also defines <code>style2</code> with <code>value2</code> for the context
|
||
<code>:foo:bar:baz</code> and <code>style3</code> with <code>value3</code> for <code>:foo:bar:frob</code>. Any
|
||
<code>subcontext</code> may be the empty string to re-use the first context
|
||
unchanged.</p>
|
||
<hr />
|
||
<p><span id="Styles-2"></span></p>
|
||
<h3 id="26122-styles"><a class="header" href="#26122-styles">26.12.2 Styles</a></h3>
|
||
<p><span id="index-insert_002dtab_002c-completion-style-1"></span></p>
|
||
<p><code>insert-tab</code></p>
|
||
<p>The <code>zed</code> function <em>sets</em> this style in context ‘<code>:completion:zed:*</code>’ to
|
||
turn off completion when <code>TAB</code> is typed at the beginning of a line. You
|
||
may override this by setting your own value for this context and style.</p>
|
||
<p><span id="index-pager_002c-nslookup-style"></span></p>
|
||
<p><code>pager</code></p>
|
||
<p>The <code>nslookup</code> function looks up this style in the context ‘<code>:nslookup</code>’
|
||
to determine the program used to display output that does not fit on a
|
||
single screen.</p>
|
||
<p><span id="index-prompt_002c-nslookup-style"></span>
|
||
<span id="index-rprompt_002c-nslookup-style"></span></p>
|
||
<p><code>prompt</code></p>
|
||
<p><code>rprompt</code></p>
|
||
<p>The <code>nslookup</code> function looks up this style in the context ‘<code>:nslookup</code>’
|
||
to set the prompt and the right-side prompt, respectively. The usual
|
||
expansions for the <code>PS1</code> and <code>RPS1</code> parameters may be used (see <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>).</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="Zftp-Function-System.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
|
||
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
||
<a rel="prev" href="Zftp-Function-System.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></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>
|