2712 lines
151 KiB
HTML
2712 lines
151 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Expansion - Zsh Manual</title>
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
<link rel="stylesheet" href="./theme/catppuccin.css">
|
||
<link rel="stylesheet" href="./theme/catppuccin-highlight.css">
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-&-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html" class="active"><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"><strong aria-hidden="true">26.</strong> User Contributions</a></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="latte">Latte</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="frappe">Frappé</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="macchiato">Macchiato</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mocha">Mocha</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Zsh Manual</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script type="text/javascript">
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||
<p><strong>Table of Contents</strong> <em>generated with <a href="https://github.com/thlorenz/doctoc">DocToc</a></em></p>
|
||
<ul>
|
||
<li><a href="#14-expansion">14 Expansion</a>
|
||
<ul>
|
||
<li><a href="#141-history-expansion">14.1 History Expansion</a>
|
||
<ul>
|
||
<li><a href="#1411-overview">14.1.1 Overview</a></li>
|
||
<li><a href="#1412-event-designators">14.1.2 Event Designators</a></li>
|
||
<li><a href="#1413-word-designators">14.1.3 Word Designators</a></li>
|
||
<li><a href="#1414-modifiers">14.1.4 Modifiers</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#142-process-substitution">14.2 Process Substitution</a></li>
|
||
<li><a href="#143-parameter-expansion">14.3 Parameter Expansion</a>
|
||
<ul>
|
||
<li><a href="#1431-parameter-expansion-flags">14.3.1 Parameter Expansion Flags</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#"></a>
|
||
<ul>
|
||
<li><a href="#1432-rules">14.3.2 Rules</a></li>
|
||
<li><a href="#1433-examples">14.3.3 Examples</a></li>
|
||
<li><a href="#144-command-substitution">14.4 Command Substitution</a></li>
|
||
<li><a href="#145-arithmetic-expansion">14.5 Arithmetic Expansion</a></li>
|
||
<li><a href="#146-brace-expansion">14.6 Brace Expansion</a></li>
|
||
<li><a href="#147-filename-expansion">14.7 Filename Expansion</a>
|
||
<ul>
|
||
<li><a href="#1471-dynamic-named-directories">14.7.1 Dynamic named directories</a></li>
|
||
<li><a href="#1472-static-named-directories">14.7.2 Static named directories</a></li>
|
||
<li><a href="#1473--expansion">14.7.3 ‘=’ expansion</a></li>
|
||
<li><a href="#1474-notes">14.7.4 Notes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#148-filename-generation">14.8 Filename Generation</a>
|
||
<ul>
|
||
<li><a href="#1481-glob-operators">14.8.1 Glob Operators</a></li>
|
||
<li><a href="#1482-ksh-like-glob-operators">14.8.2 ksh-like Glob Operators</a></li>
|
||
<li><a href="#1483-precedence">14.8.3 Precedence</a></li>
|
||
<li><a href="#1484-globbing-flags">14.8.4 Globbing Flags</a></li>
|
||
<li><a href="#1485-approximate-matching">14.8.5 Approximate Matching</a></li>
|
||
<li><a href="#1486-recursive-globbing">14.8.6 Recursive Globbing</a></li>
|
||
<li><a href="#1487-glob-qualifiers">14.8.7 Glob Qualifiers</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Expansion"></span> <span id="Expansion-1"></span></p>
|
||
<h1 id="14-expansion"><a class="header" href="#14-expansion">14 Expansion</a></h1>
|
||
<p><span id="index-expansion"></span></p>
|
||
<p>The following types of expansions are performed in the indicated order
|
||
in five steps:</p>
|
||
<p><em>History Expansion</em><br />
|
||
This is performed only in interactive shells.</p>
|
||
<p><em>Alias Expansion</em><br />
|
||
Aliases are expanded immediately before the command line is parsed as
|
||
explained in <a href="Shell-Grammar.html#Aliasing">Aliasing</a>.</p>
|
||
<p><em>Process Substitution</em><br />
|
||
<em>Parameter Expansion</em><br />
|
||
<em>Command Substitution</em><br />
|
||
<em>Arithmetic Expansion</em><br />
|
||
<em>Brace Expansion</em><br />
|
||
These five are performed in left-to-right fashion. On each argument, any
|
||
of the five steps that are needed are performed one after the other.
|
||
Hence, for example, all the parts of parameter expansion are completed
|
||
before command substitution is started. After these expansions, all
|
||
unquoted occurrences of the characters ‘\’,‘’’ and ‘"’ are removed.</p>
|
||
<p><em>Filename Expansion</em><br />
|
||
If the SH_FILE_EXPANSION option is set, the order of expansion is
|
||
modified for compatibility with sh and ksh. In that case <em>filename
|
||
expansion</em> is performed immediately after <em>alias expansion</em>, preceding
|
||
the set of five expansions mentioned above.</p>
|
||
<p><span id="index-globbing"></span></p>
|
||
<p><em>Filename Generation</em><br />
|
||
This expansion, commonly referred to as globbing, is always done last.</p>
|
||
<p>The following sections explain the types of expansion in detail.</p>
|
||
<hr />
|
||
<p><span id="History-Expansion"></span> <span
|
||
id="History-Expansion-1"></span></p>
|
||
<h2 id="141-history-expansion"><a class="header" href="#141-history-expansion">14.1 History Expansion</a></h2>
|
||
<p><span id="index-history"></span> <span
|
||
id="index-history-expansion"></span> <span
|
||
id="index-expansion_002c-history"></span></p>
|
||
<p>History expansion allows you to use words from previous command lines in
|
||
the command line you are typing. This simplifies spelling corrections
|
||
and the repetition of complicated commands or arguments.</p>
|
||
<p><span id="index-HISTSIZE_002c-use-of"></span></p>
|
||
<p>Immediately before execution, each command is saved in the history list,
|
||
the size of which is controlled by the HISTSIZE parameter. The one most
|
||
recent command is always retained in any case. Each saved command in the
|
||
history list is called a history <em>event</em> and is assigned a number,
|
||
beginning with 1 (one) when the shell starts up. The history number that
|
||
you may see in your prompt (see <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>) is the number that
|
||
is to be assigned to the <em>next</em> command.</p>
|
||
<hr />
|
||
<p><span id="Overview"></span> <span id="Overview-1"></span></p>
|
||
<h3 id="1411-overview"><a class="header" href="#1411-overview">14.1.1 Overview</a></h3>
|
||
<p><span id="index-histchars_002c-use-of-1"></span></p>
|
||
<p>A history expansion begins with the first character of the histchars
|
||
parameter, which is ‘!’ by default, and may occur anywhere on the
|
||
command line, including inside double quotes (but not inside single
|
||
quotes ’...’ or C-style quotes $’...’ nor when escaped with a
|
||
backslash).</p>
|
||
<p>The first character is followed by an optional event designator (<a href="#Event-Designators">Event
|
||
Designators</a>) and then an optional word designator
|
||
(<a href="#Word-Designators">Word Designators</a>); if neither of these designators
|
||
is present, no history expansion occurs.</p>
|
||
<p>Input lines containing history expansions are echoed after being
|
||
expanded, but before any other expansions take place and before the
|
||
command is executed. It is this expanded form that is recorded as the
|
||
history event for later references.</p>
|
||
<p>History expansions do not nest.</p>
|
||
<p>By default, a history reference with no event designator refers to the
|
||
same event as any preceding history reference on that command line; if
|
||
it is the only history reference in a command, it refers to the previous
|
||
command. <span id="index-CSH_005fJUNKIE_005fHISTORY_002c-use-of"></span>
|
||
However, if the option CSH_JUNKIE_HISTORY is set, then every history
|
||
reference with no event specification <em>always</em> refers to the previous
|
||
command.</p>
|
||
<p>For example, ‘!’ is the event designator for the previous command, so
|
||
‘!!:1’ always refers to the first word of the previous command, and
|
||
‘!!$’ always refers to the last word of the previous command. With
|
||
CSH_JUNKIE_HISTORY set, then ‘!:1’ and ‘!$’ function in the same manner
|
||
as ‘!!:1’ and ‘!!$’, respectively. Conversely, if CSH_JUNKIE_HISTORY is
|
||
unset, then ‘!:1’ and ‘!$’ refer to the first and last words,
|
||
respectively, of the same event referenced by the nearest other history
|
||
reference preceding them on the current command line, or to the previous
|
||
command if there is no preceding reference.</p>
|
||
<p>The character sequence ‘^<code>foo</code>^<code>bar</code>’ (where ‘^’ is actually the second
|
||
character of the histchars parameter) repeats the last command,
|
||
replacing the string <code>foo</code> with <code>bar</code>. More precisely, the sequence
|
||
‘^<code>foo</code>^<code>bar</code>^’ is synonymous with ‘!!:s^<code>foo</code>^<code>bar</code>^’, hence other
|
||
modifiers (see <a href="#Modifiers">Modifiers</a>) may follow the final ‘^’. In
|
||
particular, ‘^<code>foo</code>^<code>bar</code>^:G’ performs a global substitution.</p>
|
||
<p>If the shell encounters the character sequence ‘!"’ in the input, the
|
||
history mechanism is temporarily disabled until the current list (see
|
||
<a href="Shell-Grammar.html#Shell-Grammar">Shell Grammar</a>) is fully parsed. The
|
||
‘!"’ is removed from the input, and any subsequent ‘!’ characters have
|
||
no special significance.</p>
|
||
<p><span id="index-fc_002c-use-of"></span></p>
|
||
<p>A less convenient but more comprehensible form of command history
|
||
support is provided by the fc builtin.</p>
|
||
<hr />
|
||
<p><span id="Event-Designators"></span> <span
|
||
id="Event-Designators-1"></span></p>
|
||
<h3 id="1412-event-designators"><a class="header" href="#1412-event-designators">14.1.2 Event Designators</a></h3>
|
||
<p><span id="index-history-event-designators"></span> <span
|
||
id="index-event-designators_002c-history"></span></p>
|
||
<p>An event designator is a reference to a command-line entry in the
|
||
history list. In the list below, remember that the initial ‘!’ in each
|
||
item may be changed to another character by setting the histchars
|
||
parameter.</p>
|
||
<p>!<br />
|
||
Start a history expansion, except when followed by a blank, newline, ‘=’
|
||
or ‘(’. If followed immediately by a word designator (<a href="#Word-Designators">Word
|
||
Designators</a>), this forms a history reference with no
|
||
event designator (<a href="#Overview">Overview</a>).</p>
|
||
<p>!!<br />
|
||
Refer to the previous command. By itself, this expansion repeats the
|
||
previous command.</p>
|
||
<p>!<code>n</code><br />
|
||
Refer to command-line <code>n</code>.</p>
|
||
<p>!-<code>n</code><br />
|
||
Refer to the current command-line minus <code>n</code>.</p>
|
||
<p>!<code>str</code><br />
|
||
Refer to the most recent command starting with <code>str</code>.</p>
|
||
<p>!?<code>str</code>[?]<br />
|
||
Refer to the most recent command containing <code>str</code>. The trailing ‘?’ is
|
||
necessary if this reference is to be followed by a modifier or followed
|
||
by any text that is not to be considered part of <code>str</code>.</p>
|
||
<p>!#<br />
|
||
Refer to the current command line typed in so far. The line is treated
|
||
as if it were complete up to and including the word before the one with
|
||
the ‘!#’ reference.</p>
|
||
<p>!{...}<br />
|
||
Insulate a history reference from adjacent characters (if necessary).</p>
|
||
<hr />
|
||
<p><span id="Word-Designators"></span> <span
|
||
id="Word-Designators-1"></span></p>
|
||
<h3 id="1413-word-designators"><a class="header" href="#1413-word-designators">14.1.3 Word Designators</a></h3>
|
||
<p><span id="index-history-word-designators"></span> <span
|
||
id="index-word-designators_002c-history"></span></p>
|
||
<p>A word designator indicates which word or words of a given command line
|
||
are to be included in a history reference. A ‘:’ usually separates the
|
||
event specification from the word designator. It may be omitted only if
|
||
the word designator begins with a ‘^’, ‘$’, ‘*’, ‘-’ or ‘%’. Word
|
||
designators include:</p>
|
||
<p>0<br />
|
||
The first input word (command).</p>
|
||
<p><code>n</code><br />
|
||
The <code>n</code>th argument.</p>
|
||
<p>^<br />
|
||
The first argument. That is, 1.</p>
|
||
<p>$<br />
|
||
The last argument.</p>
|
||
<p>%<br />
|
||
The word matched by (the most recent) ?<code>str</code> search.</p>
|
||
<p><code>x</code>-<code>y</code><br />
|
||
A range of words; <code>x</code> defaults to 0.</p>
|
||
<p>*<br />
|
||
All the arguments, or a null value if there are none.</p>
|
||
<p><code>x</code>*<br />
|
||
Abbreviates ‘<code>x</code>-$’.</p>
|
||
<p><code>x</code>-<br />
|
||
Like ‘<code>x</code>*’ but omitting word $.</p>
|
||
<p>Note that a ‘%’ word designator works only when used in one of ‘!%’,
|
||
‘!:%’ or ‘!?<code>str</code>?:%’, and only when used after a !? expansion (possibly
|
||
in an earlier command). Anything else results in an error, although the
|
||
error may not be the most obvious one.</p>
|
||
<hr />
|
||
<p><span id="Modifiers"></span> <span id="Modifiers-1"></span></p>
|
||
<h3 id="1414-modifiers"><a class="header" href="#1414-modifiers">14.1.4 Modifiers</a></h3>
|
||
<p><span id="index-modifiers"></span> <span
|
||
id="index-colon-modifiers"></span> <span
|
||
id="index-history-modifiers"></span> <span
|
||
id="index-globbing-modifiers"></span> <span
|
||
id="index-parameter-modifiers"></span></p>
|
||
<p>After the optional word designator, you can add a sequence of one or
|
||
more of the following modifiers, each preceded by a ‘:’. These modifiers
|
||
also work on the result of <em>filename generation</em> and <em>parameter
|
||
expansion</em>, except where noted.</p>
|
||
<p>a<br />
|
||
Turn a file name into an absolute path: prepends the current directory,
|
||
if necessary; remove ‘.’ path segments; and remove ‘..’ path segments
|
||
and the segments that immediately precede them.</p>
|
||
<p>This transformation is agnostic about what is in the filesystem, i.e. is
|
||
on the logical, not the physical directory. It takes place in the same
|
||
manner as when changing directories when neither of the options
|
||
CHASE_DOTS or CHASE_LINKS is set. For example, ‘/before/here/../after’
|
||
is always transformed to ‘/before/after’, regardless of whether
|
||
‘/before/here’ exists or what kind of object (dir, file, symlink, etc.)
|
||
it is.</p>
|
||
<p>A<br />
|
||
Turn a file name into an absolute path as the ‘a’ modifier does, and
|
||
<em>then</em> pass the result through the realpath(3) library function to
|
||
resolve symbolic links.</p>
|
||
<p>Note: on systems that do not have a realpath(3) library function,
|
||
symbolic links are not resolved, so on those systems ‘a’ and ‘A’ are
|
||
equivalent.</p>
|
||
<p>Note: foo:A and realpath(foo) are different on some inputs. For
|
||
realpath(foo) semantics, see the ‘P‘ modifier.</p>
|
||
<p>c<br />
|
||
Resolve a command name into an absolute path by searching the command
|
||
path given by the PATH variable. This does not work for commands
|
||
containing directory parts. Note also that this does not usually work as
|
||
a glob qualifier unless a file of the same name is found in the current
|
||
directory.</p>
|
||
<p>e<br />
|
||
Remove all but the part of the filename extension following the ‘.’; see
|
||
the definition of the filename extension in the description of the r
|
||
modifier below. Note that according to that definition the result will
|
||
be empty if the string ends with a ‘.’.</p>
|
||
<p>h [ <code>digits</code> ]<br />
|
||
Remove a trailing pathname component, shortening the path by one
|
||
directory level: this is the ‘head’ of the pathname. This works like
|
||
‘dirname’. If the h is followed immediately (with no spaces or other
|
||
separator) by any number of decimal digits, and the value of the
|
||
resulting number is non-zero, that number of leading components is
|
||
preserved instead of the final component being removed. In an absolute
|
||
path the leading ‘/’ is the first component, so, for example, if
|
||
var=/my/path/to/something, then ${var:h3} substitutes /my/path.
|
||
Consecutive ‘/’s are treated the same as a single ‘/’. In parameter
|
||
substitution, digits may only be used if the expression is in braces, so
|
||
for example the short form substitution $var:h2 is treated as ${var:h}2,
|
||
not as ${var:h2}. No restriction applies to the use of digits in history
|
||
substitution or globbing qualifiers. If more components are requested
|
||
than are present, the entire path is substituted (so this does not
|
||
trigger a ‘failed modifier’ error in history expansion).</p>
|
||
<p>l<br />
|
||
Convert the words to all lowercase.</p>
|
||
<p>p<br />
|
||
Print the new command but do not execute it. Only works with history
|
||
expansion.</p>
|
||
<p>P<br />
|
||
Turn a file name into an absolute path, like realpath(3). The resulting
|
||
path will be absolute, will refer to the same directory entry as the
|
||
input filename, and none of its components will be symbolic links or
|
||
equal to ‘.’ or ‘..’.</p>
|
||
<p>Unlike realpath(3), non-existent trailing components are permitted and
|
||
preserved.</p>
|
||
<p>q<br />
|
||
Quote the substituted words, escaping further substitutions. Works with
|
||
history expansion and parameter expansion, though for parameters it is
|
||
only useful if the resulting text is to be re-evaluated such as by eval.</p>
|
||
<p>Q<br />
|
||
Remove one level of quotes from the substituted words.</p>
|
||
<p>r<br />
|
||
Remove a filename extension leaving the root name. Strings with no
|
||
filename extension are not altered. A filename extension is a ‘.’
|
||
followed by any number of characters (including zero) that are neither
|
||
‘.’ nor ‘/’ and that continue to the end of the string. For example, the
|
||
extension of ‘foo.orig.c’ is ‘.c’, and ‘dir.c/foo’ has no extension.</p>
|
||
<p>s/<code>l</code>/<code>r</code>[/]<br />
|
||
Substitute <code>r</code> for <code>l</code> as described below. The substitution is done only
|
||
for the first string that matches <code>l</code>. For arrays and for filename
|
||
generation, this applies to each word of the expanded text. See below
|
||
for further notes on substitutions.</p>
|
||
<p>The forms ‘gs/<code>l</code>/<code>r</code>’ and ‘s/<code>l</code>/<code>r</code>/:G’ perform global substitution,
|
||
i.e. substitute every occurrence of <code>r</code> for <code>l</code>. Note that the g or :G
|
||
must appear in exactly the position shown.</p>
|
||
<p>See further notes on this form of substitution below.</p>
|
||
<p>&<br />
|
||
Repeat the previous s substitution. Like s, may be preceded immediately
|
||
by a g. In parameter expansion the & must appear inside braces, and in
|
||
filename generation it must be quoted with a backslash.</p>
|
||
<p>t [ <code>digits</code> ]<br />
|
||
Remove all leading pathname components, leaving the final component
|
||
(tail). This works like ‘basename’. Any trailing slashes are first
|
||
removed. Decimal digits are handled as described above for (h), but in
|
||
this case that number of trailing components is preserved instead of the
|
||
default 1; 0 is treated the same as 1.</p>
|
||
<p>u<br />
|
||
Convert the words to all uppercase.</p>
|
||
<p>x<br />
|
||
Like q, but break into words at whitespace. Does not work with parameter
|
||
expansion.</p>
|
||
<p>The s/<code>l</code>/<code>r</code>/ substitution works as follows. By default the left-hand
|
||
side of substitutions are not patterns, but character strings. Any
|
||
character can be used as the delimiter in place of ‘/’. A backslash
|
||
quotes the delimiter character. The character ‘&’, in the
|
||
right-hand-side <code>r</code>, is replaced by the text from the left-hand-side
|
||
<code>l</code>. The ‘&’ can be quoted with a backslash. A null <code>l</code> uses the
|
||
previous string either from the previous <code>l</code> or from the contextual scan
|
||
string <code>s</code> from ‘!?<code>s</code>’. You can omit the rightmost delimiter if a
|
||
newline immediately follows <code>r</code>; the rightmost ‘?’ in a context scan can
|
||
similarly be omitted. Note the same record of the last <code>l</code> and <code>r</code> is
|
||
maintained across all forms of expansion.</p>
|
||
<p>Note that if a ‘&’ is used within glob qualifiers an extra backslash is
|
||
needed as a & is a special character in this case.</p>
|
||
<p>Also note that the order of expansions affects the interpretation of <code>l</code>
|
||
and <code>r</code>. When used in a history expansion, which occurs before any other
|
||
expansions, <code>l</code> and <code>r</code> are treated as literal strings (except as
|
||
explained for HIST_SUBST_PATTERN below). When used in parameter
|
||
expansion, the replacement of <code>r</code> into the parameter’s value is done
|
||
first, and then any additional process, parameter, command, arithmetic,
|
||
or brace references are applied, which may evaluate those substitutions
|
||
and expansions more than once if <code>l</code> appears more than once in the
|
||
starting value. When used in a glob qualifier, any substitutions or
|
||
expansions are performed once at the time the qualifier is parsed, even
|
||
before the ‘:s’ expression itself is divided into <code>l</code> and <code>r</code> sides.</p>
|
||
<p>If the option HIST_SUBST_PATTERN is set, <code>l</code> is treated as a pattern of
|
||
the usual form described in <a href="#Filename-Generation">Filename Generation</a>.
|
||
This can be used in all the places where modifiers are available; note,
|
||
however, that in globbing qualifiers parameter substitution has already
|
||
taken place, so parameters in the replacement string should be quoted to
|
||
ensure they are replaced at the correct time. Note also that complicated
|
||
patterns used in globbing qualifiers may need the extended glob
|
||
qualifier notation (#q:s/<code>...</code>/<code>...</code>/) in order for the shell to
|
||
recognize the expression as a glob qualifier. Further, note that bad
|
||
patterns in the substitution are not subject to the NO_BAD_PATTERN
|
||
option so will cause an error.</p>
|
||
<p>When HIST_SUBST_PATTERN is set, <code>l</code> may start with a # to indicate that
|
||
the pattern must match at the start of the string to be substituted, and
|
||
a % may appear at the start or after an # to indicate that the pattern
|
||
must match at the end of the string to be substituted. The % or # may be
|
||
quoted with two backslashes.</p>
|
||
<p>For example, the following piece of filename generation code with the
|
||
EXTENDED_GLOB option:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print -r -- *.c(#q:s/#%(#b)s(*).c/'S${match[1]}.C'/)
|
||
</code></pre>
|
||
</div>
|
||
<p>takes the expansion of *.c and applies the glob qualifiers in the
|
||
(#q<code>...</code>) expression, which consists of a substitution modifier anchored
|
||
to the start and end of each word (#%). This turns on backreferences
|
||
((#b)), so that the parenthesised subexpression is available in the
|
||
replacement string as ${match[1]}. The replacement string is quoted so
|
||
that the parameter is not substituted before the start of filename
|
||
generation.</p>
|
||
<p>The following f, F, w and W modifiers work only with parameter expansion
|
||
and filename generation. They are listed here to provide a single point
|
||
of reference for all modifiers.</p>
|
||
<p>f<br />
|
||
Repeats the immediately (without a colon) following modifier until the
|
||
resulting word doesn’t change any more.</p>
|
||
<p>F:<code>expr</code>:<br />
|
||
Like f, but repeats only <code>n</code> times if the expression <code>expr</code> evaluates to
|
||
<code>n</code>. Any character can be used instead of the ‘:’; if ‘(’, ‘[’, or ‘{’
|
||
is used as the opening delimiter, the closing delimiter should be ’)’,
|
||
‘]’, or ‘}’, respectively.</p>
|
||
<p>w<br />
|
||
Makes the immediately following modifier work on each word in the
|
||
string.</p>
|
||
<p>W:<code>sep</code>:<br />
|
||
Like w but words are considered to be the parts of the string that are
|
||
separated by <code>sep</code>. Any character can be used instead of the ‘:’;
|
||
opening parentheses are handled specially, see above.</p>
|
||
<hr />
|
||
<p><span id="Process-Substitution"></span> <span
|
||
id="Process-Substitution-1"></span></p>
|
||
<h2 id="142-process-substitution"><a class="header" href="#142-process-substitution">14.2 Process Substitution</a></h2>
|
||
<p><span id="index-process-substitution"></span> <span
|
||
id="index-substitution_002c-process"></span></p>
|
||
<p>Each part of a command argument that takes the form ‘<(<code>list</code>)’,
|
||
‘>(<code>list</code>)’ or ‘=(<code>list</code>)’ is subject to process substitution. The
|
||
expression may be preceded or followed by other strings except that, to
|
||
prevent clashes with commonly occurring strings and patterns, the last
|
||
form must occur at the start of a command argument, and the forms are
|
||
only expanded when first parsing command or assignment arguments.
|
||
Process substitutions may be used following redirection operators; in
|
||
this case, the substitution must appear with no trailing string.</p>
|
||
<p>Note that ‘<<(<code>list</code>)’ is not a special syntax; it is equivalent to
|
||
‘< <(<code>list</code>)’, redirecting standard input from the result of process
|
||
substitution. Hence all the following documentation applies. The second
|
||
form (with the space) is recommended for clarity.</p>
|
||
<p>In the case of the < or > forms, the shell runs the commands in <code>list</code>
|
||
as a subprocess of the job executing the shell command line. If the
|
||
system supports the /dev/fd mechanism, the command argument is the name
|
||
of the device file corresponding to a file descriptor; otherwise, if the
|
||
system supports named pipes (FIFOs), the command argument will be a
|
||
named pipe. If the form with > is selected then writing on this special
|
||
file will provide input for <code>list</code>. If < is used, then the file passed
|
||
as an argument will be connected to the output of the <code>list</code> process.
|
||
For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">paste <(cut -f1 file1) <(cut -f3 file2) |
|
||
tee >(process1) >(process2) >/dev/null
|
||
</code></pre>
|
||
</div>
|
||
<p>cuts fields 1 and 3 from the files <code>file1</code> and <code>file2</code> respectively,
|
||
pastes the results together, and sends it to the processes <code>process1</code>
|
||
and <code>process2</code>.</p>
|
||
<p>If =(<code>...</code>) is used instead of <(<code>...</code>), then the file passed as an
|
||
argument will be the name of a temporary file containing the output of
|
||
the <code>list</code> process. This may be used instead of the < form for a
|
||
program that expects to lseek (see lseek(2)) on the input file.</p>
|
||
<p>There is an optimisation for substitutions of the form =(<<<<code>arg</code>),
|
||
where <code>arg</code> is a single-word argument to the here-string redirection
|
||
<<<. This form produces a file name containing the value of <code>arg</code>
|
||
after any substitutions have been performed. This is handled entirely
|
||
within the current shell. This is effectively the reverse of the special
|
||
form $(<<code>arg</code>) which treats <code>arg</code> as a file name and replaces it with
|
||
the file’s contents.</p>
|
||
<p>The = form is useful as both the /dev/fd and the named pipe
|
||
implementation of <(<code>...</code>) have drawbacks. In the former case, some
|
||
programmes may automatically close the file descriptor in question
|
||
before examining the file on the command line, particularly if this is
|
||
necessary for security reasons such as when the programme is running
|
||
setuid. In the second case, if the programme does not actually open the
|
||
file, the subshell attempting to read from or write to the pipe will (in
|
||
a typical implementation, different operating systems may have different
|
||
behaviour) block for ever and have to be killed explicitly. In both
|
||
cases, the shell actually supplies the information using a pipe, so that
|
||
programmes that expect to lseek (see lseek(2)) on the file will not
|
||
work.</p>
|
||
<p>Also note that the previous example can be more compactly and
|
||
efficiently written (provided the MULTIOS option is set) as:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">paste <(cut -f1 file1) <(cut -f3 file2) > >(process1) > >(process2)
|
||
</code></pre>
|
||
</div>
|
||
<p>The shell uses pipes instead of FIFOs to implement the latter two
|
||
process substitutions in the above example.</p>
|
||
<p>There is an additional problem with >(<code>process</code>); when this is attached
|
||
to an external command, the parent shell does not wait for <code>process</code> to
|
||
finish and hence an immediately following command cannot rely on the
|
||
results being complete. The problem and solution are the same as
|
||
described in the section <em>MULTIOS</em> in
|
||
<a href="Redirection.html#Redirection">Redirection</a>. Hence in a simplified
|
||
version of the example above:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">paste <(cut -f1 file1) <(cut -f3 file2) > >(process)
|
||
</code></pre>
|
||
</div>
|
||
<p>(note that no MULTIOS are involved), <code>process</code> will be run
|
||
asynchronously as far as the parent shell is concerned. The workaround
|
||
is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">{ paste <(cut -f1 file1) <(cut -f3 file2) } > >(process)
|
||
</code></pre>
|
||
</div>
|
||
<p>The extra processes here are spawned from the parent shell which will
|
||
wait for their completion.</p>
|
||
<p>Another problem arises any time a job with a substitution that requires
|
||
a temporary file is disowned by the shell, including the case where ‘&!’
|
||
or ‘&|’ appears at the end of a command containing a substitution. In
|
||
that case the temporary file will not be cleaned up as the shell no
|
||
longer has any memory of the job. A workaround is to use a subshell, for
|
||
example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">(mycmd =(myoutput)) &!
|
||
</code></pre>
|
||
</div>
|
||
<p>as the forked subshell will wait for the command to finish then remove
|
||
the temporary file.</p>
|
||
<p>A general workaround to ensure a process substitution endures for an
|
||
appropriate length of time is to pass it as a parameter to an anonymous
|
||
shell function (a piece of shell code that is run immediately with
|
||
function scope). For example, this code:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">() {
|
||
print File $1:
|
||
cat $1
|
||
} =(print This be the verse)
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs something resembling the following</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">File /tmp/zsh6nU0kS:
|
||
This be the verse
|
||
</code></pre>
|
||
</div>
|
||
<p>The temporary file created by the process substitution will be deleted
|
||
when the function exits.</p>
|
||
<hr />
|
||
<p><span id="Parameter-Expansion"></span> <span
|
||
id="Parameter-Expansion-1"></span></p>
|
||
<h2 id="143-parameter-expansion"><a class="header" href="#143-parameter-expansion">14.3 Parameter Expansion</a></h2>
|
||
<p><span id="index-parameter-expansion"></span> <span
|
||
id="index-expansion_002c-parameter"></span></p>
|
||
<p>The character ‘$’ is used to introduce parameter expansions. See
|
||
<a href="Parameters.html#Parameters">Parameters</a> for a description of
|
||
parameters, including arrays, associative arrays, and subscript notation
|
||
to access individual array elements.</p>
|
||
<p>Note in particular the fact that words of unquoted parameters are not
|
||
automatically split on whitespace unless the option SH_WORD_SPLIT is
|
||
set; see references to this option below for more details. This is an
|
||
important difference from other shells. However, as in other shells,
|
||
null words are elided from unquoted parameters’ expansions.</p>
|
||
<p>With default options, after the assignments:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">array=("first word" "" "third word")
|
||
scalar="only word"
|
||
</code></pre>
|
||
</div>
|
||
<p>then $array substitutes two words, ‘first word’ and ‘third word’, and
|
||
$scalar substitutes a single word ‘only word’. Note that second element
|
||
of array was elided. Scalar parameters can be elided too if their value
|
||
is null (empty). To avoid elision, use quoting as follows: "$scalar" for
|
||
scalars and "${array[@]}" or "${(@)array}" for arrays. (The last two
|
||
forms are equivalent.)</p>
|
||
<p>Parameter expansions can involve <em>flags</em>, as in ‘${(@kv)aliases}’, and
|
||
other operators, such as ‘${PREFIX:-"/usr/local"}’. Parameter expansions
|
||
can also be nested. These topics will be introduced below. The full
|
||
rules are complicated and are noted at the end.</p>
|
||
<p>In the expansions discussed below that require a pattern, the form of
|
||
the pattern is the same as that used for filename generation; see
|
||
<a href="#Filename-Generation">Filename Generation</a>. Note that these patterns,
|
||
along with the replacement text of any substitutions, are themselves
|
||
subject to parameter expansion, command substitution, and arithmetic
|
||
expansion. In addition to the following operations, the colon modifiers
|
||
described in <a href="#Modifiers">Modifiers</a> in <a href="#History-Expansion">History
|
||
Expansion</a> can be applied: for example,
|
||
${i:s/foo/bar/} performs string substitution on the expansion of
|
||
parameter $i.</p>
|
||
<p>In the following descriptions, ‘<code>word</code>’ refers to a single word
|
||
substituted on the command line, not necessarily a space delimited word.</p>
|
||
<p>${<code>name</code>}<br />
|
||
The value, if any, of the parameter <code>name</code> is substituted. The braces
|
||
are required if the expansion is to be followed by a letter, digit, or
|
||
underscore that is not to be interpreted as part of <code>name</code>. In addition,
|
||
more complicated forms of substitution usually require the braces to be
|
||
present; exceptions, which only apply if the option KSH_ARRAYS is not
|
||
set, are a single subscript or any colon modifiers appearing after the
|
||
name, or any of the characters ‘^’, ‘=’, ‘~’, ‘#’ or ‘+’ appearing
|
||
before the name, all of which work with or without braces.</p>
|
||
<p>If <code>name</code> is an array parameter, and the KSH_ARRAYS option is not set,
|
||
then the value of each element of <code>name</code> is substituted, one element per
|
||
word. Otherwise, the expansion results in one word only; with
|
||
KSH_ARRAYS, this is the first element of an array. No field splitting is
|
||
done on the result unless the SH_WORD_SPLIT option is set. See also the
|
||
flags = and s:<code>string</code>:.</p>
|
||
<p>${+<code>name</code>}<br />
|
||
If <code>name</code> is the name of a set parameter ‘1’ is substituted, otherwise
|
||
‘0’ is substituted.</p>
|
||
<p>${<code>name</code>-<code>word</code>}<br />
|
||
${<code>name</code>:-<code>word</code>}<br />
|
||
If <code>name</code> is set, or in the second form is non-null, then substitute its
|
||
value; otherwise substitute <code>word</code>. In the second form <code>name</code> may be
|
||
omitted, in which case <code>word</code> is always substituted.</p>
|
||
<p>${<code>name</code>+<code>word</code>}<br />
|
||
${<code>name</code>:+<code>word</code>}<br />
|
||
If <code>name</code> is set, or in the second form is non-null, then substitute
|
||
<code>word</code>; otherwise substitute nothing.</p>
|
||
<p>${<code>name</code>=<code>word</code>}<br />
|
||
${<code>name</code>:=<code>word</code>}<br />
|
||
${<code>name</code>::=<code>word</code>}<br />
|
||
In the first form, if <code>name</code> is unset then set it to <code>word</code>; in the
|
||
second form, if <code>name</code> is unset or null then set it to <code>word</code>; and in
|
||
the third form, unconditionally set <code>name</code> to <code>word</code>. In all forms, the
|
||
value of the parameter is then substituted.</p>
|
||
<p>${<code>name</code>?<code>word</code>}<br />
|
||
${<code>name</code>:?<code>word</code>}<br />
|
||
In the first form, if <code>name</code> is set, or in the second form if <code>name</code> is
|
||
both set and non-null, then substitute its value; otherwise, print
|
||
<code>word</code> and exit from the shell. Interactive shells instead return to the
|
||
prompt. If <code>word</code> is omitted, then a standard message is printed.</p>
|
||
<p>In any of the above expressions that test a variable and substitute an
|
||
alternate <code>word</code>, note that you can use standard shell quoting in the
|
||
<code>word</code> value to selectively override the splitting done by the
|
||
SH_WORD_SPLIT option and the = flag, but not splitting by the
|
||
s:<code>string</code>: flag.</p>
|
||
<p>In the following expressions, when <code>name</code> is an array and the
|
||
substitution is not quoted, or if the ‘(@)’ flag or the <code>name</code>[@]
|
||
syntax is used, matching and replacement is performed on each array
|
||
element separately.</p>
|
||
<p>${<code>name</code>#<code>pattern</code>}<br />
|
||
${<code>name</code>##<code>pattern</code>}<br />
|
||
If the <code>pattern</code> matches the beginning of the value of <code>name</code>, then
|
||
substitute the value of <code>name</code> with the matched portion deleted;
|
||
otherwise, just substitute the value of <code>name</code>. In the first form, the
|
||
smallest matching pattern is preferred; in the second form, the largest
|
||
matching pattern is preferred.</p>
|
||
<p>${<code>name</code>%<code>pattern</code>}<br />
|
||
${<code>name</code>%%<code>pattern</code>}<br />
|
||
If the <code>pattern</code> matches the end of the value of <code>name</code>, then substitute
|
||
the value of <code>name</code> with the matched portion deleted; otherwise, just
|
||
substitute the value of <code>name</code>. In the first form, the smallest matching
|
||
pattern is preferred; in the second form, the largest matching pattern
|
||
is preferred.</p>
|
||
<p>${<code>name</code>:#<code>pattern</code>}<br />
|
||
If the <code>pattern</code> matches the value of <code>name</code>, then substitute the empty
|
||
string; otherwise, just substitute the value of <code>name</code>. If <code>name</code> is an
|
||
array the matching array elements are removed (use the ‘(M)’ flag to
|
||
remove the non-matched elements).</p>
|
||
<p>${<code>name</code>:|<code>arrayname</code>}<br />
|
||
If <code>arrayname</code> is the name (N.B., not contents) of an array variable,
|
||
then any elements contained in <code>arrayname</code> are removed from the
|
||
substitution of <code>name</code>. If the substitution is scalar, either because
|
||
<code>name</code> is a scalar variable or the expression is quoted, the elements of
|
||
<code>arrayname</code> are instead tested against the entire expression.</p>
|
||
<p>${<code>name</code>:*<code>arrayname</code>}<br />
|
||
Similar to the preceding substitution, but in the opposite sense, so
|
||
that entries present in both the original substitution and as elements
|
||
of <code>arrayname</code> are retained and others removed.</p>
|
||
<p>${<code>name</code>:^<code>arrayname</code>}<br />
|
||
${<code>name</code>:^^<code>arrayname</code>}<br />
|
||
Zips two arrays, such that the output array is twice as long as the
|
||
shortest (longest for ‘:^^’) of name and arrayname, with the elements
|
||
alternatingly being picked from them. For ‘:^’, if one of the input
|
||
arrays is longer, the output will stop when the end of the shorter array
|
||
is reached. Thus,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">a=(1 2 3 4); b=(a b); print ${a:^b}
|
||
</code></pre>
|
||
</div>
|
||
<p>will output ‘1 a 2 b’. For ‘:^^’, then the input is repeated until all
|
||
of the longer array has been used up and the above will output ‘1 a 2 b
|
||
3 a 4 b’.</p>
|
||
<p>Either or both inputs may be a scalar, they will be treated as an array
|
||
of length 1 with the scalar as the only element. If either array is
|
||
empty, the other array is output with no extra elements inserted.</p>
|
||
<p>Currently the following code will output ‘a b’ and ‘1’ as two separate
|
||
elements, which can be unexpected. The second print provides a
|
||
workaround which should continue to work if this is changed.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">a=(a b); b=(1 2); print -l "${a:^b}"; print -l "${${a:^b}}"
|
||
</code></pre>
|
||
</div>
|
||
<p>${<code>name</code>:<code>offset</code>}<br />
|
||
${<code>name</code>:<code>offset</code>:<code>length</code>}<br />
|
||
This syntax gives effects similar to parameter subscripting in the form
|
||
$<code>name</code>[<code>start</code>,<code>end</code>], but is compatible with other shells; note that
|
||
both <code>offset</code> and <code>length</code> are interpreted differently from the
|
||
components of a subscript.</p>
|
||
<p>If <code>offset</code> is non-negative, then if the variable <code>name</code> is a scalar
|
||
substitute the contents starting <code>offset</code> characters from the first
|
||
character of the string, and if <code>name</code> is an array substitute elements
|
||
starting <code>offset</code> elements from the first element. If <code>length</code> is given,
|
||
substitute that many characters or elements, otherwise the entire rest
|
||
of the scalar or array.</p>
|
||
<p>A positive <code>offset</code> is always treated as the offset of a character or
|
||
element in <code>name</code> from the first character or element of the array (this
|
||
is different from native zsh subscript notation). Hence 0 refers to the
|
||
first character or element regardless of the setting of the option
|
||
KSH_ARRAYS.</p>
|
||
<p>A negative offset counts backwards from the end of the scalar or array,
|
||
so that -1 corresponds to the last character or element, and so on.</p>
|
||
<p>When positive, <code>length</code> counts from the <code>offset</code> position toward the end
|
||
of the scalar or array. When negative, <code>length</code> counts back from the
|
||
end. If this results in a position smaller than <code>offset</code>, a diagnostic
|
||
is printed and nothing is substituted.</p>
|
||
<p>The option MULTIBYTE is obeyed, i.e. the offset and length count
|
||
multibyte characters where appropriate.</p>
|
||
<p><code>offset</code> and <code>length</code> undergo the same set of shell substitutions as for
|
||
scalar assignment; in addition, they are then subject to arithmetic
|
||
evaluation. Hence, for example</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print ${foo:3}
|
||
print ${foo: 1 + 2}
|
||
print ${foo:$(( 1 + 2))}
|
||
print ${foo:$(echo 1 + 2)}
|
||
</code></pre>
|
||
</div>
|
||
<p>all have the same effect, extracting the string starting at the fourth
|
||
character of $foo if the substitution would otherwise return a scalar,
|
||
or the array starting at the fourth element if $foo would return an
|
||
array. Note that with the option KSH_ARRAYS $foo always returns a scalar
|
||
(regardless of the use of the offset syntax) and a form such as
|
||
${foo[*]:3} is required to extract elements of an array named foo.</p>
|
||
<p>If <code>offset</code> is negative, the - may not appear immediately after the : as
|
||
this indicates the ${<code>name</code>:-<code>word</code>} form of substitution. Instead, a
|
||
space may be inserted before the -. Furthermore, neither <code>offset</code> nor
|
||
<code>length</code> may begin with an alphabetic character or & as these are used
|
||
to indicate history-style modifiers. To substitute a value from a
|
||
variable, the recommended approach is to precede it with a $ as this
|
||
signifies the intention (parameter substitution can easily be rendered
|
||
unreadable); however, as arithmetic substitution is performed, the
|
||
expression ${var: offs} does work, retrieving the offset from $offs.</p>
|
||
<p>For further compatibility with other shells there is a special case for
|
||
array offset 0. This usually accesses the first element of the array.
|
||
However, if the substitution refers to the positional parameter array,
|
||
e.g. $@ or $*, then offset 0 instead refers to $0, offset 1 refers to
|
||
$1, and so on. In other words, the positional parameter array is
|
||
effectively extended by prepending $0. Hence ${*:0:1} substitutes $0
|
||
and ${*:1:1} substitutes $1.</p>
|
||
<p>${<code>name</code>/<code>pattern</code>/<code>repl</code>}<br />
|
||
${<code>name</code>//<code>pattern</code>/<code>repl</code>}<br />
|
||
${<code>name</code>:/<code>pattern</code>/<code>repl</code>}<br />
|
||
Replace the longest possible match of <code>pattern</code> in the expansion of
|
||
parameter <code>name</code> by string <code>repl</code>. The first form replaces just the
|
||
first occurrence, the second form all occurrences, and the third form
|
||
replaces only if <code>pattern</code> matches the entire string. Both <code>pattern</code> and
|
||
<code>repl</code> are subject to double-quoted substitution, so that expressions
|
||
like ${name/$opat/$npat} will work, but obey the usual rule that pattern
|
||
characters in $opat are not treated specially unless either the option
|
||
GLOB_SUBST is set, or $opat is instead substituted as ${~opat}.</p>
|
||
<p>The <code>pattern</code> may begin with a ‘#’, in which case the <code>pattern</code> must
|
||
match at the start of the string, or ‘%’, in which case it must match at
|
||
the end of the string, or ‘#%’ in which case the <code>pattern</code> must match
|
||
the entire string. The <code>repl</code> may be an empty string, in which case the
|
||
final ‘/’ may also be omitted. To quote the final ‘/’ in other cases it
|
||
should be preceded by a single backslash; this is not necessary if the
|
||
‘/’ occurs inside a substituted parameter. Note also that the ‘#’, ‘%’
|
||
and ‘#% are not active if they occur inside a substituted parameter,
|
||
even at the start.</p>
|
||
<p>If, after quoting rules apply, ${<code>name</code>} expands to an array, the
|
||
replacements act on each element individually. Note also the effect of
|
||
the I and S parameter expansion flags below; however, the flags M, R, B,
|
||
E and N are not useful.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">foo="twinkle twinkle little star" sub="t*e" rep="spy"
|
||
print ${foo//${~sub}/$rep}
|
||
print ${(S)foo//${~sub}/$rep}
|
||
</code></pre>
|
||
</div>
|
||
<p>Here, the ‘~’ ensures that the text of $sub is treated as a pattern
|
||
rather than a plain string. In the first case, the longest match for
|
||
t*e is substituted and the result is ‘spy star’, while in the second
|
||
case, the shortest matches are taken and the result is ‘spy spy lispy
|
||
star’.</p>
|
||
<p>${#<code>spec</code>}<br />
|
||
If <code>spec</code> is one of the above substitutions, substitute the length in
|
||
characters of the result instead of the result itself. If <code>spec</code> is an
|
||
array expression, substitute the number of elements of the result. This
|
||
has the side-effect that joining is skipped even in quoted forms, which
|
||
may affect other sub-expressions in <code>spec</code>. Note that ‘^’, ‘=’, and
|
||
‘~’, below, must appear to the left of ‘#’ when these forms are
|
||
combined.</p>
|
||
<p>If the option POSIX_IDENTIFIERS is not set, and <code>spec</code> is a simple name,
|
||
then the braces are optional; this is true even for special parameters
|
||
so e.g. $#- and $#* take the length of the string $- and the array $*
|
||
respectively. If POSIX_IDENTIFIERS is set, then braces are required for
|
||
the # to be treated in this fashion.</p>
|
||
<p>${^<code>spec</code>}<br />
|
||
${^^<code>spec</code>}<br />
|
||
<span id="index-RC_005fEXPAND_005fPARAM_002c-toggle"></span> <span
|
||
id="index-array-expansion-style_002c-rc"></span> <span
|
||
id="index-rc_002c-array-expansion-style"></span></p>
|
||
<p>Turn on the RC_EXPAND_PARAM option for the evaluation of <code>spec</code>; if the
|
||
‘^’ is doubled, turn it off. When this option is set, array expansions
|
||
of the form <code>foo</code>${<code>xx</code>}<code>bar</code>, where the parameter <code>xx</code> is set to
|
||
(<code>a b c</code>), are substituted with ‘<code>fooabar foobbar foocbar</code>’ instead of
|
||
the default ‘<code>fooa b cbar</code>’. Note that an empty array will therefore
|
||
cause all arguments to be removed.</p>
|
||
<p>Internally, each such expansion is converted into the equivalent list
|
||
for brace expansion. E.g., ${^var} becomes {$var[1],$var[2],...},
|
||
and is processed as described in <a href="#Brace-Expansion">Brace Expansion</a>
|
||
below: note, however, the expansion happens immediately, with any
|
||
explicit brace expansion happening later. If word splitting is also in
|
||
effect the $var[<code>N</code>] may themselves be split into different list
|
||
elements.</p>
|
||
<p>${=<code>spec</code>}<br />
|
||
${==<code>spec</code>}<br />
|
||
<span id="index-SH_005fWORD_005fSPLIT_002c-toggle"></span> <span
|
||
id="index-field-splitting_002c-sh-style_002c-parameter"></span> <span
|
||
id="index-sh_002c-field-splitting-style_002c-parameter"></span></p>
|
||
<p>Perform word splitting using the rules for SH_WORD_SPLIT during the
|
||
evaluation of <code>spec</code>, but regardless of whether the parameter appears in
|
||
double quotes; if the ‘=’ is doubled, turn it off. <span
|
||
id="index-IFS_002c-use-of"></span> This forces parameter expansions to
|
||
be split into separate words before substitution, using IFS as a
|
||
delimiter. This is done by default in most other shells.</p>
|
||
<p>Note that splitting is applied to <code>word</code> in the assignment forms of
|
||
<code>spec</code> <em>before</em> the assignment to <code>name</code> is performed. This affects the
|
||
result of array assignments with the A flag.</p>
|
||
<p>${~<code>spec</code>}<br />
|
||
${~~<code>spec</code>}<br />
|
||
<span id="index-GLOB_005fSUBST_002c-toggle"></span></p>
|
||
<p>Turn on the GLOB_SUBST option for the evaluation of <code>spec</code>; if the ‘~’
|
||
is doubled, turn it off. When this option is set, the string resulting
|
||
from the expansion will be interpreted as a pattern anywhere that is
|
||
possible, such as in filename expansion and filename generation and
|
||
pattern-matching contexts like the right hand side of the ‘=’ and ‘!=’
|
||
operators in conditions.</p>
|
||
<p>In nested substitutions, note that the effect of the ~ applies to the
|
||
result of the current level of substitution. A surrounding pattern
|
||
operation on the result may cancel it. Hence, for example, if the
|
||
parameter foo is set to *, ${~foo//\*/*.c} is substituted by the
|
||
pattern *.c, which may be expanded by filename generation, but
|
||
${${~foo}//\*/*.c} substitutes to the string *.c, which will not be
|
||
further expanded.</p>
|
||
<p>If a ${...} type parameter expression or a $(...) type command
|
||
substitution is used in place of <code>name</code> above, it is expanded first and
|
||
the result is used as if it were the value of <code>name</code>. Thus it is
|
||
possible to perform nested operations: ${${foo#head}%tail} substitutes
|
||
the value of $foo with both ‘head’ and ‘tail’ deleted. The form with
|
||
$(...) is often useful in combination with the flags described next; see
|
||
the examples below. Each <code>name</code> or nested ${...} in a parameter
|
||
expansion may also be followed by a subscript expression as described in
|
||
<a href="Parameters.html#Array-Parameters">Array Parameters</a>.</p>
|
||
<p>Note that double quotes may appear around nested expressions, in which
|
||
case only the part inside is treated as quoted; for example,
|
||
${(f)"$(foo)"} quotes the result of $(foo), but the flag ‘(f)’ (see
|
||
below) is applied using the rules for unquoted expansions. Note further
|
||
that quotes are themselves nested in this context; for example, in
|
||
"${(@f)"$(foo)"}", there are two sets of quotes, one surrounding the
|
||
whole expression, the other (redundant) surrounding the $(foo) as
|
||
before.</p>
|
||
<hr />
|
||
<p><span id="Parameter-Expansion-Flags"></span></p>
|
||
<h3 id="1431-parameter-expansion-flags"><a class="header" href="#1431-parameter-expansion-flags">14.3.1 Parameter Expansion Flags</a></h3>
|
||
<p><span id="index-parameter-expansion-flags"></span> <span
|
||
id="index-flags_002c-parameter-expansion"></span> <span
|
||
id="index-substitution_002c-parameter_002c-flags"></span></p>
|
||
<p>If the opening brace is directly followed by an opening parenthesis, the
|
||
string up to the matching closing parenthesis will be taken as a list of
|
||
flags. In cases where repeating a flag is meaningful, the repetitions
|
||
need not be consecutive; for example, ‘(q%q%q)’ means the same thing as
|
||
the more readable ‘(%%qqq)’. The following flags are supported:</p>
|
||
<h1 id=""><a class="header" href="#"></a></h1>
|
||
<p>Evaluate the resulting words as numeric expressions and interpret these
|
||
as character codes. Output the corresponding characters. Note that this
|
||
form is entirely distinct from use of the # without parentheses.</p>
|
||
<p>If the MULTIBYTE option is set and the number is greater than 127 (i.e.
|
||
not an ASCII character) it is treated as a Unicode character.</p>
|
||
<p>%<br />
|
||
Expand all % escapes in the resulting words in the same way as in
|
||
prompts (see <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>). If this flag is
|
||
given twice, full prompt expansion is done on the resulting words,
|
||
depending on the setting of the PROMPT_PERCENT, PROMPT_SUBST and
|
||
PROMPT_BANG options.</p>
|
||
<p>@<br />
|
||
In double quotes, array elements are put into separate words. E.g.,
|
||
‘"${(@)foo}"’ is equivalent to ‘"${foo[@]}"’ and ‘"${(@)foo[1,2]}"’
|
||
is the same as ‘"$foo[1]" "$foo[2]"’. This is distinct from <em>field
|
||
splitting</em> by the f, s or z flags, which still applies within each array
|
||
element.</p>
|
||
<p>A<br />
|
||
Convert the substitution into an array expression, even if it otherwise
|
||
would be scalar. This has lower precedence than subscripting, so one
|
||
level of nested expansion is required in order that subscripts apply to
|
||
array elements. Thus ${${(A)<code>name</code>}[1]} yields the full value of
|
||
<code>name</code> when <code>name</code> is scalar.</p>
|
||
<p>This assigns an array parameter with ‘${...=...}’, ‘${...:=...}’ or
|
||
‘${...::=...}’. If this flag is repeated (as in ‘AA’), assigns an
|
||
associative array parameter. Assignment is made before sorting or
|
||
padding; if field splitting is active, the <code>word</code> part is split before
|
||
assignment. The <code>name</code> part may be a subscripted range for ordinary
|
||
arrays; when assigning an associative array, the <code>word</code> part <em>must</em> be
|
||
converted to an array, for example by using ‘${(AA)=<code>name</code>=...}’ to
|
||
activate field splitting.</p>
|
||
<p>Surrounding context such as additional nesting or use of the value in a
|
||
scalar assignment may cause the array to be joined back into a single
|
||
string again.</p>
|
||
<p>a<br />
|
||
Sort in array index order; when combined with ‘O’ sort in reverse array
|
||
index order. Note that ‘a’ is therefore equivalent to the default but
|
||
‘Oa’ is useful for obtaining an array’s elements in reverse order.</p>
|
||
<p>b<br />
|
||
Quote with backslashes only characters that are special to pattern
|
||
matching. This is useful when the contents of the variable are to be
|
||
tested using GLOB_SUBST, including the ${~<code>...</code>} switch.</p>
|
||
<p>Quoting using one of the q family of flags does not work for this
|
||
purpose since quotes are not stripped from non-pattern characters by
|
||
GLOB_SUBST. In other words,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">pattern=${(q)str}
|
||
[[ $str = ${~pattern} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>works if $str is ‘a*b’ but not if it is ‘a b’, whereas</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">pattern=${(b)str}
|
||
[[ $str = ${~pattern} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>is always true for any possible value of $str.</p>
|
||
<p>c<br />
|
||
With ${#<code>name</code>}, count the total number of characters in an array, as if
|
||
the elements were concatenated with spaces between them. This is not a
|
||
true join of the array, so other expressions used with this flag may
|
||
have an effect on the elements of the array before it is counted.</p>
|
||
<p>C<br />
|
||
Capitalize the resulting words. ‘Words’ in this case refers to sequences
|
||
of alphanumeric characters separated by non-alphanumerics, <em>not</em> to
|
||
words that result from field splitting.</p>
|
||
<p>D<br />
|
||
Assume the string or array elements contain directories and attempt to
|
||
substitute the leading part of these by names. The remainder of the path
|
||
(the whole of it if the leading part was not substituted) is then quoted
|
||
so that the whole string can be used as a shell argument. This is the
|
||
reverse of ‘~’ substitution: see <a href="#Filename-Expansion">Filename
|
||
Expansion</a>.</p>
|
||
<p>e<br />
|
||
Perform single word shell expansions, namely <em>parameter expansion</em>,
|
||
<em>command substitution</em> and <em>arithmetic expansion</em>, on the result. Such
|
||
expansions can be nested but too deep recursion may have</p>
|
||
<p>f<br />
|
||
Split the result of the expansion at newlines. This is a shorthand for
|
||
‘ps:\n:’.</p>
|
||
<p>F<br />
|
||
Join the words of arrays together using newline as a separator. This is
|
||
a shorthand for ‘pj:\n:’.</p>
|
||
<p>g:<code>opts</code>:<br />
|
||
Process escape sequences like the echo builtin when no options are given
|
||
(g::). With the o option, octal escapes don’t take a leading zero. With
|
||
the c option, sequences like ‘^X’ are also processed. With the e option,
|
||
processes ‘\M-t’ and similar sequences like the print builtin. With
|
||
both of the o and e options, behaves like the print builtin except that
|
||
in none of these modes is ‘\c’ interpreted.</p>
|
||
<p>i<br />
|
||
Sort case-insensitively. May be combined with ‘n’ or ‘O’.</p>
|
||
<p>k<br />
|
||
If <code>name</code> refers to an associative array, substitute the <em>keys</em> (element
|
||
names) rather than the values of the elements. Used with subscripts
|
||
(including ordinary arrays), force indices or keys to be substituted
|
||
even if the subscript form refers to values. However, this flag may not
|
||
be combined with subscript ranges. With the KSH_ARRAYS option a
|
||
subscript ‘[*]’ or ‘[@]’ is needed to operate on the whole array,
|
||
as usual.</p>
|
||
<p>L<br />
|
||
Convert all letters in the result to lower case.</p>
|
||
<p>n<br />
|
||
Sort decimal integers numerically; if the first differing characters of
|
||
two test strings are not digits, sorting is lexical. ‘+’ and ‘-’ are not
|
||
treated specially; they are treated as any other non-digit. Integers
|
||
with more initial zeroes are sorted before those with fewer or none.
|
||
Hence the array ‘foo+24 foo1 foo02 foo2 foo3 foo20 foo23’ is sorted into
|
||
the order shown. May be combined with ‘i’ or ‘O’.</p>
|
||
<p>-<br />
|
||
As n, but a leading minus sign indicates a negative decimal integer. A
|
||
leading minus sign not followed by an integer does not trigger numeric
|
||
sorting. Note that ‘+’ signs are not handled specially (this may change
|
||
in the future).</p>
|
||
<p>o<br />
|
||
Sort the resulting words in ascending order; if this appears on its own
|
||
the sorting is lexical and case-sensitive (unless the locale renders it
|
||
case-insensitive). Sorting in ascending order is the default for other
|
||
forms of sorting, so this is ignored if combined with ‘a’, ‘i’, ‘n’ or
|
||
‘-’.</p>
|
||
<p>O<br />
|
||
Sort the resulting words in descending order; ‘O’ without ‘a’, ‘i’, ‘n’
|
||
or ‘-’ sorts in reverse lexical order. May be combined with ‘a’, ‘i’,
|
||
‘n’ or ‘-’ to reverse the order of sorting.</p>
|
||
<p>P<br />
|
||
This forces the value of the parameter <code>name</code> to be interpreted as a
|
||
further parameter name, whose value will be used where appropriate. Note
|
||
that flags set with one of the typeset family of commands (in particular
|
||
case transformations) are not applied to the value of <code>name</code> used in
|
||
this fashion.</p>
|
||
<p>If used with a nested parameter or command substitution, the result of
|
||
that will be taken as a parameter name in the same way. For example, if
|
||
you have ‘foo=bar’ and ‘bar=baz’, the strings ${(P)foo}, ${(P)${foo}},
|
||
and ${(P)$(echo bar)} will be expanded to ‘baz’.</p>
|
||
<p>Likewise, if the reference is itself nested, the expression with the
|
||
flag is treated as if it were directly replaced by the parameter name.
|
||
It is an error if this nested substitution produces an array with more
|
||
than one word. For example, if ‘name=assoc’ where the parameter assoc is
|
||
an associative array, then ‘${${(P)name}[elt]}’ refers to the element
|
||
of the associative subscripted ‘elt’.</p>
|
||
<p>q<br />
|
||
Quote characters that are special to the shell in the resulting words
|
||
with $’\<code>NNN</code>’ form, with separate quotes for each octet.</p>
|
||
<p>If this flag is given twice, the resulting words are quoted in single
|
||
quotes and if it is given three times, the words are quoted in double
|
||
characters is attempted. If the flag is given four times, the words are
|
||
quoted in single quotes preceded by a $. Note that in all three of these
|
||
forms quoting is done unconditionally, even if this does not change the
|
||
way the resulting string would be interpreted by the shell.</p>
|
||
<p>If a q- is given (only a single q may appear), a minimal form of single
|
||
quoting is used that only quotes the string if needed to protect special
|
||
characters. Typically this form gives the most readable output.</p>
|
||
<p>If a q+ is given, an extended form of minimal quoting is used that This
|
||
quoting is similar to that used by the output of values by the typeset
|
||
family of commands.</p>
|
||
<p>Q<br />
|
||
Remove one level of quotes from the resulting words.</p>
|
||
<p>t<br />
|
||
Use a string describing the type of the parameter where the value of the
|
||
parameter would usually appear. This string consists of keywords
|
||
separated by hyphens (‘-’). The first keyword in the string describes
|
||
the main type, it can be one of ‘scalar’, ‘array’, ‘integer’, ‘float’ or
|
||
‘association’. The other keywords describe the type in more detail:</p>
|
||
<p>local<br />
|
||
for local parameters</p>
|
||
<p>left<br />
|
||
for left justified parameters</p>
|
||
<p>right_blanks<br />
|
||
for right justified parameters with leading blanks</p>
|
||
<p>right_zeros<br />
|
||
for right justified parameters with leading zeros</p>
|
||
<p>lower<br />
|
||
for parameters whose value is converted to all lower case when it is
|
||
expanded</p>
|
||
<p>upper<br />
|
||
for parameters whose value is converted to all upper case when it is
|
||
expanded</p>
|
||
<p>readonly<br />
|
||
for readonly parameters</p>
|
||
<p>tag<br />
|
||
for tagged parameters</p>
|
||
<p>tied<br />
|
||
for parameters tied to another parameter in the manner of PATH
|
||
(colon-separated list) and path (array), whether these are special
|
||
parameters or user-defined with ‘typeset -T’</p>
|
||
<p>export<br />
|
||
for exported parameters</p>
|
||
<p>unique<br />
|
||
for arrays which keep only the first occurrence of duplicated values</p>
|
||
<p>hide<br />
|
||
for parameters with the ‘hide’ flag</p>
|
||
<p>hideval<br />
|
||
for parameters with the ‘hideval’ flag</p>
|
||
<p>special<br />
|
||
for special parameters defined by the shell</p>
|
||
<p>u<br />
|
||
Expand only the first occurrence of each unique word.</p>
|
||
<p>U<br />
|
||
Convert all letters in the result to upper case.</p>
|
||
<p>v<br />
|
||
Used with k, substitute (as two consecutive words) both the key and the
|
||
value of each associative array element. Used with subscripts, force
|
||
values to be substituted even if the subscript form refers to indices or
|
||
keys.</p>
|
||
<p>V<br />
|
||
Make any special characters in the resulting words visible.</p>
|
||
<p>w<br />
|
||
With ${#<code>name</code>}, count words in arrays or strings; the s flag may be
|
||
used to set a word delimiter.</p>
|
||
<p>W<br />
|
||
Similar to w with the difference that empty words between repeated
|
||
delimiters are also counted.</p>
|
||
<p>X<br />
|
||
With this flag, parsing errors occurring with the Q, e and # flags or
|
||
the pattern matching forms such as ‘${<code>name</code>#<code>pattern</code>}’ are reported.
|
||
Without the flag, errors are silently ignored.</p>
|
||
<p>z<br />
|
||
Split the result of the expansion into words using shell parsing to find
|
||
the words, i.e. taking into account any quoting in the value. Comments
|
||
are not treated specially but as ordinary strings, similar to
|
||
interactive shells with the INTERACTIVE_COMMENTS option unset (however,
|
||
see the Z flag below for related options)</p>
|
||
<p>Note that this is done very late, even later than the ‘(s)’ flag. So to
|
||
access single words in the result use nested expansions as in
|
||
‘${${(z)foo}[2]}’. Likewise, to remove the quotes in the resulting
|
||
words use ‘${(Q)${(z)foo}}’.</p>
|
||
<p>0<br />
|
||
Split the result of the expansion on null bytes. This is a shorthand for
|
||
‘ps:\0:’.</p>
|
||
<p>The following flags (except p) are followed by one or more arguments as
|
||
shown. Any character, or the matching pairs ‘(...)’, ‘{...}’, ‘[...]’,
|
||
or ‘<...>’, may be used in place of a colon as delimiters, but note
|
||
that when a flag takes more than one argument, a matched pair of
|
||
delimiters must surround each argument.</p>
|
||
<p>p<br />
|
||
Recognize the same escape sequences as the print builtin in string
|
||
arguments to any of the flags described below that follow this argument.</p>
|
||
<p>Alternatively, with this option string arguments may be in the form
|
||
$<code>var</code> in which case the value of the variable is substituted. Note this
|
||
form is strict; the string argument does not undergo general parameter
|
||
expansion.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">sep=:
|
||
val=a:b:c
|
||
print ${(ps.$sep.)val}
|
||
</code></pre>
|
||
</div>
|
||
<p>splits the variable on a :.</p>
|
||
<p>~<br />
|
||
Strings inserted into the expansion by any of the flags below are to be
|
||
treated as patterns. This applies to the string arguments of flags that
|
||
follow ~ within the same set of parentheses. Compare with ~ outside
|
||
parentheses, which forces the entire substituted string to be treated as
|
||
a pattern. Hence, for example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">[[ "?" = ${(~j.|.)array} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>treats ‘|’ as a pattern and succeeds if and only if $array contains the
|
||
string ‘?’ as an element. The ~ may be repeated to toggle the
|
||
behaviour; its effect only lasts to the end of the parenthesised group.</p>
|
||
<p>j:<code>string</code>:<br />
|
||
Join the words of arrays together using <code>string</code> as a separator. <span
|
||
id="index-SH_005fWORD_005fSPLIT_002c-use-of"></span> Note that this
|
||
occurs before field splitting by the s:<code>string</code>: flag or the
|
||
SH_WORD_SPLIT option.</p>
|
||
<p>l:<code>expr</code>::<code>string1</code>::<code>string2</code>:<br />
|
||
Pad the resulting words on the left. Each word will be truncated if
|
||
required and placed in a field <code>expr</code> characters wide.</p>
|
||
<p>The arguments :<code>string1</code>: and :<code>string2</code>: are optional; neither, the
|
||
first, or both may be given. Note that the same pairs of delimiters must
|
||
be used for each of the three arguments. The space to the left will be
|
||
filled with <code>string1</code> (concatenated as often as needed) or spaces if
|
||
<code>string1</code> is not given. If both <code>string1</code> and <code>string2</code> are given,
|
||
<code>string2</code> is inserted once directly to the left of each word, truncated
|
||
if necessary, before <code>string1</code> is used to produce any remaining padding.</p>
|
||
<p>If either of <code>string1</code> or <code>string2</code> is present but empty, i.e. there are
|
||
two delimiters together at that point, the first character of $IFS is
|
||
used instead.</p>
|
||
<p>If the MULTIBYTE option is in effect, the flag m may also be given, in
|
||
which case widths will be used for the calculation of padding; otherwise
|
||
individual multibyte characters are treated as occupying one unit of
|
||
width.</p>
|
||
<p>If the MULTIBYTE option is not in effect, each byte in the string is
|
||
treated as occupying one unit of width.</p>
|
||
<p>Control characters are always assumed to be one unit wide; this allows
|
||
the mechanism to be used for generating repetitions of control
|
||
characters.</p>
|
||
<p>m<br />
|
||
Only useful together with one of the flags l or r or with the # length
|
||
operator when the MULTIBYTE option is in effect. Use the character width
|
||
reported by the system in calculating how much of the string it occupies
|
||
or the overall unit, however certain Asian character sets and certain
|
||
special effects use wider characters; combining characters have zero
|
||
width. would actually be displayed will vary.</p>
|
||
<p>If the m is repeated, the character either counts zero (if it has effect
|
||
of counting the number of glyphs (visibly separate characters), except
|
||
for the case where combining characters themselves have non-zero width
|
||
(true in certain alphabets).</p>
|
||
<p>r:<code>expr</code>::<code>string1</code>::<code>string2</code>:<br />
|
||
As l, but pad the words on the right and insert <code>string2</code> immediately to
|
||
the right of the string to be padded.</p>
|
||
<p>Left and right padding may be used together. In this case the strategy
|
||
is to apply left padding to the first half width of each of the
|
||
resulting words, and right padding to the second half. If the string to
|
||
be padded has odd width the extra padding is applied on the left.</p>
|
||
<p>s:<code>string</code>:<br />
|
||
Force field splitting at the separator <code>string</code>. Note that a <code>string</code> of
|
||
two or more characters means that all of them must match in sequence;
|
||
this differs from the treatment of two or more characters in the IFS
|
||
parameter. See also the = flag and the SH_WORD_SPLIT option. An empty
|
||
string may also be given in which case every character will be a
|
||
separate element.</p>
|
||
<p>For historical reasons, the usual behaviour that empty array elements
|
||
are retained inside double quotes is disabled for arrays generated by
|
||
splitting; hence the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">line="one::three"
|
||
print -l "${(s.:.)line}"
|
||
</code></pre>
|
||
</div>
|
||
<p>produces two lines of output for one and three and elides the empty
|
||
field. To override this behaviour, supply the ‘(@)’ flag as well, i.e.
|
||
"${(@s.:.)line}".</p>
|
||
<p>Z:<code>opts</code>:<br />
|
||
As z but takes a combination of option letters between a following pair
|
||
of delimiter characters. With no options the effect is identical to z.
|
||
The following options are available:</p>
|
||
<p>(Z+c+)<br />
|
||
causes comments to be parsed as a string and retained; any field in the
|
||
resulting array beginning with an unquoted comment character is a
|
||
comment.</p>
|
||
<p>(Z+C+)<br />
|
||
causes comments to be parsed and removed. The rule for comments is
|
||
standard: anything between a word starting with the third character of
|
||
$HISTCHARS, default #, up to the next newline is a comment.</p>
|
||
<p>(Z+n+)<br />
|
||
causes unquoted newlines to be treated as ordinary whitespace, else they
|
||
are treated as if they are shell code delimiters and converted to
|
||
semicolons.</p>
|
||
<p>Options are combined within the same set of delimiters, e.g. (Z+Cn+).</p>
|
||
<p>_:<code>flags</code>:<br />
|
||
The underscore (_) flag is reserved for future use. As of this revision
|
||
of zsh, there are no valid <code>flags</code>; anything following an underscore,
|
||
other than an empty pair of delimiters, is treated as an error, and the
|
||
flag itself has no effect.</p>
|
||
<p>The following flags are meaningful with the ${...#...} or ${...%...}
|
||
forms. The S, I, and * flags may also be used with the ${.../...}
|
||
forms.</p>
|
||
<p>S<br />
|
||
With # or ##, search for the match that starts closest to the start of
|
||
the string (a ‘substring match’). Of all matches at a particular
|
||
position, # selects the shortest and ## the longest:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">% str="aXbXc"
|
||
% echo ${(S)str#X*}
|
||
abXc
|
||
% echo ${(S)str##X*}
|
||
a
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
<p>With % or %%, search for the match that starts closest to the end of the
|
||
string:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">% str="aXbXc"
|
||
% echo ${(S)str%X*}
|
||
aXbc
|
||
% echo ${(S)str%%X*}
|
||
aXb
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
<p>(Note that % and %% don’t search for the match that ends closest to the
|
||
end of the string, as one might expect.)</p>
|
||
<p>With substitution via ${.../...} or ${...//...}, specifies non-greedy
|
||
matching, i.e. that the shortest instead of the longest match should be
|
||
replaced:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">% str="abab"
|
||
% echo ${str/*b/_}
|
||
_
|
||
% echo ${(S)str/*b/_}
|
||
_ab
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
<p>I:<code>expr</code>:<br />
|
||
Search the <code>expr</code>th match (where <code>expr</code> evaluates to a number). This
|
||
only applies when searching for substrings, either with the S flag, or
|
||
with ${.../...} (only the <code>expr</code>th match is substituted) or ${...//...}
|
||
(all matches from the <code>expr</code>th on are substituted). The default is to
|
||
take the first match.</p>
|
||
<p>The <code>expr</code>th match is counted such that there is either one or zero
|
||
matches from each starting position in the string, although for global
|
||
substitution matches overlapping previous replacements are ignored. With
|
||
the ${...%...} and ${...%%...} forms, the starting position for the
|
||
match moves backwards from the end as the index increases, while with
|
||
the other forms it moves forward from the start.</p>
|
||
<p>Hence with the string</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">which switch is the right switch for Ipswich?
|
||
</code></pre>
|
||
</div>
|
||
<p>substitutions of the form ${(SI:<code>N</code>:)string#w*ch} as <code>N</code> increases from
|
||
1 will match and remove ‘which’, ‘witch’, ‘witch’ and ‘wich’; the form
|
||
using ‘##’ will match and remove ‘which switch is the right switch for
|
||
Ipswich’, ‘witch is the right switch for Ipswich’, ‘witch for Ipswich’
|
||
and ‘wich’. The form using ‘%’ will remove the same matches as for ‘#’,
|
||
but in reverse order, and the form using ‘%%’ will remove the same
|
||
matches as for ‘##’ in reverse order.</p>
|
||
<p>*<br />
|
||
<span id="index-EXTENDED_005fGLOB_002c-enable"></span></p>
|
||
<p>Enable EXTENDED_GLOB for substitution via ${.../...} or ${...//...}.
|
||
Note that ‘**’ does not disable extendedglob.</p>
|
||
<p>B<br />
|
||
Include the index of the beginning of the match in the result.</p>
|
||
<p>E<br />
|
||
Include the index one character past the end of the match in the result
|
||
(note this is inconsistent with other uses of parameter index).</p>
|
||
<p>M<br />
|
||
Include the matched portion in the result.</p>
|
||
<p>N<br />
|
||
Include the length of the match in the result.</p>
|
||
<p>R<br />
|
||
Include the unmatched portion in the result (the <em>R</em>est).</p>
|
||
<hr />
|
||
<p><span id="Rules"></span></p>
|
||
<h3 id="1432-rules"><a class="header" href="#1432-rules">14.3.2 Rules</a></h3>
|
||
<p><span id="index-parameter-expansion-rules"></span> <span
|
||
id="index-rules_002c-parameter-expansion"></span> <span
|
||
id="index-substitution_002c-parameter_002c-rules"></span></p>
|
||
<p>Here is a summary of the rules for substitution; this assumes that
|
||
braces are present around the substitution, i.e. ${<code>...</code>}. Some
|
||
particular examples are given below. Note that the Zsh Development Group
|
||
accepts <em>no responsibility</em> for any brain damage which may occur during
|
||
the reading of the following rules.</p>
|
||
<p>1. <em>Nested substitution</em><br />
|
||
If multiple nested ${<code>...</code>} forms are present, substitution is performed
|
||
from the inside outwards. At each level, the substitution takes account
|
||
of whether the current value is a scalar or an array, whether the whole
|
||
substitution is in double quotes, and what flags are supplied to the
|
||
current level of substitution, just as if the nested substitution were
|
||
the outermost. The flags are not propagated up to enclosing
|
||
substitutions; the nested substitution will return either a scalar or an
|
||
array as determined by the flags, possibly adjusted for quoting. All the
|
||
following steps take place where applicable at all levels of
|
||
substitution.</p>
|
||
<p>Note that, unless the ‘(P)’ flag is present, the flags and any
|
||
subscripts apply directly to the value of the nested substitution; for
|
||
example, the expansion ${${foo}} behaves exactly the same as ${foo}.
|
||
When the ‘(P)’ flag is present in a nested substitution, the other
|
||
substitution rules are applied to the value <em>before</em> it is interpreted
|
||
as a name, so ${${(P)foo}} may differ from ${(P)foo}.</p>
|
||
<p>At each nested level of substitution, the substituted words undergo all
|
||
forms of single-word substitution (i.e. not filename generation),
|
||
including command substitution, arithmetic expansion and filename
|
||
expansion (i.e. leading ~ and =). Thus, for example, ${${:-=cat}:h}
|
||
expands to the directory where the cat program resides. (Explanation:
|
||
the internal substitution has no parameter but a default value =cat,
|
||
which is expanded by filename expansion to a full path; the outer
|
||
substitution then applies the modifier :h and takes the directory part
|
||
of the path.)</p>
|
||
<p>2. <em>Internal parameter flags</em><br />
|
||
Any parameter flags set by one of the typeset family of commands, in
|
||
particular the -L, -R, -Z, -u and -l options for padding and
|
||
capitalization, are applied directly to the parameter value. Note these
|
||
flags are options to the command, e.g. ‘typeset -Z’; they are not the
|
||
same as the flags used within parameter substitutions.</p>
|
||
<p>At the outermost level of substitution, the ‘(P)’ flag (rule 4.) ignores
|
||
these transformations and uses the unmodified value of the parameter as
|
||
the name to be replaced. This is usually the desired behavior because
|
||
padding may make the value syntactically illegal as a parameter name,
|
||
but if capitalization changes are desired, use the ${${(P)foo}} form
|
||
(rule 25.).</p>
|
||
<p>3. <em>Parameter subscripting</em><br />
|
||
If the value is a raw parameter reference with a subscript, such as
|
||
${<code>var</code>[3]}, the effect of subscripting is applied directly to the
|
||
parameter. Subscripts are evaluated left to right; subsequent subscripts
|
||
apply to the scalar or array value yielded by the previous subscript.
|
||
Thus if var is an array, ${var[1][2]} is the second character of the
|
||
first word, but ${var[2,4][2]} is the entire third word (the second
|
||
word of the range of words two through four of the original array). Any
|
||
number of subscripts may appear. Flags such as ‘(k)’ and ‘(v)’ which
|
||
alter the result of subscripting are applied.</p>
|
||
<p>4. <em>Parameter name replacement</em><br />
|
||
At the outermost level of nesting only, the ‘(P)’ flag is applied. This
|
||
treats the value so far as a parameter name (which may include a
|
||
subscript expression) and replaces that with the corresponding value.
|
||
This replacement occurs later if the ‘(P)’ flag appears in a nested
|
||
substitution.</p>
|
||
<p>If the value so far names a parameter that has internal flags (rule 2.),
|
||
those internal flags are applied to the new value after replacement.</p>
|
||
<p>5. <em>Double-quoted joining</em><br />
|
||
If the value after this process is an array, and the substitution
|
||
appears in double quotes, and neither an ‘(@)’ flag nor a ‘#’ length
|
||
operator is present at the current level, then words of the value are
|
||
joined with the first character of the parameter $IFS, by default a
|
||
space, between each word (single word arrays are not modified). If the
|
||
‘(j)’ flag is present, that is used for joining instead of $IFS.</p>
|
||
<p>6. <em>Nested subscripting</em><br />
|
||
Any remaining subscripts (i.e. of a nested substitution) are evaluated
|
||
at this point, based on whether the value is an array or a scalar. As
|
||
with 3., multiple subscripts can appear. Note that ${foo[2,4][2]} is
|
||
thus equivalent to ${${foo[2,4]}[2]} and also to
|
||
"${${(@)foo[2,4]}[2]}" (the nested substitution returns an array in
|
||
both cases), but not to "${${foo[2,4]}[2]}" (the nested substitution
|
||
returns a scalar because of the quotes).</p>
|
||
<p>7. <em>Modifiers</em><br />
|
||
Any modifiers, as specified by a trailing ‘#’, ‘%’, ‘/’ (possibly
|
||
doubled) or by a set of modifiers of the form ‘:...’ (see
|
||
<a href="#Modifiers">Modifiers</a> in <a href="#History-Expansion">History Expansion</a>), are
|
||
applied to the words of the value at this level.</p>
|
||
<p>8. <em>Character evaluation</em><br />
|
||
Any ‘(#)’ flag is applied, evaluating the result so far numerically as a
|
||
character.</p>
|
||
<p>9. <em>Length</em><br />
|
||
Any initial ‘#’ modifier, i.e. in the form ${#<code>var</code>}, is used to
|
||
evaluate the length of the expression so far.</p>
|
||
<p>10. <em>Forced joining</em><br />
|
||
If the ‘(j)’ flag is present, or no ‘(j)’ flag is present but the string
|
||
is to be split as given by rule 11., and joining did not take place at
|
||
rule 5., any words in the value are joined together using the given
|
||
string or the first character of $IFS if none. Note that the ‘(F)’ flag
|
||
implicitly supplies a string for joining in this manner.</p>
|
||
<p>11. <em>Simple word splitting</em><br />
|
||
If one of the ‘(s)’ or ‘(f)’ flags are present, or the ‘=’ specifier was
|
||
present (e.g. ${=<code>var</code>}), the word is split on occurrences of the
|
||
specified string, or (for = with neither of the two flags present) any
|
||
of the characters in $IFS.</p>
|
||
<p>If no ‘(s)’, ‘(f)’ or ‘=’ was given, but the word is not quoted and the
|
||
option SH_WORD_SPLIT is set, the word is split on occurrences of any of
|
||
the characters in $IFS. Note this step, too, takes place at all levels
|
||
of a nested substitution.</p>
|
||
<p>12. <em>Case modification</em><br />
|
||
Any case modification from one of the flags ‘(L)’, ‘(U)’ or ‘(C)’ is
|
||
applied.</p>
|
||
<p>13. <em>Escape sequence replacement</em><br />
|
||
First any replacements from the ‘(g)’ flag are performed, then any
|
||
prompt-style formatting from the ‘(%)’ family of flags is applied.</p>
|
||
<p>14. <em>Quote application</em><br />
|
||
Any quoting or unquoting using ‘(q)’ and ‘(Q)’ and related flags is
|
||
applied.</p>
|
||
<p>15. <em>Directory naming</em><br />
|
||
Any directory name substitution using ‘(D)’ flag is applied.</p>
|
||
<p>16. <em>Visibility enhancement</em><br />
|
||
Any modifications to make characters visible using the ‘(V)’ flag are
|
||
applied.</p>
|
||
<p>17. <em>Lexical word splitting</em><br />
|
||
If the ’(z)’ flag or one of the forms of the ’(Z)’ flag is present, the
|
||
word is split as if it were a shell command line, so that quotation
|
||
marks and other metacharacters are used to decide what constitutes a
|
||
word. Note this form of splitting is entirely distinct from that
|
||
described by rule 11.: it does not use $IFS, and does not cause forced
|
||
joining.</p>
|
||
<p>18. <em>Uniqueness</em><br />
|
||
If the result is an array and the ‘(u)’ flag was present, duplicate
|
||
elements are removed from the array.</p>
|
||
<p>19. <em>Ordering</em><br />
|
||
If the result is still an array and one of the ‘(o)’ or ‘(O)’ flags was
|
||
present, the array is reordered.</p>
|
||
<p>20. RC_EXPAND_PARAM<br />
|
||
At this point the decision is made whether any resulting array elements
|
||
are to be combined element by element with surrounding text, as given by
|
||
either the RC_EXPAND_PARAM option or the ‘^’ flag.</p>
|
||
<p>21. <em>Re-evaluation</em><br />
|
||
Any ‘(e)’ flag is applied to the value, forcing it to be re-examined for
|
||
new parameter substitutions, but also for command and arithmetic
|
||
substitutions.</p>
|
||
<p>22. <em>Padding</em><br />
|
||
Any padding of the value by the ‘(l.<code>fill</code>.)’ or ‘(r.<code>fill</code>.)’ flags is
|
||
applied.</p>
|
||
<p>23. <em>Semantic joining</em><br />
|
||
In contexts where expansion semantics requires a single word to result,
|
||
all words are rejoined with the first character of IFS between. So in
|
||
‘${(P)${(f)lines}}’ the value of ${lines} is split at newlines, but then
|
||
must be joined again before the ‘(P)’ flag can be applied.</p>
|
||
<p>If a single word is not required, this rule is skipped.</p>
|
||
<p>24. <em>Empty argument removal</em><br />
|
||
If the substitution does not appear in double quotes, any resulting
|
||
zero-length argument, whether from a scalar or an element of an array,
|
||
is elided from the list of arguments inserted into the command line.</p>
|
||
<p>Strictly speaking, the removal happens later as the same happens with
|
||
other forms of substitution; the point to note here is simply that it
|
||
occurs after any of the above parameter operations.</p>
|
||
<p>25. <em>Nested parameter name replacement</em><br />
|
||
If the ‘(P)’ flag is present and rule 4. has not applied, the value so
|
||
far is treated as a parameter name (which may include a subscript
|
||
expression) and replaced with the corresponding value, with internal
|
||
flags (rule 2.) applied to the new value.</p>
|
||
<hr />
|
||
<p><span id="Examples"></span></p>
|
||
<h3 id="1433-examples"><a class="header" href="#1433-examples">14.3.3 Examples</a></h3>
|
||
<p><span id="index-parameter-expansion_002c-examples"></span></p>
|
||
<p>The flag f is useful to split a double-quoted substitution line by line.
|
||
For example, ${(f)"$(<<code>file</code>)"} substitutes the contents of <code>file</code>
|
||
divided so that each line is an element of the resulting array. Compare
|
||
this with the effect of $(<<code>file</code>) alone, which divides the file up by
|
||
words, or the same inside double quotes, which makes the entire content
|
||
of the file a single string.</p>
|
||
<p>The following illustrates the rules for nested parameter expansions.
|
||
Suppose that $foo contains the array (bar baz):</p>
|
||
<p>"${(@)${foo}[1]}"<br />
|
||
This produces the result b. First, the inner substitution "${foo}",
|
||
which has no array (@) flag, produces a single word result "bar baz".
|
||
The outer substitution "${(@)...[1]}" detects that this is a scalar,
|
||
so that (despite the ‘(@)’ flag) the subscript picks the first
|
||
character.</p>
|
||
<p>"${${(@)foo}[1]}"<br />
|
||
This produces the result ‘bar’. In this case, the inner substitution
|
||
"${(@)foo}" produces the array ‘(bar baz)’. The outer substitution
|
||
"${...[1]}" detects that this is an array and picks the first word.
|
||
This is similar to the simple case "${foo[1]}".</p>
|
||
<p>As an example of the rules for word splitting and joining, suppose $foo
|
||
contains the array ‘(ax1 bx1)’. Then</p>
|
||
<p>${(s/x/)foo}<br />
|
||
produces the words ‘a’, ‘1 b’ and ‘1’.</p>
|
||
<p>${(j/x/s/x/)foo}<br />
|
||
produces ‘a’, ‘1’, ‘b’ and ‘1’.</p>
|
||
<p>${(s/x/)foo%%1*}<br />
|
||
produces ‘a’ and ‘ b’ (note the extra space). As substitution occurs
|
||
before either joining or splitting, the operation first generates the
|
||
modified array (ax bx), which is joined to give "ax bx", and then split
|
||
to give ‘a’, ‘ b’ and ‘’. The final empty string will then be elided, as
|
||
it is not in double quotes.</p>
|
||
<hr />
|
||
<p><span id="Command-Substitution"></span> <span
|
||
id="Command-Substitution-1"></span></p>
|
||
<h2 id="144-command-substitution"><a class="header" href="#144-command-substitution">14.4 Command Substitution</a></h2>
|
||
<p><span id="index-command-substitution"></span> <span
|
||
id="index-substitution_002c-command"></span></p>
|
||
<p>A command enclosed in parentheses preceded by a dollar sign, like
|
||
‘$(...)’, or quoted with grave accents, like ‘‘...‘’, is replaced with
|
||
its standard output, with any trailing newlines deleted. If the
|
||
substitution is not enclosed in double quotes, the output is broken into
|
||
words using the IFS parameter. <span
|
||
id="index-IFS_002c-use-of-1"></span></p>
|
||
<p>The substitution ‘$(cat <code>foo</code>)’ may be replaced by the faster
|
||
‘$(<<code>foo</code>)’. In this case <code>foo</code> undergoes single word shell expansions
|
||
(<em>parameter expansion</em>, <em>command substitution</em> and <em>arithmetic
|
||
expansion</em>), but not filename generation.</p>
|
||
<p>If the option GLOB_SUBST is set, the result of any unquoted command
|
||
substitution, including the special form just mentioned, is eligible for
|
||
filename generation.</p>
|
||
<hr />
|
||
<p><span id="Arithmetic-Expansion"></span> <span
|
||
id="Arithmetic-Expansion-1"></span></p>
|
||
<h2 id="145-arithmetic-expansion"><a class="header" href="#145-arithmetic-expansion">14.5 Arithmetic Expansion</a></h2>
|
||
<p><span id="index-arithmetic-expansion"></span> <span
|
||
id="index-expansion_002c-arithmetic"></span></p>
|
||
<p>A string of the form ‘$[<code>exp</code>]’ or ‘$((<code>exp</code>))’ is substituted with
|
||
the value of the arithmetic expression <code>exp</code>. <code>exp</code> is subjected to
|
||
<em>parameter expansion</em>, <em>command substitution</em> and <em>arithmetic expansion</em>
|
||
before it is evaluated. See <a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a>.</p>
|
||
<hr />
|
||
<p><span id="Brace-Expansion"></span> <span id="Brace-Expansion-1"></span></p>
|
||
<h2 id="146-brace-expansion"><a class="header" href="#146-brace-expansion">14.6 Brace Expansion</a></h2>
|
||
<p><span id="index-brace-expansion"></span> <span
|
||
id="index-expansion_002c-brace"></span></p>
|
||
<p>A string of the form ‘<code>foo</code>{<code>xx</code>,<code>yy</code>,<code>zz</code>}<code>bar</code>’ is expanded to the
|
||
individual words ‘<code>fooxxbar</code>’, ‘<code>fooyybar</code>’ and ‘<code>foozzbar</code>’.
|
||
Left-to-right order is preserved. This construct may be nested. Commas
|
||
may be quoted in order to include them literally in a word.</p>
|
||
<p>An expression of the form ‘{<code>n1</code>..<code>n2</code>}’, where <code>n1</code> and <code>n2</code> are
|
||
integers, is expanded to every number between <code>n1</code> and <code>n2</code> inclusive.
|
||
If either number begins with a zero, all the resulting numbers will be
|
||
padded with leading zeroes to that minimum width, but for negative
|
||
numbers the - character is also included in the width. If the numbers
|
||
are in decreasing order the resulting sequence will also be in
|
||
decreasing order.</p>
|
||
<p>An expression of the form ‘{<code>n1</code>..<code>n2</code>..<code>n3</code>}’, where <code>n1</code>, <code>n2</code>, and
|
||
<code>n3</code> are integers, is expanded as above, but only every <code>n3</code>th number
|
||
starting from <code>n1</code> is output. If <code>n3</code> is negative the numbers are output
|
||
in reverse order, this is slightly different from simply swapping <code>n1</code>
|
||
and <code>n2</code> in the case that the step <code>n3</code> doesn’t evenly divide the range.
|
||
Zero padding can be specified in any of the three numbers, specifying it
|
||
in the third can be useful to pad for example ‘{-99..100..01}’ which is
|
||
not possible to specify by putting a 0 on either of the first two
|
||
numbers (i.e. pad to two characters).</p>
|
||
<p>An expression of the form ‘{<code>c1</code>..<code>c2</code>}’, where <code>c1</code> and <code>c2</code> are single
|
||
characters (which may be multibyte characters), is expanded to every
|
||
character in the range from <code>c1</code> to <code>c2</code> in whatever character sequence
|
||
is used internally. For characters with code points below 128 this is US
|
||
ASCII (this is the only case most users will need). If any intervening
|
||
character is not If the character sequence is reversed, the output is in
|
||
reverse order, e.g. ‘{d..a}’ is substituted as ‘d c b a’.</p>
|
||
<p>If a brace expression matches none of the above forms, it is left
|
||
unchanged, unless the option BRACE_CCL (an abbreviation for ‘brace
|
||
character class’) is set. <span
|
||
id="index-BRACE_005fCCL_002c-use-of"></span> In that case, it is
|
||
expanded to a list of the individual characters between the braces
|
||
sorted into the order of the characters in the ASCII character set
|
||
(multibyte characters are not currently handled). The syntax is similar
|
||
to a [...] expression in filename generation: ‘-’ is treated specially
|
||
to denote a range of characters, but ‘^’ or ‘!’ as the first character
|
||
is treated normally. For example, ‘{abcdef0-9}’ expands to 16 words 0 1
|
||
2 3 4 5 6 7 8 9 a b c d e f.</p>
|
||
<p>Note that brace expansion is not part of filename generation (globbing);
|
||
an expression such as */{foo,bar} is split into two separate words
|
||
*/foo and */bar before filename generation takes place. In particular,
|
||
note that this is liable to produce a ‘no match’ error if <em>either</em> of
|
||
the two expressions does not match; this is to be contrasted with
|
||
*/(foo|bar), which is treated as a single pattern but otherwise has
|
||
similar effects.</p>
|
||
<p>To combine brace expansion with array expansion, see the ${^<code>spec</code>} form
|
||
described in <a href="#Parameter-Expansion">Parameter Expansion</a> above.</p>
|
||
<hr />
|
||
<p><span id="Filename-Expansion"></span> <span
|
||
id="Filename-Expansion-1"></span></p>
|
||
<h2 id="147-filename-expansion"><a class="header" href="#147-filename-expansion">14.7 Filename Expansion</a></h2>
|
||
<p><span id="index-filename-expansion"></span> <span
|
||
id="index-expansion_002c-filename"></span></p>
|
||
<p>Each word is checked to see if it begins with an unquoted ‘~’. If it
|
||
does, then the word up to a ‘/’, or the end of the word if there is no
|
||
‘/’, is checked to see if it can be substituted in one of the ways
|
||
described here. If so, then the ‘~’ and the checked portion are
|
||
replaced with the appropriate substitute value.</p>
|
||
<p>A ‘~’ by itself is replaced by the value of $HOME. A ‘~’ followed by a
|
||
‘+’ or a ‘-’ is replaced by current or previous working directory,
|
||
respectively.</p>
|
||
<p>A ‘~’ followed by a number is replaced by the directory at that
|
||
position in the directory stack. ‘~0’ is equivalent to ‘~+’, and ‘~1’
|
||
is the top of the stack. ‘~+’ followed by a number is replaced by the
|
||
directory at that position in the directory stack. ‘~+0’ is equivalent
|
||
to ‘~+’, and ‘~+1’ is the top of the stack. ‘~-’ followed by a number
|
||
is replaced by the directory that many positions from the bottom of the
|
||
stack. ‘~-0’ is the bottom of the stack. <span
|
||
id="index-PUSHD_005fMINUS_002c-use-of"></span> The PUSHD_MINUS option
|
||
exchanges the effects of ‘~+’ and ‘~-’ where they are followed by a
|
||
number.</p>
|
||
<hr />
|
||
<p><span id="Dynamic-named-directories"></span> <span
|
||
id="Dynamic-named-directories-1"></span></p>
|
||
<h3 id="1471-dynamic-named-directories"><a class="header" href="#1471-dynamic-named-directories">14.7.1 Dynamic named directories</a></h3>
|
||
<p><span id="index-directories_002c-named_002c-dynamic"></span> <span
|
||
id="index-named-directories_002c-dynamic"></span> <span
|
||
id="index-dynamic-named-directories"></span></p>
|
||
<p>If the function zsh_directory_name exists, or the shell variable
|
||
zsh_directory_name_functions exists and contains an array of function
|
||
names, then the functions are used to implement dynamic directory
|
||
naming. The functions are tried in order until one returns status zero,
|
||
so it is important that functions test whether they can handle the case
|
||
in question and return an appropriate status.</p>
|
||
<p>A ‘~’ followed by a string <code>namstr</code> in unquoted square brackets is
|
||
treated specially as a dynamic directory name. Note that the first
|
||
unquoted closing square bracket always terminates <code>namstr</code>. The shell
|
||
function is passed two arguments: the string n (for name) and <code>namstr</code>.
|
||
It should either set the array reply to a single element which is the
|
||
directory corresponding to the name and return status zero (executing an
|
||
assignment as the last statement is usually sufficient), or it should
|
||
return status non-zero. In the former case the element of reply is used
|
||
as the directory; in the latter case the substitution is deemed to have
|
||
failed. If all functions fail and the option NOMATCH is set, an error
|
||
results.</p>
|
||
<p>The functions defined as above are also used to see if a directory can
|
||
be turned into a name, for example when printing the directory stack or
|
||
when expanding %~ in prompts. In this case each function is passed two
|
||
arguments: the string d (for directory) and the candidate for dynamic
|
||
naming. The function should either return non-zero status, if the
|
||
directory cannot be named by the function, or it should set the array
|
||
reply to consist of two elements: the first is the dynamic name for the
|
||
directory (as would appear within ‘~[<code>...</code>]’), and the second is the
|
||
prefix length of the directory to be replaced. For example, if the trial
|
||
directory is /home/myname/src/zsh and the dynamic name for
|
||
/home/myname/src (which has 16 characters) is s, then the function sets</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">reply=(s 16)
|
||
</code></pre>
|
||
</div>
|
||
<p>The directory name so returned is compared with possible static names
|
||
for parts of the directory path, as described below; it is used if the
|
||
prefix length matched (16 in the example) is longer than that matched by
|
||
any static name.</p>
|
||
<p>It is not a requirement that a function implements both n and d calls;
|
||
for example, it might be appropriate for certain dynamic forms of
|
||
expansion not to be contracted to names. In that case any call with the
|
||
first argument d should cause a non-zero status to be returned.</p>
|
||
<p>The completion system calls ‘zsh_directory_name c’ followed by
|
||
equivalent calls to elements of the array zsh_directory_name_functions,
|
||
if it exists, in order to complete dynamic names for directories. The
|
||
code for this should be as for any other completion function as
|
||
described in <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>.</p>
|
||
<p>As a working example, here is a function that expands any dynamic names
|
||
beginning with the string p: to directories below /home/pws/perforce. In
|
||
this simple case a static name for the directory would be just as
|
||
effective.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zsh_directory_name() {
|
||
emulate -L zsh
|
||
setopt extendedglob
|
||
local -a match mbegin mend
|
||
if [[ $1 = d ]]; then
|
||
# turn the directory into a name
|
||
if [[ $2 = (#b)(/home/pws/perforce/)([^/]##)* ]]; then
|
||
typeset -ga reply
|
||
reply=(p:$match[2] $(( ${#match[1]} + ${#match[2]} )) )
|
||
else
|
||
return 1
|
||
fi
|
||
elif [[ $1 = n ]]; then
|
||
# turn the name into a directory
|
||
[[ $2 != (#b)p:(?*) ]] && return 1
|
||
typeset -ga reply
|
||
reply=(/home/pws/perforce/$match[1])
|
||
elif [[ $1 = c ]]; then
|
||
# complete names
|
||
local expl
|
||
local -a dirs
|
||
dirs=(/home/pws/perforce/*(/:t))
|
||
dirs=(p:${^dirs})
|
||
_wanted dynamic-dirs expl 'dynamic directory' compadd -S\] -a dirs
|
||
return
|
||
else
|
||
return 1
|
||
fi
|
||
return 0
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Static-named-directories"></span> <span
|
||
id="Static-named-directories-1"></span></p>
|
||
<h3 id="1472-static-named-directories"><a class="header" href="#1472-static-named-directories">14.7.2 Static named directories</a></h3>
|
||
<p><span id="index-directories_002c-named_002c-static"></span> <span
|
||
id="index-named-directories_002c-static"></span> <span
|
||
id="index-static-named-directories"></span></p>
|
||
<p>A ‘~’ followed by anything not already covered consisting of any number
|
||
of alphanumeric characters or underscore (‘_’), hyphen (‘-’), or dot
|
||
(‘.’) is looked up as a named directory, and replaced by the value of
|
||
that named directory if found. Named directories are typically home
|
||
directories for users on the system. They may also be defined if the
|
||
text after the ‘~’ is the name of a string shell parameter whose value
|
||
begins with a ‘/’. Note that trailing slashes will be removed from the
|
||
path to the directory (though the original parameter is not modified).</p>
|
||
<p>It is also possible to define directory names using the -d option to the
|
||
hash builtin.</p>
|
||
<p>When the shell prints a path (e.g. when expanding %~ in prompts or when
|
||
printing the directory stack), the path is checked to see if it has a
|
||
named directory as its prefix. If so, then the prefix portion is
|
||
replaced with a ‘~’ followed by the name of the directory. The shorter
|
||
of the two ways of referring to the directory is used, i.e. either the
|
||
directory name or the full path; the name is used if they are the same
|
||
length. The parameters $PWD and $OLDPWD are never abbreviated in this
|
||
fashion.</p>
|
||
<hr />
|
||
<p><span id="g_t_0060_003d_0027-expansion"></span> <span
|
||
id="g_t_0060_003d_0027-expansion-1"></span></p>
|
||
<h3 id="1473--expansion"><a class="header" href="#1473--expansion">14.7.3 ‘=’ expansion</a></h3>
|
||
<p>If a word begins with an unquoted ‘=’ and the EQUALS option is set, the
|
||
remainder of the word is taken as the name of a command. If a command
|
||
exists by that name, the word is replaced by the full pathname of the
|
||
command.</p>
|
||
<hr />
|
||
<p><span id="Notes"></span> <span id="Notes-1"></span></p>
|
||
<h3 id="1474-notes"><a class="header" href="#1474-notes">14.7.4 Notes</a></h3>
|
||
<p><span id="index-filename-expansion_002c-notes"></span></p>
|
||
<p>Filename expansion is performed on the right hand side of a parameter
|
||
assignment, including those appearing after commands of the typeset
|
||
family. In this case, the right hand side will be treated as a
|
||
colon-separated list in the manner of the PATH parameter, so that a ‘~’
|
||
or an ‘=’ following a ‘:’ is eligible for expansion. All such behaviour
|
||
can be disabled by quoting the ‘~’, the ‘=’, or the whole expression
|
||
(but not simply the colon); the EQUALS option is also respected.</p>
|
||
<p>If the option MAGIC_EQUAL_SUBST is set, any unquoted shell argument in
|
||
the form ‘<code>identifier</code>=<code>expression</code>’ becomes eligible for file expansion
|
||
as described in the previous paragraph. Quoting the first ‘=’ also
|
||
inhibits this.</p>
|
||
<hr />
|
||
<p><span id="Filename-Generation"></span> <span
|
||
id="Filename-Generation-1"></span></p>
|
||
<h2 id="148-filename-generation"><a class="header" href="#148-filename-generation">14.8 Filename Generation</a></h2>
|
||
<p><span id="index-filename-generation"></span></p>
|
||
<p>If a word contains an unquoted instance of one of the characters ‘*’,
|
||
‘(’, ‘|’, ‘<’, ‘[’, or ‘?’, it is regarded as a pattern for filename
|
||
generation, unless the GLOB option is unset. <span
|
||
id="index-GLOB_002c-use-of"></span> If the EXTENDED_GLOB option is set,
|
||
<span id="index-EXTENDED_005fGLOB_002c-use-of"></span> the ‘^’ and ‘#’
|
||
characters also denote a pattern; otherwise they are not treated
|
||
specially by the shell.</p>
|
||
<p>The word is replaced with a list of sorted filenames that match the
|
||
pattern. If no matching pattern is found, the shell gives an error
|
||
message, unless the NULL_GLOB option is set, <span
|
||
id="index-NULL_005fGLOB_002c-use-of"></span> in which case the word is
|
||
deleted; or unless the NOMATCH option is unset, in which case the word
|
||
is left unchanged. <span id="index-NOMATCH_002c-use-of"></span></p>
|
||
<p>In filename generation, the character ‘/’ must be matched explicitly;
|
||
also, a ‘.’ must be matched explicitly at the beginning of a pattern or
|
||
after a ‘/’, unless the GLOB_DOTS option is set. <span
|
||
id="index-GLOB_005fDOTS_002c-use-of"></span> No filename generation
|
||
pattern matches the files ‘.’ or ‘..’. In other instances of pattern
|
||
matching, the ‘/’ and ‘.’ are not treated specially.</p>
|
||
<hr />
|
||
<p><span id="Glob-Operators"></span></p>
|
||
<h3 id="1481-glob-operators"><a class="header" href="#1481-glob-operators">14.8.1 Glob Operators</a></h3>
|
||
<p><span id="index-glob-operators"></span></p>
|
||
<p>*<br />
|
||
Matches any string, including the null string.</p>
|
||
<p>?<br />
|
||
Matches any character.</p>
|
||
<p>[...]<br />
|
||
Matches any of the enclosed characters. Ranges of characters can be
|
||
specified by separating two characters by a ‘-’. A ‘-’ or ‘]’ may be
|
||
matched by including it as the first character in the list. <span
|
||
id="index-character-classes"></span> There are also several named
|
||
classes of characters, in the form ‘[:<code>name</code>:]’ with the following
|
||
meanings. The first set use the macros provided by the operating system
|
||
to test for the given character combinations, including any
|
||
modifications due to local language settings, see ctype(3):</p>
|
||
<p>[:alnum:]<br />
|
||
The character is alphanumeric</p>
|
||
<p>[:alpha:]<br />
|
||
The character is alphabetic</p>
|
||
<p>[:ascii:]<br />
|
||
The character is 7-bit, i.e. is a single-byte character without the top
|
||
bit set.</p>
|
||
<p>[:blank:]<br />
|
||
The character is a blank character</p>
|
||
<p>[:cntrl:]<br />
|
||
The character is a control character</p>
|
||
<p>[:digit:]<br />
|
||
The character is a decimal digit</p>
|
||
<p>[:graph:]<br />
|
||
[:lower:]<br />
|
||
The character is a lowercase letter</p>
|
||
<p>[:print:]<br />
|
||
[:punct:]<br />
|
||
[:space:]<br />
|
||
The character is whitespace</p>
|
||
<p>[:upper:]<br />
|
||
The character is an uppercase letter</p>
|
||
<p>[:xdigit:]<br />
|
||
The character is a hexadecimal digit</p>
|
||
<p>Another set of named classes is handled internally by the shell and is
|
||
not sensitive to the locale:</p>
|
||
<p>[:IDENT:]<br />
|
||
The character is allowed to form part of a shell identifier, such as a
|
||
parameter name; this test respects the POSIX_IDENTIFIERS option</p>
|
||
<p>[:IFS:]<br />
|
||
The character is used as an input field separator, i.e. is contained in
|
||
the IFS parameter</p>
|
||
<p>[:IFSSPACE:]<br />
|
||
The character is an IFS white space character; see the documentation for
|
||
IFS in <a href="Parameters.html#Parameters-Used-By-The-Shell">Parameters Used By The
|
||
Shell</a>.</p>
|
||
<p>[:INCOMPLETE:]<br />
|
||
Matches a byte that starts an incomplete multibyte character. Note that
|
||
there may be a sequence of more than one bytes that taken together form
|
||
the prefix of a multibyte character. To test for a potentially
|
||
incomplete byte sequence, use the pattern ‘[[:INCOMPLETE:]]*’. This
|
||
will never match a sequence starting with a valid multibyte character.</p>
|
||
<p>[:INVALID:]<br />
|
||
Matches a byte that does not start a valid multibyte character. Note
|
||
this may be a continuation byte of an incomplete multibyte character as
|
||
any part of a multibyte string consisting of invalid and incomplete
|
||
multibyte characters is treated as single bytes.</p>
|
||
<p>[:WORD:]<br />
|
||
The character is treated as part of a word; this test is sensitive to
|
||
the value of the WORDCHARS parameter</p>
|
||
<p>Note that the square brackets are additional to those enclosing the
|
||
whole set of characters, so to test for a single alphanumeric character
|
||
you need ‘[[:alnum:]]’. Named character sets can be used alongside
|
||
other types, e.g. ‘[[:alpha:]0-9]’.</p>
|
||
<p>[^...]<br />
|
||
[!...]<br />
|
||
Like [...], except that it matches any character which is not in the
|
||
given set.</p>
|
||
<p><[<code>x</code>]-[<code>y</code>]><br />
|
||
Matches any number in the range <code>x</code> to <code>y</code>, inclusive. Either of the
|
||
numbers may be omitted to make the range open-ended; hence ‘<->’
|
||
matches any number. To match individual digits, the [...] form is more
|
||
efficient.</p>
|
||
<p>Be careful when using other wildcards adjacent to patterns of this form;
|
||
for example, <0-9>* will actually match any number whatsoever at the
|
||
start of the string, since the ‘<0-9>’ will match the first digit, and
|
||
the ‘*’ will match any others. This is a trap for the unwary, but is
|
||
match always succeeds. Expressions such as ‘<0-9>[^[:digit:]]*’
|
||
can be used instead.</p>
|
||
<p>(...)<br />
|
||
Matches the enclosed pattern. This is used for grouping. If the KSH_GLOB
|
||
option is set, then a ‘@’, ‘*’, ‘+’, ‘?’ or ‘!’ immediately preceding
|
||
the ‘(’ is treated specially, as detailed below. The option SH_GLOB
|
||
prevents bare parentheses from being used in this way, though the
|
||
KSH_GLOB option is still available.</p>
|
||
<p>Note that grouping cannot extend over multiple directories: it is an
|
||
error to have a ‘/’ within a group (this only applies for patterns used
|
||
in filename generation). There is one exception: a group of the form
|
||
(<code>pat</code>/)# appearing as a complete path segment can match a sequence of
|
||
directories. For example, foo/(a*/)#bar matches foo/bar, foo/any/bar,
|
||
foo/any/anyother/bar, and so on.</p>
|
||
<p><code>x</code>|<code>y</code><br />
|
||
Matches either <code>x</code> or <code>y</code>. This operator has lower precedence than any
|
||
other. The ‘|’ character must be within parentheses, to avoid
|
||
interpretation as a pipeline. The alternatives are tried in order from
|
||
left to right.</p>
|
||
<p>^<code>x</code><br />
|
||
(Requires EXTENDED_GLOB to be set.) Matches anything except the pattern
|
||
<code>x</code>. This has a higher precedence than ‘/’, so ‘^foo/bar’ will search
|
||
directories in ‘.’ except ‘./foo’ for a file named ‘bar’.</p>
|
||
<p><code>x</code>~<code>y</code><br />
|
||
(Requires EXTENDED_GLOB to be set.) Match anything that matches the
|
||
pattern <code>x</code> but does not match <code>y</code>. This has lower precedence than any
|
||
operator except ‘|’, so ‘*/*~foo/bar’ will search for all files in
|
||
all directories in ‘.’ and then exclude ‘foo/bar’ if there was such a
|
||
match. Multiple patterns can be excluded by ‘<code>foo</code>~<code>bar</code>~<code>baz</code>’. In
|
||
the exclusion pattern (<code>y</code>), ‘/’ and ‘.’ are not treated specially the
|
||
way they usually are in globbing.</p>
|
||
<p><code>x</code>#<br />
|
||
(Requires EXTENDED_GLOB to be set.) Matches zero or more occurrences of
|
||
the pattern <code>x</code>. This operator has high precedence; ‘12#’ is equivalent
|
||
to ‘1(2#)’, rather than ‘(12)#’. It is an error for an unquoted ‘#’ to
|
||
follow something which cannot be repeated; this includes an empty
|
||
string, a pattern already followed by ‘##’, or parentheses when part of
|
||
a KSH_GLOB pattern (for example, ‘!(<code>foo</code>)#’ is invalid and must be
|
||
replaced by ‘*(!(<code>foo</code>))’).</p>
|
||
<p><code>x</code>##<br />
|
||
(Requires EXTENDED_GLOB to be set.) Matches one or more occurrences of
|
||
the pattern <code>x</code>. This operator has high precedence; ‘12##’ is equivalent
|
||
to ‘1(2##)’, rather than ‘(12)##’. No more than two active ‘#’
|
||
characters may appear together. (Note the potential clash with glob
|
||
qualifiers in the form ‘1(2##)’ which should therefore be avoided.)</p>
|
||
<hr />
|
||
<p><span id="ksh_002dlike-Glob-Operators"></span></p>
|
||
<h3 id="1482-ksh-like-glob-operators"><a class="header" href="#1482-ksh-like-glob-operators">14.8.2 ksh-like Glob Operators</a></h3>
|
||
<p><span id="index-KSH_005fGLOB_002c-use-of"></span></p>
|
||
<p>If the KSH_GLOB option is set, the effects of parentheses can be
|
||
modified by a preceding ‘@’, ‘*’, ‘+’, ‘?’ or ‘!’. This character need
|
||
not be unquoted to have special effects, but the ‘(’ must be.</p>
|
||
<p>@(...)<br />
|
||
Match the pattern in the parentheses. (Like ‘(...)’.)</p>
|
||
<p>*(...)<br />
|
||
Match any number of occurrences. (Like ‘(...)#’, except that recursive
|
||
directory searching is not supported.)</p>
|
||
<p>+(...)<br />
|
||
Match at least one occurrence. (Like ‘(...)##’, except that recursive
|
||
directory searching is not supported.)</p>
|
||
<p>?(...)<br />
|
||
Match zero or one occurrence. (Like ‘(|...)’.)</p>
|
||
<p>!(...)<br />
|
||
Match anything but the expression in parentheses. (Like ‘(^(...))’.)</p>
|
||
<hr />
|
||
<p><span id="Precedence"></span></p>
|
||
<h3 id="1483-precedence"><a class="header" href="#1483-precedence">14.8.3 Precedence</a></h3>
|
||
<p><span id="index-precedence-of-glob-operators"></span></p>
|
||
<p>The precedence of the operators given above is (highest) ‘^’, ‘/’, ‘~’,
|
||
‘|’ (lowest); the remaining operators are simply treated from left to
|
||
right as part of a string, with ‘#’ and ‘##’ applying to the shortest
|
||
possible preceding unit (i.e. a character, ‘?’, ‘[...]’, ‘<...>’, or
|
||
a parenthesised expression). As mentioned above, a ‘/’ used as a
|
||
directory separator may not appear inside parentheses, while a ‘|’ must
|
||
do so; in patterns used in other contexts than filename generation (for
|
||
example, in case statements and tests within ‘[[...]]’), a ‘/’ is
|
||
not special; and ‘/’ is also not special after a ‘~’ appearing outside
|
||
parentheses in a filename pattern.</p>
|
||
<hr />
|
||
<p><span id="Globbing-Flags"></span></p>
|
||
<h3 id="1484-globbing-flags"><a class="header" href="#1484-globbing-flags">14.8.4 Globbing Flags</a></h3>
|
||
<p><span id="index-globbing-flags"></span> <span
|
||
id="index-glob-flags"></span></p>
|
||
<p>There are various flags which affect any text to their right up to the
|
||
end of the enclosing group or to the end of the pattern; they require
|
||
the EXTENDED_GLOB option. All take the form (#<code>X</code>) where <code>X</code> may have
|
||
one of the following forms:</p>
|
||
<p>i<br />
|
||
Case insensitive: upper or lower case characters in the pattern match
|
||
upper or lower case characters.</p>
|
||
<p>l<br />
|
||
Lower case characters in the pattern match upper or lower case
|
||
characters; upper case characters in the pattern still only match upper
|
||
case characters.</p>
|
||
<p>I<br />
|
||
Case sensitive: locally negates the effect of i or l from that point on.</p>
|
||
<p><span id="index-match"></span> <span id="index-mbegin"></span> <span
|
||
id="index-mend"></span></p>
|
||
<p>b<br />
|
||
Activate backreferences for parenthesised groups in the pattern; this
|
||
does not work in filename generation. When a pattern with a set of
|
||
active parentheses is matched, the strings matched by the groups are
|
||
stored in the array $match, the indices of the beginning of the matched
|
||
parentheses in the array $mbegin, and the indices of the end in the
|
||
array $mend, with the first element of each array corresponding to the
|
||
first parenthesised group, and so on. These arrays are not otherwise
|
||
special to the shell. The indices use the same convention as does
|
||
parameter substitution, so that elements of $mend and $mbegin may be
|
||
used in subscripts; the KSH_ARRAYS option is respected. Sets of globbing
|
||
flags are not considered parenthesised groups; only the first nine
|
||
active parentheses can be referenced.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">foo="a_string_with_a_message"
|
||
if [[ $foo = (a|an)_(#b)(*) ]]; then
|
||
print ${foo[$mbegin[1],$mend[1]]}
|
||
fi
|
||
</code></pre>
|
||
</div>
|
||
<p>prints ‘string_with_a_message’. Note that the first set of parentheses
|
||
is before the (#b) and does not create a backreference.</p>
|
||
<p>Backreferences work with all forms of pattern matching other than
|
||
filename generation, but note that when performing matches on an entire
|
||
array, such as ${<code>array</code>#<code>pattern</code>}, or a global substitution, such as
|
||
${<code>param</code>//<code>pat</code>/<code>repl</code>}, only the data for the last match remains
|
||
available. In the case of global replacements this may still be useful.
|
||
See the example for the m flag below.</p>
|
||
<p>The numbering of backreferences strictly follows the order of the
|
||
opening parentheses from left to right in the pattern string, although
|
||
sets of parentheses may be nested. There are special rules for
|
||
parentheses followed by ‘#’ or ‘##’. Only the last match of the
|
||
parenthesis is remembered: for example, in ‘[[ abab = (#b)([ab])#
|
||
]]’, only the final ‘b’ is stored in match[1]. Thus extra
|
||
parentheses may be necessary to match the complete segment: for example,
|
||
use ‘X((ab|cd)#)Y’ to match a whole string of either ‘ab’ or ‘cd’
|
||
between ‘X’ and ‘Y’, using the value of $match[1] rather than
|
||
$match[2].</p>
|
||
<p>If the match fails none of the parameters is altered, so in some cases
|
||
it may be necessary to initialise them beforehand. If some of the
|
||
backreferences fail to match — which happens if they are in an alternate
|
||
branch which fails to match, or if they are followed by # and matched
|
||
zero times — then the matched string is set to the empty string, and the
|
||
start and end indices are set to -1.</p>
|
||
<p>Pattern matching with backreferences is slightly slower than without.</p>
|
||
<p>B<br />
|
||
Deactivate backreferences, negating the effect of the b flag from that
|
||
point on.</p>
|
||
<p>c<code>N</code>,<code>M</code><br />
|
||
The flag (#c<code>N</code>,<code>M</code>) can be used anywhere that the # or ## operators can
|
||
be used except in the expressions ‘(*/)#’ and ‘(*/)##’ in filename
|
||
generation, where ‘/’ has special meaning; it cannot be combined with
|
||
other globbing flags and a bad pattern error occurs if it is misplaced.
|
||
It is equivalent to the form {<code>N</code>,<code>M</code>} in regular expressions. The
|
||
previous character or group is required to match between <code>N</code> and <code>M</code>
|
||
times, inclusive. The form (#c<code>N</code>) requires exactly N matches; (#c,<code>M</code>)
|
||
is equivalent to specifying <code>N</code> as 0; (#c<code>N</code>,) specifies that there is
|
||
no maximum limit on the number of matches.</p>
|
||
<p><span id="index-MATCH"></span> <span id="index-MBEGIN"></span> <span
|
||
id="index-MEND"></span></p>
|
||
<p>m<br />
|
||
Set references to the match data for the entire string matched; this is
|
||
similar to backreferencing and does not work in filename generation. The
|
||
flag must be in effect at the end of the pattern, i.e. not local to a
|
||
group. The parameters $MATCH, $MBEGIN and $MEND will be set to the
|
||
string matched and to the indices of the beginning and end of the
|
||
string, respectively. This is most useful in parameter substitutions, as
|
||
otherwise the string matched is obvious.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">arr=(veldt jynx grimps waqf zho buck)
|
||
print ${arr//(#m)[aeiou]/${(U)MATCH}}
|
||
</code></pre>
|
||
</div>
|
||
<p>forces all the matches (i.e. all vowels) into uppercase, printing ‘vEldt
|
||
jynx grImps wAqf zhO bUck’.</p>
|
||
<p>Unlike backreferences, there is no speed penalty for using match
|
||
references, other than the extra substitutions required for the
|
||
replacement strings in cases such as the example shown.</p>
|
||
<p>M<br />
|
||
Deactivate the m flag, hence no references to match data will be
|
||
created.</p>
|
||
<p>a<code>num</code><br />
|
||
Approximate matching: <code>num</code> errors are allowed in the string matched by
|
||
the pattern. The rules for this are described in the next subsection.</p>
|
||
<p>s, e<br />
|
||
Unlike the other flags, these have only a local effect, and each must
|
||
appear on its own: ‘(#s)’ and ‘(#e)’ are the only valid forms. The
|
||
‘(#s)’ flag succeeds only at the start of the test string, and the
|
||
‘(#e)’ flag succeeds only at the end of the test string; they correspond
|
||
to ‘^’ and ‘$’ in standard regular expressions. They are useful for
|
||
matching path segments in patterns other than those in filename
|
||
generation (where path segments are in any case treated separately). For
|
||
example, ‘*((#s)|/)test((#e)|/)*’ matches a path segment ‘test’ in
|
||
any of the following strings: test, test/at/start, at/end/test,
|
||
in/test/middle.</p>
|
||
<p>Another use is in parameter substitution; for example
|
||
‘${array/(#s)A*Z(#e)}’ will remove only elements of an array which
|
||
match the complete pattern ‘A*Z’. There are other ways of performing
|
||
many operations of this type, however the combination of the
|
||
substitution operations ‘/’ and ‘//’ with the ‘(#s)’ and ‘(#e)’ flags
|
||
provides a single simple and memorable method.</p>
|
||
<p>Note that assertions of the form ‘(^(#s))’ also work, i.e. match
|
||
anywhere except at the start of the string, although this actually means
|
||
‘anything except a zero-length portion at the start of the string’; you
|
||
need to use ‘(""~(#s))’ to match a zero-length portion of the string
|
||
not at the start.</p>
|
||
<p>q<br />
|
||
A ‘q’ and everything up to the closing parenthesis of the globbing flags
|
||
are ignored by the pattern matching code. This is intended to support
|
||
the use of glob qualifiers, see below. The result is that the pattern
|
||
‘(#b)(*).c(#q.)’ can be used both for globbing and for matching against
|
||
a string. In the former case, the ‘(#q.)’ will be treated as a glob
|
||
qualifier and the ‘(#b)’ will not be useful, while in the latter case
|
||
the ‘(#b)’ is useful for backreferences and the ‘(#q.)’ will be ignored.
|
||
Note that colon modifiers in the glob qualifiers are also not applied in
|
||
ordinary pattern matching.</p>
|
||
<p>u<br />
|
||
Respect the current locale in determining the presence of multibyte
|
||
characters in a pattern, provided the shell was compiled with
|
||
MULTIBYTE_SUPPORT. This overrides the MULTIBYTE option; the default
|
||
behaviour is taken from the option. Compare U. (Mnemonic: typically
|
||
multibyte characters are from Unicode in the UTF-8 encoding, although
|
||
any extension of ASCII supported by the system library may be used.)</p>
|
||
<p>U<br />
|
||
All characters are considered to be a single byte long. The opposite
|
||
of u. This overrides the MULTIBYTE option.</p>
|
||
<p>For example, the test string fooxx can be matched by the pattern
|
||
(#i)FOOXX, but not by (#l)FOOXX, (#i)FOO(#I)XX or ((#i)FOOX)X. The
|
||
string (#ia2)readme specifies case-insensitive matching of readme with
|
||
up to two errors.</p>
|
||
<p>When using the ksh syntax for grouping both KSH_GLOB and EXTENDED_GLOB
|
||
must be set and the left parenthesis should be preceded by @. Note also
|
||
that the flags do not affect letters inside [...] groups, in other
|
||
words (#i)[a-z] still matches only lowercase letters. Finally, note
|
||
that when examining whole paths case-insensitively every directory must
|
||
be searched for all files which match, so that a pattern of the form
|
||
(#i)/foo/bar/... is potentially slow.</p>
|
||
<hr />
|
||
<p><span id="Approximate-Matching"></span></p>
|
||
<h3 id="1485-approximate-matching"><a class="header" href="#1485-approximate-matching">14.8.5 Approximate Matching</a></h3>
|
||
<p><span id="index-approximate-matching"></span> <span
|
||
id="index-matching_002c-approximate"></span></p>
|
||
<p>When matching approximately, the shell keeps a count of the errors
|
||
found, which cannot exceed the number specified in the (#a<code>num</code>) flags.
|
||
Four types of error are recognised:</p>
|
||
<p>1.<br />
|
||
Different characters, as in fooxbar and fooybar.</p>
|
||
<p>2.<br />
|
||
Transposition of characters, as in banana and abnana.</p>
|
||
<p>3.<br />
|
||
A character missing in the target string, as with the pattern road and
|
||
target string rod.</p>
|
||
<p>4.<br />
|
||
An extra character appearing in the target string, as with stove and
|
||
strove.</p>
|
||
<p>Thus, the pattern (#a3)abcd matches dcba, with the errors occurring by
|
||
using the first rule twice and the second once, grouping the string as
|
||
[d][cb][a] and [a][bc][d].</p>
|
||
<p>Non-literal parts of the pattern must match exactly, including
|
||
characters in character ranges: hence (#a1)??? matches strings of length
|
||
four, by applying rule 4 to an empty part of the pattern, but not
|
||
strings of length two, since all the ? must match. Other characters
|
||
which must match exactly are initial dots in filenames (unless the
|
||
GLOB_DOTS option is set), and all slashes in filenames, so that a/bc is
|
||
two errors from ab/c (the slash cannot be transposed with another
|
||
character). Similarly, errors are counted separately for non-contiguous
|
||
strings in the pattern, so that (ab|cd)ef is two errors from aebf.</p>
|
||
<p>When using exclusion via the ~ operator, approximate matching is
|
||
treated entirely separately for the excluded part and must be activated
|
||
separately. Thus, (#a1)README~READ_ME matches READ.ME but not READ_ME,
|
||
as the trailing READ_ME is matched without approximation. However,
|
||
(#a1)README~(#a1)READ_ME does not match any pattern of the form
|
||
READ<code>?</code>ME as all such forms are now excluded.</p>
|
||
<p>Apart from exclusions, there is only one overall error count; however,
|
||
the maximum errors allowed may be altered locally, and this can be
|
||
delimited by grouping. For example, (#a1)cat((#a0)dog)fox allows one
|
||
error in total, which may not occur in the dog section, and the pattern
|
||
(#a1)cat(#a0)dog(#a1)fox is equivalent. Note that the point at which an
|
||
error is first found is the crucial one for establishing whether to use
|
||
approximation; for example, (#a1)abc(#a0)xyz will not match abcdxyz,
|
||
because the error occurs at the ‘x’, where approximation is turned off.</p>
|
||
<p>Entire path segments may be matched approximately, so that
|
||
‘(#a1)/foo/d/is/available/at/the/bar’ allows one error in any path
|
||
segment. This is much less efficient than without the (#a1), however,
|
||
since every directory in the path must be scanned for a possible
|
||
approximate match. It is best to place the (#a1) after any path segments
|
||
which are known to be correct.</p>
|
||
<hr />
|
||
<p><span id="Recursive-Globbing"></span></p>
|
||
<h3 id="1486-recursive-globbing"><a class="header" href="#1486-recursive-globbing">14.8.6 Recursive Globbing</a></h3>
|
||
<p><span id="index-recursive-globbing"></span> <span
|
||
id="index-globbing_002c-recursive"></span></p>
|
||
<p>A pathname component of the form ‘(<code>foo</code>/)#’ matches a path consisting
|
||
of zero or more directories matching the pattern <code>foo</code>.</p>
|
||
<p>As a shorthand, ‘**/’ is equivalent to ‘(*/)#’; note that this
|
||
therefore matches files in the current directory as well as
|
||
subdirectories. Thus:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- (*/)#bar
|
||
</code></pre>
|
||
</div>
|
||
<p>or</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- **/bar
|
||
</code></pre>
|
||
</div>
|
||
<p>does a recursive directory search for files named ‘bar’ (potentially
|
||
including the file ‘bar’ in the current directory). This form does not
|
||
follow symbolic links; the alternative form ‘***/’ does, but is
|
||
otherwise identical. Neither of these can be combined with other forms
|
||
of globbing within the same path segment; in that case, the ‘*’
|
||
operators revert to their usual effect.</p>
|
||
<p>Even shorter forms are available when the option GLOB_STAR_SHORT is set.
|
||
In that case if no / immediately follows a ** or *** they are
|
||
treated as if both a / plus a further * are present. Hence:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">setopt GLOBSTARSHORT
|
||
ls -ld -- **.c
|
||
</code></pre>
|
||
</div>
|
||
<p>is equivalent to</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- **/*.c
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Glob-Qualifiers"></span></p>
|
||
<h3 id="1487-glob-qualifiers"><a class="header" href="#1487-glob-qualifiers">14.8.7 Glob Qualifiers</a></h3>
|
||
<p><span id="index-globbing_002c-qualifiers"></span> <span
|
||
id="index-qualifiers_002c-globbing"></span></p>
|
||
<p>Patterns used for filename generation may end in a list of qualifiers
|
||
enclosed in parentheses. The qualifiers specify which filenames that
|
||
otherwise match the given pattern will be inserted in the argument list.</p>
|
||
<p><span id="index-BARE_005fGLOB_005fQUAL_002c-use-of"></span></p>
|
||
<p>If the option BARE_GLOB_QUAL is set, then a trailing set of parentheses
|
||
containing no ‘|’ or ‘(’ characters (or ‘~’ if it is special) is taken
|
||
as a set of glob qualifiers. A glob subexpression that would normally be
|
||
taken as glob qualifiers, for example ‘(^x)’, can be forced to be
|
||
treated as part of the glob pattern by doubling the parentheses, in this
|
||
case producing ‘((^x))’.</p>
|
||
<p>If the option EXTENDED_GLOB is set, a different syntax for glob
|
||
qualifiers is available, namely ‘(#q<code>x</code>)’ where <code>x</code> is any of the same
|
||
glob qualifiers used in the other format. The qualifiers must still
|
||
appear at the end of the pattern. However, with this syntax multiple
|
||
glob qualifiers may be chained together. They are treated as a logical
|
||
AND of the individual sets of flags. Also, as the syntax is unambiguous,
|
||
the expression will be treated as glob qualifiers just as long any
|
||
parentheses contained within it are balanced; appearance of ‘|’, ‘(’ or
|
||
‘~’ does not negate the effect. Note that qualifiers will be recognised
|
||
in this form even if a bare glob qualifier exists at the end of files if
|
||
both options are set; however, mixed syntax should probably be avoided
|
||
for the sake of clarity. Note that within conditions using the ‘[[’
|
||
form the presence of a parenthesised expression (#q<code>...</code>) at the end of
|
||
a string indicates that globbing should be performed; the expression may
|
||
include glob qualifiers, but it is also valid if it is simply (#q). This
|
||
does not apply to the right hand side of pattern match operators as the
|
||
syntax already has special significance.</p>
|
||
<p>A qualifier may be any one of the following:</p>
|
||
<p>/<br />
|
||
directories</p>
|
||
<p>F<br />
|
||
‘full’ (i.e. non-empty) directories. Note that the opposite sense (^F)
|
||
expands to empty directories and all non-directories. Use (/^F) for
|
||
empty directories.</p>
|
||
<p>.<br />
|
||
plain files</p>
|
||
<p>@<br />
|
||
symbolic links</p>
|
||
<p>=<br />
|
||
sockets</p>
|
||
<p>p<br />
|
||
named pipes (FIFOs)</p>
|
||
<p>*<br />
|
||
%<br />
|
||
device files (character or block special)</p>
|
||
<p>%b<br />
|
||
block special files</p>
|
||
<p>%c<br />
|
||
character special files</p>
|
||
<p>r<br />
|
||
owner-readable files (0400)</p>
|
||
<p>w<br />
|
||
x<br />
|
||
A<br />
|
||
group-readable files (0040)</p>
|
||
<p>I<br />
|
||
E<br />
|
||
R<br />
|
||
world-readable files (0004)</p>
|
||
<p>W<br />
|
||
X<br />
|
||
s<br />
|
||
setuid files (04000)</p>
|
||
<p>S<br />
|
||
setgid files (02000)</p>
|
||
<p>t<br />
|
||
files with the sticky bit (01000)</p>
|
||
<p>f<code>spec</code><br />
|
||
files with access rights matching <code>spec</code>. This <code>spec</code> may be a octal
|
||
number optionally preceded by a ‘=’, a ‘+’, or a ‘-’. If none of these
|
||
characters is given, the behavior is the same as for ‘=’. The octal
|
||
number describes the mode bits to be expected, if combined with a ‘=’,
|
||
the value given must match the file-modes exactly, with a ‘+’, at least
|
||
the bits in the given number must be set in the file-modes, and with a
|
||
‘-’, the bits in the number must not be set. Giving a ‘?’ instead of a
|
||
octal digit anywhere in the number ensures that the corresponding bits
|
||
in the file-modes are not checked, this is only useful in combination
|
||
with ‘=’.</p>
|
||
<p>If the qualifier ‘f’ is followed by any other character anything up to
|
||
the next matching character (‘[’, ‘{’, and ‘<’ match ‘]’, ‘}’, and
|
||
‘>’ respectively, any other character matches itself) is taken as a list
|
||
of comma-separated <code>sub-spec</code>s. Each <code>sub-spec</code> may be either an octal
|
||
number as described above or a list of any of the characters ‘u’, ‘g’,
|
||
‘o’, and ‘a’, followed by a ‘=’, a ‘+’, or a ‘-’, followed by a list of
|
||
any of the characters ‘r’, ‘w’, ‘x’, ‘s’, and ‘t’, or an octal digit.
|
||
The first list of characters specify which access rights are to be
|
||
checked. If a ‘u’ is given, those for the owner of the file are used, if
|
||
a ‘g’ is given, those of the group are checked, a ‘o’ means to test
|
||
those of other users, and the ‘a’ says to test all three groups. The
|
||
‘=’, ‘+’, and ‘-’ again says how the modes are to be checked and have
|
||
the same meaning as described for the first form above. The second list
|
||
of characters finally says which access rights are to be expected: ‘r’
|
||
for read access, ‘w’ for write access, ‘x’ for the right to execute the
|
||
file (or to search a directory), ‘s’ for the setuid and setgid bits, and
|
||
‘t’ for the sticky bit.</p>
|
||
<p>Thus, ‘*(f70?)’ gives the files for which the owner has read, write,
|
||
and execute permission, and for which other group members have no
|
||
rights, independent of the permissions for other users. The pattern
|
||
‘*(f-100)’ gives all files for which the owner does not have execute
|
||
permission, and ‘*(f:gu+w,o-rx:)’ gives the files for which the owner
|
||
and the other members of the group have at least write permission, and
|
||
for which other users don’t have read or execute permission.</p>
|
||
<p>e<code>string</code><br />
|
||
+<code>cmd</code><br />
|
||
The <code>string</code> will be executed as shell code. The filename will be
|
||
included in the list if and only if the code returns a zero status
|
||
(usually the status of the last command).</p>
|
||
<p>In the first form, the first character after the ‘e’ will be used as a
|
||
separator and anything up to the next matching separator will be taken
|
||
as the <code>string</code>; ‘[’, ‘{’, and ‘<’ match ‘]’, ‘}’, and ‘>’,
|
||
respectively, while any other character matches itself. Note that
|
||
expansions must be quoted in the <code>string</code> to prevent them from being
|
||
expanded before globbing is done. <code>string</code> is then executed as shell
|
||
code. The string globqual is appended to the array zsh_eval_context the
|
||
duration of execution.</p>
|
||
<p><span id="index-REPLY_002c-use-of-1"></span> <span
|
||
id="index-reply_002c-use-of"></span></p>
|
||
<p>During the execution of <code>string</code> the filename currently being tested is
|
||
available in the parameter REPLY; the parameter may be altered to a
|
||
string to be inserted into the list instead of the original filename. In
|
||
addition, the parameter reply may be set to an array or a string, which
|
||
overrides the value of REPLY. If set to an array, the latter is inserted
|
||
into the command line word by word.</p>
|
||
<p>For example, suppose a directory contains a single file ‘lonely’. Then
|
||
the expression ‘*(e:’reply=(${REPLY}{1,2})’:)’ will cause the words
|
||
‘lonely1’ and ‘lonely2’ to be inserted into the command line. Note the
|
||
quoting of <code>string</code>.</p>
|
||
<p>The form +<code>cmd</code> has the same effect, but no delimiters appear around
|
||
<code>cmd</code>. Instead, <code>cmd</code> is taken as the longest sequence of characters
|
||
following the + that are alphanumeric or underscore. Typically <code>cmd</code>
|
||
will be the name of a shell function that contains the appropriate test.
|
||
For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">nt() { [[ $REPLY -nt $NTREF ]] }
|
||
NTREF=reffile
|
||
ls -ld -- *(+nt)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all files in the directory that have been modified more recently
|
||
than reffile.</p>
|
||
<p>d<code>dev</code><br />
|
||
files on the device <code>dev</code></p>
|
||
<p>l[-|+]<code>ct</code><br />
|
||
files having a link count less than <code>ct</code> (-), greater than <code>ct</code> (+), or
|
||
equal to <code>ct</code></p>
|
||
<p>U<br />
|
||
files owned by the effective user ID</p>
|
||
<p>G<br />
|
||
files owned by the effective group ID</p>
|
||
<p>u<code>id</code><br />
|
||
files owned by user ID <code>id</code> if that is a number. Otherwise, <code>id</code>
|
||
specifies a user name: the character after the ‘u’ will be taken as a
|
||
separator and the string between it and the next matching separator will
|
||
be taken as a user name. The starting separators ‘[’, ‘{’, and ‘<’
|
||
match the final separators ‘]’, ‘}’, and ‘>’, respectively; any other
|
||
character matches itself. The selected files are those owned by this
|
||
user. For example, ‘u:foo:’ or ‘u[foo]’ selects files owned by user
|
||
‘foo’.</p>
|
||
<p>g<code>id</code><br />
|
||
like u<code>id</code> but with group IDs or names</p>
|
||
<p>a[Mwhms][-|+]<code>n</code><br />
|
||
files accessed exactly <code>n</code> days ago. Files accessed within the last <code>n</code>
|
||
days are selected using a negative value for <code>n</code> (-<code>n</code>). Files accessed
|
||
more than <code>n</code> days ago are selected by a positive <code>n</code> value (+<code>n</code>).
|
||
Optional unit specifiers ‘M’, ‘w’, ‘h’, ‘m’ or ‘s’ (e.g. ‘ah5’) cause
|
||
the check to be performed with months (of 30 days), weeks, hours,
|
||
minutes or seconds instead of days, respectively. An explicit ‘d’ for
|
||
days is also allowed.</p>
|
||
<p>Any fractional part of the difference between the access time and the
|
||
current part in the appropriate units is ignored in the comparison. For
|
||
instance, ‘echo *(ah-5)’ would echo files accessed within the last five
|
||
hours, while ‘echo *(ah+5)’ would echo files accessed at least six
|
||
hours ago, as times strictly between five and six hours are treated as
|
||
five hours.</p>
|
||
<p>m[Mwhms][-|+]<code>n</code><br />
|
||
like the file access qualifier, except that it uses the file
|
||
modification time.</p>
|
||
<p>c[Mwhms][-|+]<code>n</code><br />
|
||
like the file access qualifier, except that it uses the file inode
|
||
change time.</p>
|
||
<p>L[+|-]<code>n</code><br />
|
||
files less than <code>n</code> bytes (-), more than <code>n</code> bytes (+), or exactly <code>n</code>
|
||
bytes in length.</p>
|
||
<p>If this flag is directly followed by a <em>size specifier</em> ‘k’ (‘K’), ‘m’
|
||
(‘M’), or ‘p’ (‘P’) (e.g. ‘Lk-50’) the check is performed with
|
||
kilobytes, megabytes, or blocks (of 512 bytes) instead. (On some systems
|
||
additional specifiers are available for gigabytes, ‘g’ or ‘G’, and
|
||
terabytes, ‘t’ or ‘T’.) If a size specifier is used a file is regarded
|
||
as "exactly" the size if the file size rounded up to the next unit is
|
||
equal to the test size. Hence ‘*(Lm1)’ matches files from 1 byte up to
|
||
1 Megabyte inclusive. Note also that the set of files "less than" the
|
||
test size only includes files that would not match the equality test;
|
||
hence ‘*(Lm-1)’ only matches files of zero size.</p>
|
||
<p>^<br />
|
||
negates all qualifiers following it</p>
|
||
<p>-<br />
|
||
toggles between making the qualifiers work on symbolic links (the
|
||
default) and the files they point to, if any; any symbolic link for
|
||
whose target the ‘stat’ system call fails (whatever the cause of the
|
||
failure) is treated as a file in its own right</p>
|
||
<p>M<br />
|
||
sets the MARK_DIRS option for the current pattern <span
|
||
id="index-MARK_005fDIRS_002c-setting-in-pattern"></span></p>
|
||
<p>T<br />
|
||
appends a trailing qualifier mark to the filenames, analogous to the
|
||
LIST_TYPES option, for the current pattern (overrides M)</p>
|
||
<p>N<br />
|
||
sets the NULL_GLOB option for the current pattern <span
|
||
id="index-NULL_005fGLOB_002c-setting-in-pattern"></span></p>
|
||
<p>D<br />
|
||
sets the GLOB_DOTS option for the current pattern <span
|
||
id="index-GLOB_005fDOTS_002c-setting-in-pattern"></span></p>
|
||
<p>n<br />
|
||
sets the NUMERIC_GLOB_SORT option for the current pattern <span
|
||
id="index-NUMERIC_005fGLOB_005fSORT_002c-setting-in-pattern"></span></p>
|
||
<p>Y<code>n</code><br />
|
||
enables short-circuit mode: the pattern will expand to at most <code>n</code>
|
||
filenames. If more than <code>n</code> matches exist, only the first <code>n</code> matches in
|
||
directory traversal order will be considered.</p>
|
||
<p>Implies oN when no o<code>c</code> qualifier is used.</p>
|
||
<p>o<code>c</code><br />
|
||
specifies how the names of the files should be sorted. The following
|
||
values of <code>c</code> sort in the following ways:</p>
|
||
<p>n<br />
|
||
By name.</p>
|
||
<p>L<br />
|
||
By the size (length) of the files.</p>
|
||
<p>l<br />
|
||
By number of links.</p>
|
||
<p>a<br />
|
||
By time of last access, youngest first.</p>
|
||
<p>m<br />
|
||
By time of last modification, youngest first.</p>
|
||
<p>c<br />
|
||
By time of last inode change, youngest first.</p>
|
||
<p>d<br />
|
||
By directories: files in subdirectories appear before those in the
|
||
current directory at each level of the search — this is best combined
|
||
with other criteria, for example ‘odon’ to sort on names for files
|
||
within the same directory.</p>
|
||
<p>N<br />
|
||
No sorting is performed.</p>
|
||
<p>e<code>string</code><br />
|
||
+<code>cmd</code><br />
|
||
Sort by shell code (see below).</p>
|
||
<p>Note that the modifiers ^ and - are used, so ‘*(^-oL)’ gives a list of
|
||
all files sorted by file size in descending order, following any
|
||
symbolic links. Unless oN is used, multiple order specifiers may occur
|
||
to resolve ties.</p>
|
||
<p>The default sorting is n (by name) unless the Y glob qualifier is used,
|
||
in which case it is N (unsorted).</p>
|
||
<p>oe and o+ are special cases; they are each followed by shell code,
|
||
delimited as for the e glob qualifier and the + glob qualifier
|
||
respectively (see above). The code is executed for each matched file
|
||
with the parameter REPLY set to the name of the file on entry and
|
||
globsort appended to zsh_eval_context. The code should modify the
|
||
parameter REPLY in some fashion. On return, the value of the parameter
|
||
is used instead of the file name as the string on which to sort. Unlike
|
||
other sort operators, oe and o+ may be repeated, but note that the
|
||
maximum number of sort operators of any kind that may appear in any glob
|
||
expression is 12.</p>
|
||
<p>O<code>c</code><br />
|
||
like ‘o’, but sorts in descending order; i.e. ‘*(^o<code>c</code>)’ is the same as
|
||
‘*(O<code>c</code>)’ and ‘*(^O<code>c</code>)’ is the same as ‘*(o<code>c</code>)’; ‘Od’ puts files in
|
||
the current directory before those in subdirectories at each level of
|
||
the search.</p>
|
||
<p>[<code>beg</code>[,<code>end</code>]]<br />
|
||
specifies which of the matched filenames should be included in the
|
||
returned list. The syntax is the same as for array subscripts. <code>beg</code> and
|
||
the optional <code>end</code> may be mathematical expressions. As in parameter
|
||
subscripting they may be negative to make them count from the last match
|
||
backward. E.g.: ‘*(-OL[1,3])’ gives a list of the names of the three
|
||
largest files.</p>
|
||
<p>P<code>string</code><br />
|
||
The <code>string</code> will be prepended to each glob match as a separate word.
|
||
<code>string</code> is delimited in the same way as arguments to the e glob
|
||
qualifier described above. The qualifier can be repeated; the words are
|
||
prepended separately so that the resulting command line contains the
|
||
words in the same order they were given in the list of glob qualifiers.</p>
|
||
<p>A typical use for this is to prepend an option before all occurrences of
|
||
a file name; for example, the pattern ‘*(P:-f:)’ produces the command
|
||
line arguments ‘-f <code>file1</code> -f <code>file2</code> ...’</p>
|
||
<p>If the modifier ^ is active, then <code>string</code> will be appended instead of
|
||
prepended. Prepending and appending is done independently so both can be
|
||
used on the same glob expression; for example by writing
|
||
‘*(P:foo:^P:bar:^P:baz:)’ which produces the command line arguments
|
||
‘foo baz <code>file1</code> bar ...’</p>
|
||
<p>More than one of these lists can be combined, separated by commas. The
|
||
whole list matches if at least one of the sublists matches (they are
|
||
‘or’ed, the qualifiers in the sublists are ‘and’ed). Some qualifiers,
|
||
however, affect all matches generated, independent of the sublist in
|
||
which they are given. These are the qualifiers ‘M’, ‘T’, ‘N’, ‘D’, ‘n’,
|
||
‘o’, ‘O’ and the subscripts given in brackets (‘[<code>...</code>]’).</p>
|
||
<p>If a ‘:’ appears in a qualifier list, the remainder of the expression in
|
||
parenthesis is interpreted as a modifier (see <a href="#Modifiers">Modifiers</a> in
|
||
<a href="#History-Expansion">History Expansion</a>). Each modifier must be
|
||
introduced by a separate ‘:’. Note also that the result after
|
||
modification does not have to be an existing file. The name of any
|
||
existing file can be followed by a modifier of the form ‘(:<code>...</code>)’ even
|
||
if no actual filename generation is performed, although note that the
|
||
presence of the parentheses causes the entire expression to be subjected
|
||
to any global pattern matching options such as NULL_GLOB. Thus:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- *(-/)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all directories and symbolic links that point to directories, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- *(-@)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all broken symbolic links, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- *(%W)
|
||
</code></pre>
|
||
</div>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- *(W,X)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all files in the current directory that are</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print -rC1 /tmp/foo*(u0^@:t)
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs the basename of all root-owned files beginning with the string
|
||
‘foo’ in /tmp, ignoring symlinks, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ls -ld -- *.*~(lex|parse).[ch](^D^l1)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all files having a link count of one whose names contain a dot
|
||
(but not those starting with a dot, since GLOB_DOTS is explicitly
|
||
switched off) except for lex.c, lex.h, parse.c and parse.h.</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print -rC1 b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)
|
||
</code></pre>
|
||
</div>
|
||
<p>demonstrates how colon modifiers and other qualifiers may be chained
|
||
together. The ordinary qualifier ‘.’ is applied first, then the colon
|
||
modifiers in order from left to right. So if EXTENDED_GLOB is set and
|
||
the base pattern matches the regular file builtin.pro, the shell will
|
||
print ‘shmiltin.shmo’.</p>
|
||
<hr />
|
||
<p>This document was generated on <em>May 14, 2022</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html
|
||
5.0</em></a>.<br />
|
||
Zsh version 5.9, released on May 14, 2022.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="Prompt-Expansion.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next" href="Parameters.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
<a rel="prev" href="Prompt-Expansion.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
<a rel="next" href="Parameters.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<!-- Livereload script (if served using the cli tool) -->
|
||
<script type="text/javascript">
|
||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
||
const socket = new WebSocket(wsAddress);
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
</body>
|
||
</html>
|