3293 lines
168 KiB
HTML
3293 lines
168 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 -->
|
||
|
||
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-_0026-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html" 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>
|
||
</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>
|
||
<li><a href="#1432-rules">14.3.2 Rules</a></li>
|
||
<li><a href="#1433-examples">14.3.3 Examples</a></li>
|
||
</ul>
|
||
</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>
|
||
<ul>
|
||
<li>
|
||
<p><em>History Expansion</em><br />
|
||
This is performed only in interactive shells.</p>
|
||
</li>
|
||
<li>
|
||
<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>
|
||
</li>
|
||
<li>
|
||
<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 ‘<code>\</code>’,‘<code>’</code>’
|
||
and ‘<code>"</code>’ are removed.</p>
|
||
</li>
|
||
<li>
|
||
<p><em>Filename Expansion</em><br />
|
||
If the <code>SH_FILE_EXPANSION</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><em>Filename Generation</em><br />
|
||
This expansion, commonly referred to as globbing, is always done
|
||
last.</p>
|
||
</li>
|
||
</ul>
|
||
<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 <code>HISTSIZE</code> 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-2"></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 <code>histchars</code>
|
||
parameter, which is ‘<code>!</code>’ by default, and may occur anywhere on the
|
||
command line, including inside double quotes (but not inside single
|
||
quotes <code>’...’</code> or C-style quotes <code>$’...’</code> 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 <code>CSH_JUNKIE_HISTORY</code> is set, then every history
|
||
reference with no event specification <em>always</em> refers to the previous
|
||
command.</p>
|
||
<p>For example, ‘<code>!</code>’ is the event designator for the previous command, so
|
||
‘<code>!!:1</code>’ always refers to the first word of the previous command, and
|
||
‘<code>!!$</code>’ always refers to the last word of the previous command. With
|
||
<code>CSH_JUNKIE_HISTORY</code> set, then ‘<code>!:1</code>’ and ‘<code>!$</code>’ function in the same
|
||
manner as ‘<code>!!:1</code>’ and ‘<code>!!$</code>’, respectively. Conversely, if
|
||
<code>CSH_JUNKIE_HISTORY</code> is unset, then ‘<code>!:1</code>’ and ‘<code>!$</code>’ 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``^``bar</code>’ (where ‘<code>^</code>’ is actually the
|
||
second character of the <code>histchars</code> parameter) repeats the last command,
|
||
replacing the string <code>foo</code> with <code>bar</code>. More precisely, the sequence
|
||
‘<code>^``foo``^``bar``^</code>’ is synonymous with ‘<code>!!:s``^``foo``^``bar``^</code>’,
|
||
hence other modifiers (see <a href="#Modifiers">Modifiers</a>) may follow the final
|
||
‘<code>^</code>’. In particular, ‘<code>^``foo``^``bar``^:G</code>’ performs a global
|
||
substitution.</p>
|
||
<p>If the shell encounters the character sequence ‘<code>!"</code>’ 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
|
||
‘<code>!"</code>’ is removed from the input, and any subsequent ‘<code>!</code>’ 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 <code>fc</code> 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 <code>‘!’</code> in each
|
||
item may be changed to another character by setting the <code>histchars</code>
|
||
parameter.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>!</code><br />
|
||
Start a history expansion, except when followed by a blank, newline,
|
||
‘<code>=</code>’ or ‘<code>(</code>’. 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>
|
||
</li>
|
||
<li>
|
||
<p><code>!!</code><br />
|
||
Refer to the previous command. By itself, this expansion repeats the
|
||
previous command.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!``n</code><br />
|
||
Refer to command-line <code>n</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!-``n</code><br />
|
||
Refer to the current command-line minus <code>n</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!``str</code><br />
|
||
Refer to the most recent command starting with <code>str</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!?``str</code>[<code>?</code>]<br />
|
||
Refer to the most recent command containing <code>str</code>. The trailing
|
||
‘<code>?</code>’ 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>
|
||
</li>
|
||
<li>
|
||
<p><code>!#</code><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 ‘<code>!#</code>’ reference.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!{</code>...<code>}</code><br />
|
||
Insulate a history reference from adjacent characters (if
|
||
necessary).</p>
|
||
</li>
|
||
</ul>
|
||
<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 ‘<code>:</code>’ usually separates the
|
||
event specification from the word designator. It may be omitted only if
|
||
the word designator begins with a ‘<code>^</code>’, ‘<code>$</code>’, ‘<code>*</code>’, ‘<code>-</code>’ or ‘<code>%</code>’.
|
||
Word designators include:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>0</code><br />
|
||
The first input word (command).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>n</code><br />
|
||
The <code>n</code>th argument.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>^</code><br />
|
||
The first argument. That is, <code>1</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>$</code><br />
|
||
The last argument.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%</code><br />
|
||
The word matched by (the most recent) <code>?``str</code> search.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``-``y</code><br />
|
||
A range of words; <code>x</code> defaults to <code>0</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*</code><br />
|
||
All the arguments, or a null value if there are none.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``*</code><br />
|
||
Abbreviates ‘<code>x``-$</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``-</code><br />
|
||
Like ‘<code>x``*</code>’ but omitting word <code>$</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Note that a ‘<code>%</code>’ word designator works only when used in one of ‘<code>!%</code>’,
|
||
‘<code>!:%</code>’ or ‘<code>!?``str``?:%</code>’, and only when used after a <code>!?</code> 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 ‘<code>:</code>’. These
|
||
modifiers also work on the result of <em>filename generation</em> and
|
||
<em>parameter expansion</em>, except where noted.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>a</code><br />
|
||
Turn a file name into an absolute path: prepends the current
|
||
directory, if necessary; remove ‘<code>.</code>’ path segments; and remove
|
||
‘<code>..</code>’ 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 <code>CHASE_DOTS</code> or <code>CHASE_LINKS</code> is set. For example,
|
||
‘<code>/before/here/../after</code>’ is always transformed to
|
||
‘<code>/before/after</code>’, regardless of whether ‘<code>/before/here</code>’ exists
|
||
or what kind of object (dir, file, symlink, etc.) it is.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>A</code><br />
|
||
Turn a file name into an absolute path as the ‘<code>a</code>’ modifier does,
|
||
and <em>then</em> pass the result through the <code>realpath(3)</code> library
|
||
function to resolve symbolic links.</p>
|
||
<p>Note: on systems that do not have a <code>realpath(3)</code> library function,
|
||
symbolic links are not resolved, so on those systems ‘<code>a</code>’ and ‘<code>A</code>’
|
||
are equivalent.</p>
|
||
<p>Note: <code>foo:A</code> and <code>realpath(foo)</code> are different on some inputs. For
|
||
<code>realpath(foo)</code> semantics, see the ‘<code>P</code>‘ modifier.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>c</code><br />
|
||
Resolve a command name into an absolute path by searching the
|
||
command path given by the <code>PATH</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><code>e</code><br />
|
||
Remove all but the part of the filename extension following the
|
||
‘<code>.</code>’; see the definition of the filename extension in the
|
||
description of the <code>r</code> modifier below. Note that according to that
|
||
definition the result will be empty if the string ends with a ‘<code>.</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>h</code> [ <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
|
||
‘<code>dirname</code>’. If the <code>h</code> 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 ‘<code>/</code>’ is the first component, so, for
|
||
example, if <code>var=/my/path/to/something</code>, then <code>${var:h3}</code>
|
||
substitutes <code>/my/path</code>. 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 <code>$var:h2</code> is treated as <code>${var:h}2</code>, not as
|
||
<code>${var:h2}</code>. 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>
|
||
</li>
|
||
<li>
|
||
<p><code>l</code><br />
|
||
Convert the words to all lowercase.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>p</code><br />
|
||
Print the new command but do not execute it. Only works with history
|
||
expansion.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>P</code><br />
|
||
Turn a file name into an absolute path, like <code>realpath(3)</code>. The
|
||
resulting path will be absolute, have neither ‘<code>.</code>’ nor ‘<code>..</code>’
|
||
components, and refer to the same directory entry as the input
|
||
filename.</p>
|
||
<p>Unlike <code>realpath(3)</code>, non-existent trailing components are permitted
|
||
and preserved.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>q</code><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 <code>eval</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Q</code><br />
|
||
Remove one level of quotes from the substituted words.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>r</code><br />
|
||
Remove a filename extension leaving the root name. Strings with no
|
||
filename extension are not altered. A filename extension is a ‘<code>.</code>’
|
||
followed by any number of characters (including zero) that are
|
||
neither ‘<code>.</code>’ nor ‘<code>/</code>’ and that continue to the end of the string.
|
||
For example, the extension of ‘<code>foo.orig.c</code>’ is ‘<code>.c</code>’, and
|
||
‘<code>dir.c/foo</code>’ has no extension.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>s/``l``/``r</code>[<code>/</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 ‘<code>gs/``l``/``r</code>’ and ‘<code>s/``l``/``r``/:G</code>’ perform global
|
||
substitution, i.e. substitute every occurrence of <code>r</code> for <code>l</code>. Note
|
||
that the <code>g</code> or <code>:G</code> must appear in exactly the position shown.</p>
|
||
<p>See further notes on this form of substitution below.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>&</code><br />
|
||
Repeat the previous <code>s</code> substitution. Like <code>s</code>, may be preceded
|
||
immediately by a <code>g</code>. In parameter expansion the <code>&</code> must appear
|
||
inside braces, and in filename generation it must be quoted with a
|
||
backslash.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>t</code> [ <code>digits</code> ]<br />
|
||
Remove all leading pathname components, leaving the final component
|
||
(tail). This works like ‘<code>basename</code>’. 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>
|
||
</li>
|
||
<li>
|
||
<p><code>u</code><br />
|
||
Convert the words to all uppercase.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x</code><br />
|
||
Like <code>q</code>, but break into words at whitespace. Does not work with
|
||
parameter expansion.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The <code>s/``l``/``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 ‘<code>/</code>’. A
|
||
backslash quotes the delimiter character. The character ‘<code>&</code>’, in the
|
||
right-hand-side <code>r</code>, is replaced by the text from the left-hand-side
|
||
<code>l</code>. The ‘<code>&</code>’ 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 ‘<code>?</code>’ 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 ‘<code>&</code>’ is used within glob qualifiers an extra backslash
|
||
is needed as a <code>&</code> 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 <code>HIST_SUBST_PATTERN</code> 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 ‘<code>:s</code>’ expression itself is divided into <code>l</code> and <code>r</code> sides.</p>
|
||
<p>If the option <code>HIST_SUBST_PATTERN</code> 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
|
||
<code>(#q:s/``...``/``...``/)</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 <code>NO_BAD_PATTERN</code> option so will
|
||
cause an error.</p>
|
||
<p>When <code>HIST_SUBST_PATTERN</code> is set, <code>l</code> may start with a <code>#</code> to indicate
|
||
that the pattern must match at the start of the string to be
|
||
substituted, and a <code>%</code> may appear at the start or after an <code>#</code> to
|
||
indicate that the pattern must match at the end of the string to be
|
||
substituted. The <code>%</code> or <code>#</code> may be quoted with two backslashes.</p>
|
||
<p>For example, the following piece of filename generation code with the
|
||
<code>EXTENDED_GLOB</code> option:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print -r -- *.c(#q:s/#%(#b)s(*).c/'S${match[1]}.C'/)
|
||
</code></pre>
|
||
</div>
|
||
<p>takes the expansion of <code>*.c</code> and applies the glob qualifiers in the
|
||
<code>(#q``...``)</code> expression, which consists of a substitution modifier
|
||
anchored to the start and end of each word (<code>#%</code>). This turns on
|
||
backreferences (<code>(#b)</code>), so that the parenthesised subexpression is
|
||
available in the replacement string as <code>${match[1]}</code>. The replacement
|
||
string is quoted so that the parameter is not substituted before the
|
||
start of filename generation.</p>
|
||
<p>The following <code>f</code>, <code>F</code>, <code>w</code> and <code>W</code> modifiers work only with parameter
|
||
expansion and filename generation. They are listed here to provide a
|
||
single point of reference for all modifiers.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>f</code><br />
|
||
Repeats the immediately (without a colon) following modifier until
|
||
the resulting word doesn’t change any more.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>F:``expr``:</code><br />
|
||
Like <code>f</code>, 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 ‘<code>:</code>’; if
|
||
‘<code>(</code>’, ‘<code>[</code>’, or ‘<code>{</code>’ is used as the opening delimiter, the closing
|
||
delimiter should be ’<code>)</code>’, ‘<code>]</code>’, or ‘<code>}</code>’, respectively.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>w</code><br />
|
||
Makes the immediately following modifier work on each word in the
|
||
string.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>W:``sep``:</code><br />
|
||
Like <code>w</code> 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
|
||
‘<code>:</code>’; opening parentheses are handled specially, see above.</p>
|
||
</li>
|
||
</ul>
|
||
<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 <code><</code> or <code>></code> 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 <code>/dev/fd</code> 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 <code>></code> is selected then writing on this
|
||
special file will provide input for <code>list</code>. If <code><</code> 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-example">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 <code><</code> form for a
|
||
program that expects to lseek (see man page 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
|
||
<code><<<</code>. 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 <code>=</code> form is useful as both the <code>/dev/fd</code> 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 man page 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 <code>MULTIOS</code> option is set) as:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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-example">paste <(cut -f1 file1) <(cut -f3 file2) > >(process)
|
||
</code></pre>
|
||
</div>
|
||
<p>(note that no <code>MULTIOS</code> 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-example">{ 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
|
||
‘<code>&!</code>’ or ‘<code>&|</code>’ 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-example">(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-example">() {
|
||
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-example">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 ‘<code>$</code>’ 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 <code>SH_WORD_SPLIT</code> 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-example">array=("first word" "" "third word")
|
||
scalar="only word"
|
||
</code></pre>
|
||
</div>
|
||
<p>then <code>$array</code> substitutes two words, ‘<code>first word</code>’ and ‘<code>third word</code>’,
|
||
and <code>$scalar</code> substitutes a single word ‘<code>only word</code>’. Note that second
|
||
element of <code>array</code> was elided. Scalar parameters can be elided too if
|
||
their value is null (empty). To avoid elision, use quoting as follows:
|
||
<code>"$scalar"</code> for scalars and <code>"${array[@]}"</code> or <code>"${(@)array}"</code> for
|
||
arrays. (The last two forms are equivalent.)</p>
|
||
<p>Parameter expansions can involve <em>flags</em>, as in ‘<code>${(@kv)aliases}</code>’, and
|
||
other operators, such as ‘<code>${PREFIX:-"/usr/local"}</code>’. 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,
|
||
<code>${i:s/foo/bar/}</code> performs string substitution on the expansion of
|
||
parameter <code>$i</code>.</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>
|
||
<ul>
|
||
<li>
|
||
<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 <code>KSH_ARRAYS</code> is not set, are a single subscript or any
|
||
colon modifiers appearing after the name, or any of the characters
|
||
‘<code>^</code>’, ‘<code>=</code>’, ‘<code>~</code>’, ‘<code>#</code>’ or ‘<code>+</code>’ appearing before the name, all
|
||
of which work with or without braces.</p>
|
||
<p>If <code>name</code> is an array parameter, and the <code>KSH_ARRAYS</code> 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 <code>KSH_ARRAYS</code>, this is the first element of an array. No field
|
||
splitting is done on the result unless the <code>SH_WORD_SPLIT</code> option is
|
||
set. See also the flags <code>=</code> and <code>s:``string``:</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${+``name``}</code><br />
|
||
If <code>name</code> is the name of a set parameter ‘<code>1</code>’ is substituted,
|
||
otherwise ‘<code>0</code>’ is substituted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``-``word``}</code><br />
|
||
<code>${``name``:-``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``+``word``}</code><br />
|
||
<code>${``name``:+``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``=``word``}</code><br />
|
||
<code>${``name``:=``word``}</code><br />
|
||
<code>${``name``::=``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``?``word``}</code><br />
|
||
<code>${``name``:?``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>
|
||
</li>
|
||
</ul>
|
||
<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
|
||
<code>SH_WORD_SPLIT</code> option and the <code>=</code> flag, but not splitting by the
|
||
<code>s:``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 ‘<code>(@)</code>’ flag or the <code>name``[@]</code>
|
||
syntax is used, matching and replacement is performed on each array
|
||
element separately.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>${``name``#``pattern``}</code><br />
|
||
<code>${``name``##``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``%``pattern``}</code><br />
|
||
<code>${``name``%%``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``:#``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
|
||
‘<code>(M)</code>’ flag to remove the non-matched elements).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``:|``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``:*``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>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``:^``arrayname``}</code><br />
|
||
<code>${``name``:^^``arrayname``}</code><br />
|
||
Zips two arrays, such that the output array is twice as long as the
|
||
shortest (longest for ‘<code>:^^</code>’) of <code>name</code> and <code>arrayname</code>, with the
|
||
elements alternatingly being picked from them. For ‘<code>:^</code>’, 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-example">a=(1 2 3 4); b=(a b); print ${a:^b}
|
||
</code></pre>
|
||
</div>
|
||
<p>will output ‘<code>1 a 2 b</code>’. For ‘<code>:^^</code>’, then the input is repeated
|
||
until all of the longer array has been used up and the above will
|
||
output ‘<code>1 a 2 b 3 a 4 b</code>’.</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 ‘<code>a b</code>’ and ‘<code>1</code>’ 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-example">a=(a b); b=(1 2); print -l "${a:^b}"; print -l "${${a:^b}}"
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``:``offset``}</code><br />
|
||
<code>${``name``:``offset``:``length``}</code><br />
|
||
This syntax gives effects similar to parameter subscripting in the
|
||
form <code>$``name``[``start``,``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 <code>KSH_ARRAYS</code>.</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 <code>MULTIBYTE</code> 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-example">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 <code>$foo</code> if the substitution would otherwise
|
||
return a scalar, or the array starting at the fourth element if
|
||
<code>$foo</code> would return an array. Note that with the option <code>KSH_ARRAYS</code>
|
||
<code>$foo</code> always returns a scalar (regardless of the use of the offset
|
||
syntax) and a form such as <code>${foo[*]:3}</code> is required to extract
|
||
elements of an array named <code>foo</code>.</p>
|
||
<p>If <code>offset</code> is negative, the <code>-</code> may not appear immediately after
|
||
the <code>:</code> as this indicates the <code>${``name``:-``word``}</code> form of
|
||
substitution. Instead, a space may be inserted before the <code>-</code>.
|
||
Furthermore, neither <code>offset</code> nor <code>length</code> may begin with an
|
||
alphabetic character or <code>&</code> 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 <code>$</code> as this signifies
|
||
the intention (parameter substitution can easily be rendered
|
||
unreadable); however, as arithmetic substitution is performed, the
|
||
expression <code>${var: offs}</code> does work, retrieving the offset from
|
||
<code>$offs</code>.</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. <code>$@</code> or <code>$*</code>, then offset 0 instead refers to
|
||
<code>$0</code>, offset 1 refers to <code>$1</code>, and so on. In other words, the
|
||
positional parameter array is effectively extended by prepending
|
||
<code>$0</code>. Hence <code>${*:0:1}</code> substitutes <code>$0</code> and <code>${*:1:1}</code> substitutes
|
||
<code>$1</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${``name``/``pattern``/``repl``}</code><br />
|
||
<code>${``name``//``pattern``/``repl``}</code><br />
|
||
<code>${``name``:/``pattern``/``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 <code>${name/$opat/$npat}</code> will work, but obey the
|
||
usual rule that pattern characters in <code>$opat</code> are not treated
|
||
specially unless either the option <code>GLOB_SUBST</code> is set, or <code>$opat</code>
|
||
is instead substituted as <code>${~opat}</code>.</p>
|
||
<p>The <code>pattern</code> may begin with a ‘<code>#</code>’, in which case the <code>pattern</code>
|
||
must match at the start of the string, or ‘<code>%</code>’, in which case it
|
||
must match at the end of the string, or ‘<code>#%</code>’ 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 ‘<code>/</code>’ may also be omitted. To quote
|
||
the final ‘<code>/</code>’ in other cases it should be preceded by a single
|
||
backslash; this is not necessary if the ‘<code>/</code>’ occurs inside a
|
||
substituted parameter. Note also that the ‘<code>#</code>’, ‘<code>%</code>’ and ‘<code>#%</code> 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 <code>I</code> and <code>S</code> parameter expansion flags below; however,
|
||
the flags <code>M</code>, <code>R</code>, <code>B</code>, <code>E</code> and <code>N</code> are not useful.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 ‘<code>~</code>’ ensures that the text of <code>$sub</code> is treated as a
|
||
pattern rather than a plain string. In the first case, the longest
|
||
match for <code>t*e</code> is substituted and the result is ‘<code>spy star</code>’, while
|
||
in the second case, the shortest matches are taken and the result is
|
||
‘<code>spy spy lispy star</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<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 ‘<code>^</code>’, ‘<code>=</code>’, and ‘<code>~</code>’, below, must appear to the left of
|
||
‘<code>#</code>’ when these forms are combined.</p>
|
||
<p>If the option <code>POSIX_IDENTIFIERS</code> 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. <code>$#-</code> and <code>$#*</code> take the length of the string
|
||
<code>$-</code> and the array <code>$*</code> respectively. If <code>POSIX_IDENTIFIERS</code> is set,
|
||
then braces are required for the <code>#</code> to be treated in this fashion.</p>
|
||
</li>
|
||
<li>
|
||
<p><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 <code>RC_EXPAND_PARAM</code> option for the evaluation of <code>spec</code>;
|
||
if the ‘<code>^</code>’ is doubled, turn it off. When this option is set, array
|
||
expansions of the form <code>foo``${``xx``}``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., <code>${^var}</code> becomes
|
||
<code>{$var[1],$var[2],</code>...<code>}</code>, 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 <code>$var[``N``]</code> may
|
||
themselves be split into different list elements.</p>
|
||
</li>
|
||
<li>
|
||
<p><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 <code>SH_WORD_SPLIT</code> during
|
||
the evaluation of <code>spec</code>, but regardless of whether the parameter
|
||
appears in double quotes; if the ‘<code>=</code>’ 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 <code>IFS</code> 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 <code>A</code> flag.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${~``spec``}</code><br />
|
||
<span id="index-GLOB_005fSUBST_002c-toggle"></span></p>
|
||
<p>Turn on the <code>GLOB_SUBST</code> option for the evaluation of <code>spec</code>; if the
|
||
‘<code>~</code>’ 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 ‘<code>=</code>’ and ‘<code>!=</code>’ operators in conditions.</p>
|
||
<p>In nested substitutions, note that the effect of the <code>~</code> 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 <code>foo</code> is set to <code>*</code>, <code>${~foo//\*/*.c}</code> is
|
||
substituted by the pattern <code>*.c</code>, which may be expanded by filename
|
||
generation, but <code>${${~foo}//\*/*.c}</code> substitutes to the string
|
||
<code>*.c</code>, which will not be further expanded.</p>
|
||
</li>
|
||
</ul>
|
||
<p>If a <code>${</code>...<code>}</code> type parameter expression or a <code>$(</code>...<code>)</code> 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: <code>${${foo#head}%tail}</code> substitutes
|
||
the value of <code>$foo</code> with both ‘<code>head</code>’ and ‘<code>tail</code>’ deleted. The form
|
||
with <code>$(</code>...<code>)</code> is often useful in combination with the flags described
|
||
next; see the examples below. Each <code>name</code> or nested <code>${</code>...<code>}</code> 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,
|
||
<code>${(f)"$(foo)"}</code> quotes the result of <code>$(foo)</code>, but the flag ‘<code>(f)</code>’
|
||
(see below) is applied using the rules for unquoted expansions. Note
|
||
further that quotes are themselves nested in this context; for example,
|
||
in <code>"${(@f)"$(foo)"}"</code>, there are two sets of quotes, one surrounding
|
||
the whole expression, the other (redundant) surrounding the <code>$(foo)</code> 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, ‘(<code>q%q%q</code>)’ means the same thing
|
||
as the more readable ‘(<code>%%qqq</code>)’. The following flags are supported:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>#</code><br />
|
||
Evaluate the resulting words as numeric expressions and output the
|
||
characters corresponding to the resulting integer. Note that this
|
||
form is entirely distinct from use of the <code>#</code> without parentheses.</p>
|
||
<p>If the <code>MULTIBYTE</code> option is set and the number is greater than 127
|
||
(i.e. not an ASCII character) it is treated as a Unicode character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%</code><br />
|
||
Expand all <code>%</code> 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 <code>PROMPT_PERCENT</code>, <code>PROMPT_SUBST</code> and
|
||
<code>PROMPT_BANG</code> options.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>@</code><br />
|
||
In double quotes, array elements are put into separate words. E.g.,
|
||
‘<code>"${(@)foo}"</code>’ is equivalent to ‘<code>"${foo[@]}"</code>’ and
|
||
‘<code>"${(@)foo[1,2]}"</code>’ is the same as ‘<code>"$foo[1]" "$foo[2]"</code>’. This
|
||
is distinct from <em>field splitting</em> by the <code>f</code>, <code>s</code> or <code>z</code> flags,
|
||
which still applies within each array element.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>A</code><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
|
||
<code>${${(A``)``name``}[1]}</code> yields the full value of <code>name</code> when <code>name</code>
|
||
is scalar.</p>
|
||
<p>This assigns an array parameter with ‘<code>${</code>...<code>=</code>...<code>}</code>’,
|
||
‘<code>${</code>...<code>:=</code>...<code>}</code>’ or ‘<code>${</code>...<code>::=</code>...<code>}</code>’. If this flag is
|
||
repeated (as in ‘<code>AA</code>’), 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 ‘<code>${(AA)=``name``=</code>...<code>}</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>
|
||
</li>
|
||
<li>
|
||
<p><code>a</code><br />
|
||
Sort in array index order; when combined with ‘<code>O</code>’ sort in reverse
|
||
array index order. Note that ‘<code>a</code>’ is therefore equivalent to the
|
||
default but ‘<code>Oa</code>’ is useful for obtaining an array’s elements in
|
||
reverse order.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>b</code><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 <code>GLOB_SUBST</code>, including the <code>${~``...``}</code> switch.</p>
|
||
<p>Quoting using one of the <code>q</code> family of flags does not work for this
|
||
purpose since quotes are not stripped from non-pattern characters by
|
||
<code>GLOB_SUBST</code>. In other words,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">pattern=${(q)str}
|
||
[[ $str = ${~pattern} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>works if <code>$str</code> is ‘<code>a*b</code>’ but not if it is ‘<code>a b</code>’, whereas</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">pattern=${(b)str}
|
||
[[ $str = ${~pattern} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>is always true for any possible value of <code>$str</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>c</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>C</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>D</code><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 ‘<code>~</code>’ substitution: see <a href="#Filename-Expansion">Filename
|
||
Expansion</a>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>e</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>f</code><br />
|
||
Split the result of the expansion at newlines. This is a shorthand
|
||
for ‘<code>ps:\n:</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>F</code><br />
|
||
Join the words of arrays together using newline as a separator. This
|
||
is a shorthand for ‘<code>pj:\n:</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>g:``opts``:</code><br />
|
||
Process escape sequences like the echo builtin when no options are
|
||
given (<code>g::</code>). With the <code>o</code> option, octal escapes don’t take a
|
||
leading zero. With the <code>c</code> option, sequences like ‘<code>^X</code>’ are also
|
||
processed. With the <code>e</code> option, processes ‘<code>\M-t</code>’ and similar
|
||
sequences like the print builtin. With both of the <code>o</code> and <code>e</code>
|
||
options, behaves like the print builtin except that in none of these
|
||
modes is ‘<code>\c</code>’ interpreted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>i</code><br />
|
||
Sort case-insensitively. May be combined with ‘<code>n</code>’ or ‘<code>O</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>k</code><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
|
||
<code>KSH_ARRAYS</code> option a subscript ‘<code>[*]</code>’ or ‘<code>[@]</code>’ is needed to
|
||
operate on the whole array, as usual.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>L</code><br />
|
||
Convert all letters in the result to lower case.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>n</code><br />
|
||
Sort decimal integers numerically; if the first differing characters
|
||
of two test strings are not digits, sorting is lexical. Integers
|
||
with more initial zeroes are sorted before those with fewer or none.
|
||
Hence the array ‘<code>foo1 foo02 foo2 foo3 foo20 foo23</code>’ is sorted into
|
||
the order shown. May be combined with ‘<code>i</code>’ or ‘<code>O</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>o</code><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 ‘<code>a</code>’, ‘<code>i</code>’ or ‘<code>n</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>O</code><br />
|
||
Sort the resulting words in descending order; ‘<code>O</code>’ without ‘<code>a</code>’,
|
||
‘<code>i</code>’ or ‘<code>n</code>’ sorts in reverse lexical order. May be combined
|
||
with ‘<code>a</code>’, ‘<code>i</code>’ or ‘<code>n</code>’ to reverse the order of sorting.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>P</code><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 <code>typeset</code> 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 ‘<code>foo=bar</code>’ and ‘<code>bar=baz</code>’, the strings
|
||
<code>${(P)foo}</code>, <code>${(P)${foo}}</code>, and <code>${(P)$(echo bar)}</code> will be
|
||
expanded to ‘<code>baz</code>’.</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 ‘<code>name=assoc</code>’ where the
|
||
parameter <code>assoc</code> is an associative array, then
|
||
‘<code>${${(P)name}[elt]}</code>’ refers to the element of the associative
|
||
subscripted ‘<code>elt</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>q</code><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 <code>$</code>. 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 <code>q-</code> is given (only a single <code>q</code> 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 <code>q+</code> 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
|
||
<code>typeset</code> family of commands.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Q</code><br />
|
||
Remove one level of quotes from the resulting words.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>t</code><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 (‘<code>-</code>’). The first keyword in the string
|
||
describes the main type, it can be one of ‘<code>scalar</code>’, ‘<code>array</code>’,
|
||
‘<code>integer</code>’, ‘<code>float</code>’ or ‘<code>association</code>’. The other keywords
|
||
describe the type in more detail:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>local</code><br />
|
||
for local parameters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>left</code><br />
|
||
for left justified parameters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>right_blanks</code><br />
|
||
for right justified parameters with leading blanks</p>
|
||
</li>
|
||
<li>
|
||
<p><code>right_zeros</code><br />
|
||
for right justified parameters with leading zeros</p>
|
||
</li>
|
||
<li>
|
||
<p><code>lower</code><br />
|
||
for parameters whose value is converted to all lower case when
|
||
it is expanded</p>
|
||
</li>
|
||
<li>
|
||
<p><code>upper</code><br />
|
||
for parameters whose value is converted to all upper case when
|
||
it is expanded</p>
|
||
</li>
|
||
<li>
|
||
<p><code>readonly</code><br />
|
||
for readonly parameters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>tag</code><br />
|
||
for tagged parameters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>export</code><br />
|
||
for exported parameters</p>
|
||
</li>
|
||
<li>
|
||
<p><code>unique</code><br />
|
||
for arrays which keep only the first occurrence of duplicated
|
||
values</p>
|
||
</li>
|
||
<li>
|
||
<p><code>hide</code><br />
|
||
for parameters with the ‘hide’ flag</p>
|
||
</li>
|
||
<li>
|
||
<p><code>hideval</code><br />
|
||
for parameters with the ‘hideval’ flag</p>
|
||
</li>
|
||
<li>
|
||
<p><code>special</code><br />
|
||
for special parameters defined by the shell</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><code>u</code><br />
|
||
Expand only the first occurrence of each unique word.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>U</code><br />
|
||
Convert all letters in the result to upper case.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>v</code><br />
|
||
Used with <code>k</code>, 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>
|
||
</li>
|
||
<li>
|
||
<p><code>V</code><br />
|
||
Make any special characters in the resulting words visible.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>w</code><br />
|
||
With <code>${#``name``}</code>, count words in arrays or strings; the <code>s</code> flag
|
||
may be used to set a word delimiter.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>W</code><br />
|
||
Similar to <code>w</code> with the difference that empty words between repeated
|
||
delimiters are also counted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>X</code><br />
|
||
With this flag, parsing errors occurring with the <code>Q</code>, <code>e</code> and <code>#</code>
|
||
flags or the pattern matching forms such as
|
||
‘<code>${``name``#``pattern``}</code>’ are reported. Without the flag, errors
|
||
are silently ignored.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>z</code><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 <code>INTERACTIVE_COMMENTS</code> option unset
|
||
(however, see the <code>Z</code> flag below for related options)</p>
|
||
<p>Note that this is done very late, even later than the ‘<code>(s)</code>’ flag.
|
||
So to access single words in the result use nested expansions as in
|
||
‘<code>${${(z)foo}[2]}</code>’. Likewise, to remove the quotes in the
|
||
resulting words use ‘<code>${(Q)${(z)foo}}</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>0</code><br />
|
||
Split the result of the expansion on null bytes. This is a shorthand
|
||
for ‘<code>ps:\0:</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The following flags (except <code>p</code>) are followed by one or more arguments
|
||
as shown. Any character, or the matching pairs ‘<code>(</code>...<code>)</code>’, ‘<code>{</code>...<code>}</code>’,
|
||
‘<code>[</code>...<code>]</code>’, or ‘<code><</code>...<code>></code>’, 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>
|
||
<ul>
|
||
<li>
|
||
<p><code>p</code><br />
|
||
Recognize the same escape sequences as the <code>print</code> 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-example">sep=:
|
||
val=a:b:c
|
||
print ${(ps.$sep.)val}
|
||
</code></pre>
|
||
</div>
|
||
<p>splits the variable on a <code>:</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>~</code><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 <code>~</code> within the same set of parentheses. Compare
|
||
with <code>~</code> 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-example">[[ "?" = ${(~j.|.)array} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>treats ‘<code>|</code>’ as a pattern and succeeds if and only if <code>$array</code>
|
||
contains the string ‘<code>?</code>’ as an element. The <code>~</code> may be repeated to
|
||
toggle the behaviour; its effect only lasts to the end of the
|
||
parenthesised group.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>j:``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 <code>s:``string``:</code> flag or
|
||
the <code>SH_WORD_SPLIT</code> option.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>l:``expr``::``string1``::``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
|
||
<code>$IFS</code> is used instead.</p>
|
||
<p>If the <code>MULTIBYTE</code> option is in effect, the flag <code>m</code> 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 <code>MULTIBYTE</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><code>m</code><br />
|
||
Only useful together with one of the flags <code>l</code> or <code>r</code> or with the
|
||
<code>#</code> length operator when the <code>MULTIBYTE</code> 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 <code>m</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><code>r:``expr``::``string1``::``string2``:</code><br />
|
||
As <code>l</code>, 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>
|
||
</li>
|
||
<li>
|
||
<p><code>s:``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 <code>IFS</code> parameter. See also the <code>=</code> flag and the
|
||
<code>SH_WORD_SPLIT</code> 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-example">line="one::three"
|
||
print -l "${(s.:.)line}"
|
||
</code></pre>
|
||
</div>
|
||
<p>produces two lines of output for <code>one</code> and <code>three</code> and elides the
|
||
empty field. To override this behaviour, supply the ‘<code>(@)</code>’ flag as
|
||
well, i.e. <code>"${(@s.:.)line}"</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>Z:``opts``:</code><br />
|
||
As <code>z</code> but takes a combination of option letters between a following
|
||
pair of delimiter characters. With no options the effect is
|
||
identical to <code>z</code>. <code>(Z+c+)</code> 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. <code>(Z+C+)</code> causes comments to
|
||
be parsed and removed. The rule for comments is standard: anything
|
||
between a word starting with the third character of <code>$HISTCHARS</code>,
|
||
default <code>#</code>, up to the next newline is a comment. <code>(Z+n+)</code> causes
|
||
unquoted newlines to be treated as ordinary whitespace, else they
|
||
are treated as if they are shell code delimiters and converted to
|
||
semicolons. Options are combined within the same set of delimiters,
|
||
e.g. <code>(Z+Cn+)</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>_:``flags``:</code><br />
|
||
The underscore (<code>_</code>) 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>
|
||
</li>
|
||
</ul>
|
||
<p>The following flags are meaningful with the <code>${</code>...<code>#</code>...<code>}</code> or
|
||
<code>${</code>...<code>%</code>...<code>}</code> forms. The <code>S</code> and <code>I</code> flags may also be used with the
|
||
<code>${</code>...<code>/</code>...<code>}</code> forms.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>S</code><br />
|
||
With <code>#</code> or <code>##</code>, search for the match that starts closest to the
|
||
start of the string (a ‘substring match’). Of all matches at a
|
||
particular position, <code>#</code> selects the shortest and <code>##</code> the longest:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">% str="aXbXc"
|
||
% echo ${(S)str#X*}
|
||
abXc
|
||
% echo ${(S)str##X*}
|
||
a
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
<p>With <code>%</code> or <code>%%</code>, search for the match that starts closest to the
|
||
end of the string:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">% str="aXbXc"
|
||
% echo ${(S)str%X*}
|
||
aXbc
|
||
% echo ${(S)str%%X*}
|
||
aXb
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
<p>(Note that <code>%</code> and <code>%%</code> don’t search for the match that ends closest
|
||
to the end of the string, as one might expect.)</p>
|
||
<p>With substitution via <code>${</code>...<code>/</code>...<code>}</code> or <code>${</code>...<code>//</code>...<code>}</code>,
|
||
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-example">% str="abab"
|
||
% echo ${str/*b/_}
|
||
_
|
||
% echo ${(S)str/*b/_}
|
||
_ab
|
||
%
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p><code>I:``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 <code>S</code>
|
||
flag, or with <code>${</code>...<code>/</code>...<code>}</code> (only the <code>expr</code>th match is
|
||
substituted) or <code>${</code>...<code>//</code>...<code>}</code> (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 <code>${</code>...<code>%</code>...<code>}</code> and <code>${</code>...<code>%%</code>...<code>}</code> 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-example">which switch is the right switch for Ipswich?
|
||
</code></pre>
|
||
</div>
|
||
<p>substitutions of the form <code>${</code>(<code>SI:``N``:</code>)<code>string#w*ch}</code> as <code>N</code>
|
||
increases from 1 will match and remove ‘<code>which</code>’, ‘<code>witch</code>’,
|
||
‘<code>witch</code>’ and ‘<code>wich</code>’; the form using ‘<code>##</code>’ will match and
|
||
remove ‘<code>which switch is the right switch for Ipswich</code>’, ‘<code>witch is the right switch for Ipswich</code>’, ‘<code>witch for Ipswich</code>’ and ‘<code>wich</code>’.
|
||
The form using ‘<code>%</code>’ will remove the same matches as for ‘<code>#</code>’, but
|
||
in reverse order, and the form using ‘<code>%%</code>’ will remove the same
|
||
matches as for ‘<code>##</code>’ in reverse order.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>B</code><br />
|
||
Include the index of the beginning of the match in the result.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>E</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>M</code><br />
|
||
Include the matched portion in the result.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>N</code><br />
|
||
Include the length of the match in the result.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>R</code><br />
|
||
Include the unmatched portion in the result (the <em>R</em>est).</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Rules"></span></p>
|
||
<h3 id="1432-rules"><a class="header" href="#1432-rules">14.3.2 Rules</a></h3>
|
||
<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>
|
||
<ul>
|
||
<li>
|
||
<p><code>1.</code> <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 ‘<code>(P)</code>’ flag is present, the flags and any
|
||
subscripts apply directly to the value of the nested substitution;
|
||
for example, the expansion <code>${${foo}}</code> behaves exactly the same as
|
||
<code>${foo}</code>. When the ‘<code>(P)</code>’ 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 <code>${${(P)foo}}</code> may differ from
|
||
<code>${(P)foo}</code>.</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 <code>~</code> and <code>=</code>). Thus, for
|
||
example, <code>${${:-=cat}:h}</code> expands to the directory where the <code>cat</code>
|
||
program resides. (Explanation: the internal substitution has no
|
||
parameter but a default value <code>=cat</code>, which is expanded by filename
|
||
expansion to a full path; the outer substitution then applies the
|
||
modifier <code>:h</code> and takes the directory part of the path.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>2.</code> <em>Internal parameter flags</em><br />
|
||
Any parameter flags set by one of the <code>typeset</code> family of commands,
|
||
in particular the <code>-L</code>, <code>-R</code>, <code>-Z</code>, <code>-u</code> and <code>-l</code> options for
|
||
padding and capitalization, are applied directly to the parameter
|
||
value. Note these flags are options to the command, e.g. ‘<code>typeset -Z</code>’; they are not the same as the flags used within parameter
|
||
substitutions.</p>
|
||
<p>At the outermost level of substitution, the ‘<code>(P)</code>’ flag (rule <code>4.</code>)
|
||
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
|
||
<code>${${(P)foo}}</code> form (rule <code>25.</code>).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>3.</code> <em>Parameter subscripting</em><br />
|
||
If the value is a raw parameter reference with a subscript, such as
|
||
<code>${``var``[3]}</code>, 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 <code>var</code> is an array, <code>${var[1][2]}</code> is the
|
||
second character of the first word, but <code>${var[2,4][2]}</code> 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 ‘<code>(k)</code>’ and ‘<code>(v)</code>’ which alter the result of
|
||
subscripting are applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>4.</code> <em>Parameter name replacement</em><br />
|
||
At the outermost level of nesting only, the ‘<code>(P)</code>’ 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 ‘<code>(P)</code>’ flag appears in
|
||
a nested substitution.</p>
|
||
<p>If the value so far names a parameter that has internal flags (rule
|
||
<code>2.</code>), those internal flags are applied to the new value after
|
||
replacement.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>5.</code> <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 ‘<code>(@)</code>’ flag nor a ‘<code>#</code>’
|
||
length operator is present at the current level, then words of the
|
||
value are joined with the first character of the parameter <code>$IFS</code>,
|
||
by default a space, between each word (single word arrays are not
|
||
modified). If the ‘<code>(j)</code>’ flag is present, that is used for joining
|
||
instead of <code>$IFS</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>6.</code> <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 <code>3.</code>, multiple subscripts can appear. Note that
|
||
<code>${foo[2,4][2]}</code> is thus equivalent to <code>${${foo[2,4]}[2]}</code> and also
|
||
to <code>"${${(@)foo[2,4]}[2]}"</code> (the nested substitution returns an
|
||
array in both cases), but not to <code>"${${foo[2,4]}[2]}"</code> (the nested
|
||
substitution returns a scalar because of the quotes).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>7.</code> <em>Modifiers</em><br />
|
||
Any modifiers, as specified by a trailing ‘<code>#</code>’, ‘<code>%</code>’, ‘<code>/</code>’
|
||
(possibly doubled) or by a set of modifiers of the form ‘<code>:...</code>’
|
||
(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>
|
||
</li>
|
||
<li>
|
||
<p><code>8.</code> <em>Character evaluation</em><br />
|
||
Any ‘<code>(#)</code>’ flag is applied, evaluating the result so far
|
||
numerically as a character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>9.</code> <em>Length</em><br />
|
||
Any initial ‘<code>#</code>’ modifier, i.e. in the form <code>${#``var``}</code>, is used
|
||
to evaluate the length of the expression so far.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>10.</code> <em>Forced joining</em><br />
|
||
If the ‘<code>(j)</code>’ flag is present, or no ‘<code>(j)</code>’ flag is present but
|
||
the string is to be split as given by rule <code>11.</code>, and joining did
|
||
not take place at rule <code>5.</code>, any words in the value are joined
|
||
together using the given string or the first character of <code>$IFS</code> if
|
||
none. Note that the ‘<code>(F)</code>’ flag implicitly supplies a string for
|
||
joining in this manner.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>11.</code> <em>Simple word splitting</em><br />
|
||
If one of the ‘<code>(s)</code>’ or ‘<code>(f)</code>’ flags are present, or the ‘<code>=</code>’
|
||
specifier was present (e.g. <code>${=``var``}</code>), the word is split on
|
||
occurrences of the specified string, or (for <code>=</code> with neither of the
|
||
two flags present) any of the characters in <code>$IFS</code>.</p>
|
||
<p>If no ‘<code>(s)</code>’, ‘<code>(f)</code>’ or ‘<code>=</code>’ was given, but the word is not
|
||
quoted and the option <code>SH_WORD_SPLIT</code> is set, the word is split on
|
||
occurrences of any of the characters in <code>$IFS</code>. Note this step, too,
|
||
takes place at all levels of a nested substitution.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>12.</code> <em>Case modification</em><br />
|
||
Any case modification from one of the flags ‘<code>(L)</code>’, ‘<code>(U)</code>’ or
|
||
‘<code>(C)</code>’ is applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>13.</code> <em>Escape sequence replacement</em><br />
|
||
First any replacements from the ‘<code>(g)</code>’ flag are performed, then any
|
||
prompt-style formatting from the ‘<code>(%)</code>’ family of flags is applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>14.</code> <em>Quote application</em><br />
|
||
Any quoting or unquoting using ‘<code>(q)</code>’ and ‘<code>(Q)</code>’ and related flags
|
||
is applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>15.</code> <em>Directory naming</em><br />
|
||
Any directory name substitution using ‘<code>(D)</code>’ flag is applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>16.</code> <em>Visibility enhancement</em><br />
|
||
Any modifications to make characters visible using the ‘<code>(V)</code>’ flag
|
||
are applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>17.</code> <em>Lexical word splitting</em><br />
|
||
If the ’<code>(z)</code>’ flag or one of the forms of the ’<code>(Z)</code>’ 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 <code>11.</code>: it does not use <code>$IFS</code>,
|
||
and does not cause forced joining.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>18.</code> <em>Uniqueness</em><br />
|
||
If the result is an array and the ‘<code>(u)</code>’ flag was present,
|
||
duplicate elements are removed from the array.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>19.</code> <em>Ordering</em><br />
|
||
If the result is still an array and one of the ‘<code>(o)</code>’ or ‘<code>(O)</code>’
|
||
flags was present, the array is reordered.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>20.</code> <code>RC_EXPAND_PARAM</code><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 <code>RC_EXPAND_PARAM</code> option or the ‘<code>^</code>’
|
||
flag.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>21.</code> <em>Re-evaluation</em><br />
|
||
Any ‘<code>(e)</code>’ flag is applied to the value, forcing it to be
|
||
re-examined for new parameter substitutions, but also for command
|
||
and arithmetic substitutions.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>22.</code> <em>Padding</em><br />
|
||
Any padding of the value by the ‘<code>(l.``fill``.)</code>’ or
|
||
‘<code>(r.``fill``.)</code>’ flags is applied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>23.</code> <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 <code>IFS</code>
|
||
between. So in ‘<code>${(P``)${(f``)lines}}</code>’ the value of <code>${lines}</code> is
|
||
split at newlines, but then must be joined again before the ‘<code>(P)</code>’
|
||
flag can be applied.</p>
|
||
<p>If a single word is not required, this rule is skipped.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>24.</code> <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>
|
||
</li>
|
||
<li>
|
||
<p><code>25.</code> <em>Nested parameter name replacement</em><br />
|
||
If the ‘<code>(P)</code>’ flag is present and rule <code>4.</code> 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 <code>2.</code>) applied to the new value.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Examples-1"></span></p>
|
||
<h3 id="1433-examples"><a class="header" href="#1433-examples">14.3.3 Examples</a></h3>
|
||
<p>The flag <code>f</code> is useful to split a double-quoted substitution line by
|
||
line. For example, <code>${(f)"$(<``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 <code>$foo</code> contains the array <code>(bar baz``)</code>:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>"${(@)${foo}[1]}"</code><br />
|
||
This produces the result <code>b</code>. First, the inner substitution
|
||
<code>"${foo}"</code>, which has no array (<code>@</code>) flag, produces a single word
|
||
result <code>"bar baz"</code>. The outer substitution <code>"${(@)...[1]}"</code> detects
|
||
that this is a scalar, so that (despite the ‘<code>(@)</code>’ flag) the
|
||
subscript picks the first character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>"${${(@)foo}[1]}"</code><br />
|
||
This produces the result ‘<code>bar</code>’. In this case, the inner
|
||
substitution <code>"${(@)foo}"</code> produces the array ‘<code>(bar baz``)</code>’. The
|
||
outer substitution <code>"${...[1]}"</code> detects that this is an array and
|
||
picks the first word. This is similar to the simple case
|
||
<code>"${foo[1]}"</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>As an example of the rules for word splitting and joining, suppose
|
||
<code>$foo</code> contains the array ‘<code>(ax1 bx1``)</code>’. Then</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>${(s/x/)foo}</code><br />
|
||
produces the words ‘<code>a</code>’, ‘<code>1 b</code>’ and ‘<code>1</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${(j/x/s/x/)foo}</code><br />
|
||
produces ‘<code>a</code>’, ‘<code>1</code>’, ‘<code>b</code>’ and ‘<code>1</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>${(s/x/)foo%%1*}</code><br />
|
||
produces ‘<code>a</code>’ and ‘<code> b</code>’ (note the extra space). As substitution
|
||
occurs before either joining or splitting, the operation first
|
||
generates the modified array <code>(ax bx``)</code>, which is joined to give
|
||
<code>"ax bx"</code>, and then split to give ‘<code>a</code>’, ‘<code> b</code>’ and ‘’. The final
|
||
empty string will then be elided, as it is not in double quotes.</p>
|
||
</li>
|
||
</ul>
|
||
<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
|
||
‘<code>$(</code>...<code>)</code>’, or quoted with grave accents, like ‘<code>‘</code>...<code>‘</code>’, 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 <code>IFS</code> parameter.
|
||
<span id="index-IFS_002c-use-of-1"></span></p>
|
||
<p>The substitution ‘<code>$(cat</code> <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 <code>GLOB_SUBST</code> 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``{``xx``,``yy``,``zz``}``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``..``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 <code>-</code> 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``..``n2``..``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
|
||
‘<code>{-99..100..01}</code>’ 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``..``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. ‘<code>{d..a}</code>’ is substituted as ‘<code>d c b a</code>’.</p>
|
||
<p>If a brace expression matches none of the above forms, it is left
|
||
unchanged, unless the option <code>BRACE_CCL</code> (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 <code>[</code>...<code>]</code> expression in filename generation: ‘<code>-</code>’ is treated
|
||
specially to denote a range of characters, but ‘<code>^</code>’ or ‘<code>!</code>’ as the
|
||
first character is treated normally. For example, ‘<code>{abcdef0-9}</code>’
|
||
expands to 16 words <code>0 1 2 3 4 5 6 7 8 9 a b c d e f</code>.</p>
|
||
<p>Note that brace expansion is not part of filename generation (globbing);
|
||
an expression such as <code>*/{foo,bar}</code> is split into two separate words
|
||
<code>*/foo</code> and <code>*/bar</code> 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 <code>*/(foo|bar)</code>, 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 ‘<code>~</code>’. If it
|
||
does, then the word up to a ‘<code>/</code>’, or the end of the word if there is no
|
||
‘<code>/</code>’, is checked to see if it can be substituted in one of the ways
|
||
described here. If so, then the ‘<code>~</code>’ and the checked portion are
|
||
replaced with the appropriate substitute value.</p>
|
||
<p>A ‘<code>~</code>’ by itself is replaced by the value of <code>$HOME</code>. A ‘<code>~</code>’ followed
|
||
by a ‘<code>+</code>’ or a ‘<code>-</code>’ is replaced by current or previous working
|
||
directory, respectively.</p>
|
||
<p>A ‘<code>~</code>’ followed by a number is replaced by the directory at that
|
||
position in the directory stack. ‘<code>~0</code>’ is equivalent to ‘<code>~+</code>’, and
|
||
‘<code>~1</code>’ is the top of the stack. ‘<code>~+</code>’ followed by a number is
|
||
replaced by the directory at that position in the directory stack.
|
||
‘<code>~+0</code>’ is equivalent to ‘<code>~+</code>’, and ‘<code>~+1</code>’ is the top of the stack.
|
||
‘<code>~-</code>’ followed by a number is replaced by the directory that many
|
||
positions from the bottom of the stack. ‘<code>~-0</code>’ is the bottom of the
|
||
stack. <span id="index-PUSHD_005fMINUS_002c-use-of"></span> The
|
||
<code>PUSHD_MINUS</code> option exchanges the effects of ‘<code>~+</code>’ and ‘<code>~-</code>’ where
|
||
they are followed by a number.</p>
|
||
<hr />
|
||
<p><span id="Dynamic-named-directories"></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 <code>zsh_directory_name</code> exists, or the shell variable
|
||
<code>zsh_directory_name_functions</code> 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 ‘<code>~</code>’ 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 <code>n</code> (for name) and
|
||
<code>namstr</code>. It should either set the array <code>reply</code> 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 <code>NOMATCH</code> 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 <code>%~</code> in prompts. In this case each function is passed two
|
||
arguments: the string <code>d</code> (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 <code>/home/myname/src/zsh</code> and the dynamic name for
|
||
<code>/home/myname/src</code> (which has 16 characters) is <code>s</code>, then the function
|
||
sets</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>n</code> and <code>d</code>
|
||
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 <code>d</code> should cause a non-zero status to be returned.</p>
|
||
<p>The completion system calls ‘<code>zsh_directory_name c</code>’ followed by
|
||
equivalent calls to elements of the array
|
||
<code>zsh_directory_name_functions</code>, 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 <code>p:</code> to directories below
|
||
<code>/home/pws/perforce</code>. In this simple case a static name for the
|
||
directory would be just as effective.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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></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 ‘<code>~</code>’ followed by anything not already covered consisting of any
|
||
number of alphanumeric characters or underscore (‘<code>_</code>’), hyphen (‘<code>-</code>’),
|
||
or dot (‘<code>.</code>’) 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 ‘<code>~</code>’ is the name of a string shell parameter whose
|
||
value begins with a ‘<code>/</code>’. 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 <code>-d</code> option to
|
||
the <code>hash</code> builtin.</p>
|
||
<p>When the shell prints a path (e.g. when expanding <code>%~</code> 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 ‘<code>~</code>’ 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 <code>$PWD</code> and <code>$OLDPWD</code> are never abbreviated in
|
||
this fashion.</p>
|
||
<hr />
|
||
<p><span id="g_t_0060_003d_0027-expansion"></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 ‘<code>=</code>’ and the <code>EQUALS</code> 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></p>
|
||
<h3 id="1474-notes"><a class="header" href="#1474-notes">14.7.4 Notes</a></h3>
|
||
<p>Filename expansion is performed on the right hand side of a parameter
|
||
assignment, including those appearing after commands of the <code>typeset</code>
|
||
family. In this case, the right hand side will be treated as a
|
||
colon-separated list in the manner of the <code>PATH</code> parameter, so that a
|
||
‘<code>~</code>’ or an ‘<code>=</code>’ following a ‘<code>:</code>’ is eligible for expansion. All
|
||
such behaviour can be disabled by quoting the ‘<code>~</code>’, the ‘<code>=</code>’, or the
|
||
whole expression (but not simply the colon); the <code>EQUALS</code> option is also
|
||
respected.</p>
|
||
<p>If the option <code>MAGIC_EQUAL_SUBST</code> is set, any unquoted shell argument in
|
||
the form ‘<code>identifier``=``expression</code>’ becomes eligible for file
|
||
expansion as described in the previous paragraph. Quoting the first
|
||
‘<code>=</code>’ 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 ‘<code>*</code>’,
|
||
‘<code>(</code>’, ‘<code>|</code>’, ‘<code><</code>’, ‘<code>[</code>’, or ‘<code>?</code>’, it is regarded as a pattern for
|
||
filename generation, unless the <code>GLOB</code> option is unset.
|
||
<span id="index-GLOB_002c-use-of"></span> If the <code>EXTENDED_GLOB</code> option
|
||
is set, <span id="index-EXTENDED_005fGLOB_002c-use-of"></span> the ‘<code>^</code>’
|
||
and ‘<code>#</code>’ 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 <code>NULL_GLOB</code> option is set,
|
||
<span id="index-NULL_005fGLOB_002c-use-of"></span> in which case the
|
||
word is deleted; or unless the <code>NOMATCH</code> 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 ‘<code>/</code>’ must be matched explicitly;
|
||
also, a ‘<code>.</code>’ must be matched explicitly at the beginning of a pattern
|
||
or after a ‘<code>/</code>’, unless the <code>GLOB_DOTS</code> option is set.
|
||
<span id="index-GLOB_005fDOTS_002c-use-of"></span> No filename
|
||
generation pattern matches the files ‘<code>.</code>’ or ‘<code>..</code>’. In other instances
|
||
of pattern matching, the ‘<code>/</code>’ and ‘<code>.</code>’ 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>
|
||
<ul>
|
||
<li>
|
||
<p><code>*</code><br />
|
||
Matches any string, including the null string.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>?</code><br />
|
||
Matches any character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[</code>...<code>]</code><br />
|
||
Matches any of the enclosed characters. Ranges of characters can be
|
||
specified by separating two characters by a ‘<code>-</code>’. A ‘<code>-</code>’ or ‘<code>]</code>’
|
||
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 man
|
||
page ctype(3):</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>[:alnum:]</code><br />
|
||
The character is alphanumeric</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:alpha:]</code><br />
|
||
The character is alphabetic</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:ascii:]</code><br />
|
||
The character is 7-bit, i.e. is a single-byte character without
|
||
the top bit set.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:blank:]</code><br />
|
||
The character is a blank character</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:cntrl:]</code><br />
|
||
The character is a control character</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:digit:]</code><br />
|
||
The character is a decimal digit</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:graph:]</code><br />
|
||
<code>[:lower:]</code><br />
|
||
The character is a lowercase letter</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:print:]</code><br />
|
||
<code>[:punct:]</code><br />
|
||
<code>[:space:]</code><br />
|
||
The character is whitespace</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:upper:]</code><br />
|
||
The character is an uppercase letter</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:xdigit:]</code><br />
|
||
The character is a hexadecimal digit</p>
|
||
</li>
|
||
</ul>
|
||
<p>Another set of named classes is handled internally by the shell and
|
||
is not sensitive to the locale:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>[:IDENT:]</code><br />
|
||
The character is allowed to form part of a shell identifier,
|
||
such as a parameter name</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:IFS:]</code><br />
|
||
The character is used as an input field separator, i.e. is
|
||
contained in the <code>IFS</code> parameter</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:IFSSPACE:]</code><br />
|
||
The character is an IFS white space character; see the
|
||
documentation for <code>IFS</code> in <a href="Parameters.html#Parameters-Used-By-The-Shell">Parameters Used By The
|
||
Shell</a>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:INCOMPLETE:]</code><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
|
||
‘<code>[[:INCOMPLETE:]]*</code>’. This will never match a sequence
|
||
starting with a valid multibyte character.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[:INVALID:]</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>[:WORD:]</code><br />
|
||
The character is treated as part of a word; this test is
|
||
sensitive to the value of the <code>WORDCHARS</code> parameter</p>
|
||
</li>
|
||
</ul>
|
||
<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 ‘<code>[[:alnum:]]</code>’. Named character sets can be used
|
||
alongside other types, e.g. ‘<code>[[:alpha:]0-9]</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[^</code>...<code>]</code><br />
|
||
<code>[!</code>...<code>]</code><br />
|
||
Like <code>[</code>...<code>]</code>, except that it matches any character which is not in
|
||
the given set.</p>
|
||
</li>
|
||
<li>
|
||
<p><code><</code>[<code>x</code>]<code>-</code>[<code>y</code>]<code>></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 ‘<code><-></code>’
|
||
matches any number. To match individual digits, the <code>[</code>...<code>]</code> form
|
||
is more efficient.</p>
|
||
<p>Be careful when using other wildcards adjacent to patterns of this
|
||
form; for example, <code><0-9>*</code> will actually match any number
|
||
whatsoever at the start of the string, since the ‘<code><0-9></code>’ will
|
||
match the first digit, and the ‘<code>*</code>’ will match any others. This is
|
||
a trap for the unwary, but is match always succeeds. Expressions
|
||
such as ‘<code><0-9>[^[:digit:]]*</code>’ can be used instead.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>(</code>...<code>)</code><br />
|
||
Matches the enclosed pattern. This is used for grouping. If the
|
||
<code>KSH_GLOB</code> option is set, then a ‘<code>@</code>’, ‘<code>*</code>’, ‘<code>+</code>’, ‘<code>?</code>’ or ‘<code>!</code>’
|
||
immediately preceding the ‘<code>(</code>’ is treated specially, as detailed
|
||
below. The option <code>SH_GLOB</code> prevents bare parentheses from being
|
||
used in this way, though the <code>KSH_GLOB</code> option is still available.</p>
|
||
<p>Note that grouping cannot extend over multiple directories: it is an
|
||
error to have a ‘<code>/</code>’ 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, <code>foo/(a*/)#bar</code> matches
|
||
<code>foo/bar</code>, <code>foo/any/bar</code>, <code>foo/any/anyother/bar</code>, and so on.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``|``y</code><br />
|
||
Matches either <code>x</code> or <code>y</code>. This operator has lower precedence than
|
||
any other. The ‘<code>|</code>’ character must be within parentheses, to avoid
|
||
interpretation as a pipeline. The alternatives are tried in order
|
||
from left to right.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>^``x</code><br />
|
||
(Requires <code>EXTENDED_GLOB</code> to be set.) Matches anything except the
|
||
pattern <code>x</code>. This has a higher precedence than ‘<code>/</code>’, so
|
||
‘<code>^foo/bar</code>’ will search directories in ‘<code>.</code>’ except ‘<code>./foo</code>’
|
||
for a file named ‘<code>bar</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``~``y</code><br />
|
||
(Requires <code>EXTENDED_GLOB</code> 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 ‘<code>|</code>’, so ‘<code>*/*~foo/bar</code>’ will search for
|
||
all files in all directories in ‘<code>.</code>’ and then exclude ‘<code>foo/bar</code>’
|
||
if there was such a match. Multiple patterns can be excluded by
|
||
‘<code>foo``~``bar``~``baz</code>’. In the exclusion pattern (<code>y</code>), ‘<code>/</code>’ and
|
||
‘<code>.</code>’ are not treated specially the way they usually are in
|
||
globbing.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``#</code><br />
|
||
(Requires <code>EXTENDED_GLOB</code> to be set.) Matches zero or more
|
||
occurrences of the pattern <code>x</code>. This operator has high precedence;
|
||
‘<code>12#</code>’ is equivalent to ‘<code>1(2#)</code>’, rather than ‘<code>(12)#</code>’. It is
|
||
an error for an unquoted ‘<code>#</code>’ to follow something which cannot be
|
||
repeated; this includes an empty string, a pattern already followed
|
||
by ‘<code>##</code>’, or parentheses when part of a <code>KSH_GLOB</code> pattern (for
|
||
example, ‘<code>!(``foo``)#</code>’ is invalid and must be replaced by
|
||
‘<code>*(!(``foo``))</code>’).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>x``##</code><br />
|
||
(Requires <code>EXTENDED_GLOB</code> to be set.) Matches one or more
|
||
occurrences of the pattern <code>x</code>. This operator has high precedence;
|
||
‘<code>12##</code>’ is equivalent to ‘<code>1(2##)</code>’, rather than ‘<code>(12)##</code>’. No
|
||
more than two active ‘<code>#</code>’ characters may appear together. (Note the
|
||
potential clash with glob qualifiers in the form ‘<code>1(2##)</code>’ which
|
||
should therefore be avoided.)</p>
|
||
</li>
|
||
</ul>
|
||
<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 <code>KSH_GLOB</code> option is set, the effects of parentheses can be
|
||
modified by a preceding ‘<code>@</code>’, ‘<code>*</code>’, ‘<code>+</code>’, ‘<code>?</code>’ or ‘<code>!</code>’. This
|
||
character need not be unquoted to have special effects, but the ‘<code>(</code>’
|
||
must be.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>@(</code>...<code>)</code><br />
|
||
Match the pattern in the parentheses. (Like ‘<code>(</code>...<code>)</code>’.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*(</code>...<code>)</code><br />
|
||
Match any number of occurrences. (Like ‘<code>(</code>...<code>)#</code>’, except that
|
||
recursive directory searching is not supported.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>+(</code>...<code>)</code><br />
|
||
Match at least one occurrence. (Like ‘<code>(</code>...<code>)##</code>’, except that
|
||
recursive directory searching is not supported.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>?(</code>...<code>)</code><br />
|
||
Match zero or one occurrence. (Like ‘<code>(|</code>...<code>)</code>’.)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>!(</code>...<code>)</code><br />
|
||
Match anything but the expression in parentheses. (Like
|
||
‘<code>(^(</code>...<code>))</code>’.)</p>
|
||
</li>
|
||
</ul>
|
||
<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) ‘<code>^</code>’, ‘<code>/</code>’,
|
||
‘<code>~</code>’, ‘<code>|</code>’ (lowest); the remaining operators are simply treated from
|
||
left to right as part of a string, with ‘<code>#</code>’ and ‘<code>##</code>’ applying to the
|
||
shortest possible preceding unit (i.e. a character, ‘<code>?</code>’, ‘<code>[</code>...<code>]</code>’,
|
||
‘<code><</code>...<code>></code>’, or a parenthesised expression). As mentioned above, a
|
||
‘<code>/</code>’ used as a directory separator may not appear inside parentheses,
|
||
while a ‘<code>|</code>’ must do so; in patterns used in other contexts than
|
||
filename generation (for example, in <code>case</code> statements and tests within
|
||
‘<code>[[</code>...<code>]]</code>’), a ‘<code>/</code>’ is not special; and ‘<code>/</code>’ is also not special
|
||
after a ‘<code>~</code>’ 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>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 <code>EXTENDED_GLOB</code> option. All take the form <code>(#``X``)</code> where <code>X</code> may
|
||
have one of the following forms:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>i</code><br />
|
||
Case insensitive: upper or lower case characters in the pattern
|
||
match upper or lower case characters.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>l</code><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>
|
||
</li>
|
||
<li>
|
||
<p><code>I</code><br />
|
||
Case sensitive: locally negates the effect of <code>i</code> or <code>l</code> from that
|
||
point on.</p>
|
||
<p><span id="index-match"></span> <span id="index-mbegin"></span>
|
||
<span id="index-mend"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>b</code><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 <code>$match</code>, the indices of the beginning of
|
||
the matched parentheses in the array <code>$mbegin</code>, and the indices of
|
||
the end in the array <code>$mend</code>, 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
|
||
<code>$mend</code> and <code>$mbegin</code> may be used in subscripts; the <code>KSH_ARRAYS</code>
|
||
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-example">foo="a_string_with_a_message"
|
||
if [[ $foo = (a|an)_(#b)(*) ]]; then
|
||
print ${foo[$mbegin[1],$mend[1]]}
|
||
fi
|
||
</code></pre>
|
||
</div>
|
||
<p>prints ‘<code>string_with_a_message</code>’. Note that the first set of
|
||
parentheses is before the <code>(#b)</code> 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``#``pattern``}</code>, or a global
|
||
substitution, such as <code>${``param``//``pat``/``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 <code>m</code>
|
||
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 ‘<code>#</code>’ or ‘<code>##</code>’. Only the last match of
|
||
the parenthesis is remembered: for example, in ‘<code>[[ abab = (#b)([ab])# ]]</code>’, only the final ‘<code>b</code>’ is stored in <code>match[1]</code>. Thus
|
||
extra parentheses may be necessary to match the complete segment:
|
||
for example, use ‘<code>X((ab|cd)#)Y</code>’ to match a whole string of either
|
||
‘<code>ab</code>’ or ‘<code>cd</code>’ between ‘<code>X</code>’ and ‘<code>Y</code>’, using the value of
|
||
<code>$match[1]</code> rather than <code>$match[2]</code>.</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
|
||
<code>#</code> 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>
|
||
</li>
|
||
<li>
|
||
<p><code>B</code><br />
|
||
Deactivate backreferences, negating the effect of the <code>b</code> flag from
|
||
that point on.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>c``N``,``M</code><br />
|
||
The flag <code>(#c``N``,``M``)</code> can be used anywhere that the <code>#</code> or <code>##</code>
|
||
operators can be used except in the expressions ‘<code>(*/)#</code>’ and
|
||
‘<code>(*/)##</code>’ in filename generation, where ‘<code>/</code>’ 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``,``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 <code>(#c``N``)</code> requires exactly <code>N</code> matches; <code>(#c,``M``)</code> is
|
||
equivalent to specifying <code>N</code> as 0; <code>(#c``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>
|
||
</li>
|
||
<li>
|
||
<p><code>m</code><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 <code>$MATCH</code>, <code>$MBEGIN</code> and
|
||
<code>$MEND</code> 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-example">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
|
||
‘<code>vEldt jynx grImps wAqf zhO bUck</code>’.</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>
|
||
</li>
|
||
<li>
|
||
<p><code>M</code><br />
|
||
Deactivate the <code>m</code> flag, hence no references to match data will be
|
||
created.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>a``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>
|
||
</li>
|
||
<li>
|
||
<p><code>s</code>, <code>e</code><br />
|
||
Unlike the other flags, these have only a local effect, and each
|
||
must appear on its own: ‘<code>(#s)</code>’ and ‘<code>(#e)</code>’ are the only valid
|
||
forms. The ‘<code>(#s)</code>’ flag succeeds only at the start of the test
|
||
string, and the ‘<code>(#e)</code>’ flag succeeds only at the end of the test
|
||
string; they correspond to ‘<code>^</code>’ and ‘<code>$</code>’ 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,
|
||
‘<code>*((#s)|/)test((#e)|/)*</code>’ matches a path segment ‘<code>test</code>’ in
|
||
any of the following strings: <code>test</code>, <code>test/at/start</code>,
|
||
<code>at/end/test</code>, <code>in/test/middle</code>.</p>
|
||
<p>Another use is in parameter substitution; for example
|
||
‘<code>${array/(#s)A*Z(#e)}</code>’ will remove only elements of an array
|
||
which match the complete pattern ‘<code>A*Z</code>’. There are other ways of
|
||
performing many operations of this type, however the combination of
|
||
the substitution operations ‘<code>/</code>’ and ‘<code>//</code>’ with the ‘<code>(#s)</code>’ and
|
||
‘<code>(#e)</code>’ flags provides a single simple and memorable method.</p>
|
||
<p>Note that assertions of the form ‘<code>(^(#s))</code>’ 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 ‘<code>(""~(#s))</code>’ to match a zero-length
|
||
portion of the string not at the start.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>q</code><br />
|
||
A ‘<code>q</code>’ 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 ‘<code>(#b)(*).c(#q.)</code>’ can be used both for globbing and for
|
||
matching against a string. In the former case, the ‘<code>(#q.)</code>’ will be
|
||
treated as a glob qualifier and the ‘<code>(#b)</code>’ will not be useful,
|
||
while in the latter case the ‘<code>(#b)</code>’ is useful for backreferences
|
||
and the ‘<code>(#q.)</code>’ will be ignored. Note that colon modifiers in the
|
||
glob qualifiers are also not applied in ordinary pattern matching.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>u</code><br />
|
||
Respect the current locale in determining the presence of multibyte
|
||
characters in a pattern, provided the shell was compiled with
|
||
<code>MULTIBYTE_SUPPORT</code>. This overrides the <code>MULTIBYTE</code> option; the
|
||
default behaviour is taken from the option. Compare <code>U</code>. (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>
|
||
</li>
|
||
<li>
|
||
<p><code>U</code><br />
|
||
All characters are considered to be a single byte long. The opposite
|
||
of <code>u</code>. This overrides the <code>MULTIBYTE</code> option.</p>
|
||
</li>
|
||
</ul>
|
||
<p>For example, the test string <code>fooxx</code> can be matched by the pattern
|
||
<code>(#i``)FOOXX</code>, but not by <code>(#l``)FOOXX</code>, <code>(#i``)FOO``(#I``)XX</code> or
|
||
<code>((#i``)FOOX``)X</code>. The string <code>(#ia2``)readme</code> specifies
|
||
case-insensitive matching of <code>readme</code> with up to two errors.</p>
|
||
<p>When using the ksh syntax for grouping both <code>KSH_GLOB</code> and
|
||
<code>EXTENDED_GLOB</code> must be set and the left parenthesis should be preceded
|
||
by <code>@</code>. Note also that the flags do not affect letters inside <code>[</code>...<code>]</code>
|
||
groups, in other words <code>(#i``)[a-z]</code> 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 <code>(#i``)/foo/bar/...</code> 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>When matching approximately, the shell keeps a count of the errors
|
||
found, which cannot exceed the number specified in the <code>(#a``num``)</code>
|
||
flags. Four types of error are recognised:</p>
|
||
<ul>
|
||
<li>
|
||
<p>1.<br />
|
||
Different characters, as in <code>fooxbar</code> and <code>fooybar</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>2.<br />
|
||
Transposition of characters, as in <code>banana</code> and <code>abnana</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>3.<br />
|
||
A character missing in the target string, as with the pattern <code>road</code>
|
||
and target string <code>rod</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>4.<br />
|
||
An extra character appearing in the target string, as with <code>stove</code>
|
||
and <code>strove</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Thus, the pattern <code>(#a3``)abcd</code> matches <code>dcba</code>, with the errors
|
||
occurring by using the first rule twice and the second once, grouping
|
||
the string as <code>[d][cb][a]</code> and <code>[a][bc][d]</code>.</p>
|
||
<p>Non-literal parts of the pattern must match exactly, including
|
||
characters in character ranges: hence <code>(#a1``)???</code> 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 <code>?</code> must match. Other characters
|
||
which must match exactly are initial dots in filenames (unless the
|
||
<code>GLOB_DOTS</code> option is set), and all slashes in filenames, so that <code>a/bc</code>
|
||
is two errors from <code>ab/c</code> (the slash cannot be transposed with another
|
||
character). Similarly, errors are counted separately for non-contiguous
|
||
strings in the pattern, so that <code>(ab|cd``)ef</code> is two errors from <code>aebf</code>.</p>
|
||
<p>When using exclusion via the <code>~</code> operator, approximate matching is
|
||
treated entirely separately for the excluded part and must be activated
|
||
separately. Thus, <code>(#a1``)README~READ_ME</code> matches <code>READ.ME</code> but not
|
||
<code>READ_ME</code>, as the trailing <code>READ_ME</code> is matched without approximation.
|
||
However, <code>(#a1``)README~(#a1``)READ_ME</code> does not match any pattern of
|
||
the form <code>READ``?``ME</code> 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, <code>(#a1``)cat``((#a0``)dog``)fox</code>
|
||
allows one error in total, which may not occur in the <code>dog</code> section, and
|
||
the pattern <code>(#a1``)cat``(#a0``)dog``(#a1``)fox</code> 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,
|
||
<code>(#a1)abc(#a0)xyz</code> will not match <code>abcdxyz</code>, because the error occurs at
|
||
the ‘<code>x</code>’, where approximation is turned off.</p>
|
||
<p>Entire path segments may be matched approximately, so that
|
||
‘<code>(#a1)/foo/d/is/available/at/the/bar</code>’ allows one error in any path
|
||
segment. This is much less efficient than without the <code>(#a1)</code>, however,
|
||
since every directory in the path must be scanned for a possible
|
||
approximate match. It is best to place the <code>(#a1)</code> 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>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, ‘<code>**/</code>’ is equivalent to ‘<code>(*/)#</code>’; note that this
|
||
therefore matches files in the current directory as well as
|
||
subdirectories. Thus:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ls -ld -- (*/)#bar
|
||
</code></pre>
|
||
</div>
|
||
<p>or</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ls -ld -- **/bar
|
||
</code></pre>
|
||
</div>
|
||
<p>does a recursive directory search for files named ‘<code>bar</code>’ (potentially
|
||
including the file ‘<code>bar</code>’ in the current directory). This form does not
|
||
follow symbolic links; the alternative form ‘<code>***/</code>’ 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 ‘<code>*</code>’
|
||
operators revert to their usual effect.</p>
|
||
<p>Even shorter forms are available when the option <code>GLOB_STAR_SHORT</code> is
|
||
set. In that case if no <code>/</code> immediately follows a <code>**</code> or <code>***</code> they are
|
||
treated as if both a <code>/</code> plus a further <code>*</code> are present. Hence:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">setopt GLOBSTARSHORT
|
||
ls -ld -- **.c
|
||
</code></pre>
|
||
</div>
|
||
<p>is equivalent to</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>BARE_GLOB_QUAL</code> is set, then a trailing set of
|
||
parentheses containing no ‘<code>|</code>’ or ‘<code>(</code>’ characters (or ‘<code>~</code>’ 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 ‘<code>(^x)</code>’, can be
|
||
forced to be treated as part of the glob pattern by doubling the
|
||
parentheses, in this case producing ‘<code>((^x))</code>’.</p>
|
||
<p>If the option <code>EXTENDED_GLOB</code> is set, a different syntax for glob
|
||
qualifiers is available, namely ‘<code>(#q``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 ‘<code>|</code>’, ‘<code>(</code>’
|
||
or ‘<code>~</code>’ 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 ‘<code>[[</code>’ form the presence of a parenthesised expression <code>(#q``...``)</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 <code>(#q)</code>. 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>
|
||
<ul>
|
||
<li>
|
||
<p><code>/</code><br />
|
||
directories</p>
|
||
</li>
|
||
<li>
|
||
<p><code>F</code><br />
|
||
‘full’ (i.e. non-empty) directories. Note that the opposite sense
|
||
<code>(^F``)</code> expands to empty directories and all non-directories. Use
|
||
<code>(/^F``)</code> for empty directories.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>.</code><br />
|
||
plain files</p>
|
||
</li>
|
||
<li>
|
||
<p><code>@</code><br />
|
||
symbolic links</p>
|
||
</li>
|
||
<li>
|
||
<p><code>=</code><br />
|
||
sockets</p>
|
||
</li>
|
||
<li>
|
||
<p><code>p</code><br />
|
||
named pipes (FIFOs)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>*</code><br />
|
||
<code>%</code><br />
|
||
device files (character or block special)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%b</code><br />
|
||
block special files</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%c</code><br />
|
||
character special files</p>
|
||
</li>
|
||
<li>
|
||
<p><code>r</code><br />
|
||
owner-readable files (0400)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>w</code><br />
|
||
<code>x</code><br />
|
||
<code>A</code><br />
|
||
group-readable files (0040)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>I</code><br />
|
||
<code>E</code><br />
|
||
<code>R</code><br />
|
||
world-readable files (0004)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>W</code><br />
|
||
<code>X</code><br />
|
||
<code>s</code><br />
|
||
setuid files (04000)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>S</code><br />
|
||
setgid files (02000)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>t</code><br />
|
||
files with the sticky bit (01000)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>f``spec</code><br />
|
||
files with access rights matching <code>spec</code>. This <code>spec</code> may be a octal
|
||
number optionally preceded by a ‘<code>=</code>’, a ‘<code>+</code>’, or a ‘<code>-</code>’. If none
|
||
of these characters is given, the behavior is the same as for ‘<code>=</code>’.
|
||
The octal number describes the mode bits to be expected, if combined
|
||
with a ‘<code>=</code>’, the value given must match the file-modes exactly,
|
||
with a ‘<code>+</code>’, at least the bits in the given number must be set in
|
||
the file-modes, and with a ‘<code>-</code>’, the bits in the number must not be
|
||
set. Giving a ‘<code>?</code>’ 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 ‘<code>=</code>’.</p>
|
||
<p>If the qualifier ‘<code>f</code>’ is followed by any other character anything
|
||
up to the next matching character (‘<code>[</code>’, ‘<code>{</code>’, and ‘<code><</code>’ match
|
||
‘<code>]</code>’, ‘<code>}</code>’, and ‘<code>></code>’ 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 ‘<code>u</code>’, ‘<code>g</code>’, ‘<code>o</code>’, and ‘<code>a</code>’,
|
||
followed by a ‘<code>=</code>’, a ‘<code>+</code>’, or a ‘<code>-</code>’, followed by a list of any
|
||
of the characters ‘<code>r</code>’, ‘<code>w</code>’, ‘<code>x</code>’, ‘<code>s</code>’, and ‘<code>t</code>’, or an octal
|
||
digit. The first list of characters specify which access rights are
|
||
to be checked. If a ‘<code>u</code>’ is given, those for the owner of the file
|
||
are used, if a ‘<code>g</code>’ is given, those of the group are checked, a
|
||
‘<code>o</code>’ means to test those of other users, and the ‘<code>a</code>’ says to
|
||
test all three groups. The ‘<code>=</code>’, ‘<code>+</code>’, and ‘<code>-</code>’ 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: ‘<code>r</code>’ for read access, ‘<code>w</code>’
|
||
for write access, ‘<code>x</code>’ for the right to execute the file (or to
|
||
search a directory), ‘<code>s</code>’ for the setuid and setgid bits, and ‘<code>t</code>’
|
||
for the sticky bit.</p>
|
||
<p>Thus, ‘<code>*(f70?)</code>’ 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 ‘<code>*(f-100)</code>’ gives all files for which the owner does not
|
||
have execute permission, and ‘<code>*(f:gu+w,o-rx:)</code>’ 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>
|
||
</li>
|
||
<li>
|
||
<p><code>e``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 ‘<code>e</code>’ will be used
|
||
as a separator and anything up to the next matching separator will
|
||
be taken as the <code>string</code>; ‘<code>[</code>’, ‘<code>{</code>’, and ‘<code><</code>’ match ‘<code>]</code>’,
|
||
‘<code>}</code>’, and ‘<code>></code>’, 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 <code>globqual</code> is
|
||
appended to the array <code>zsh_eval_context</code> 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 <code>REPLY</code>; the parameter may be altered
|
||
to a string to be inserted into the list instead of the original
|
||
filename. In addition, the parameter <code>reply</code> may be set to an array
|
||
or a string, which overrides the value of <code>REPLY</code>. 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 ‘<code>lonely</code>’.
|
||
Then the expression ‘<code>*(e:’reply=(${REPLY}{1,2})’:)</code>’ will cause the
|
||
words ‘<code>lonely1</code>’ and ‘<code>lonely2</code>’ 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 <code>+</code> 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-example">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 <code>reffile</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>d``dev</code><br />
|
||
files on the device <code>dev</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>l</code>[<code>-</code>|<code>+</code>]<code>ct</code><br />
|
||
files having a link count less than <code>ct</code> (<code>-</code>), greater than <code>ct</code>
|
||
(<code>+</code>), or equal to <code>ct</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>U</code><br />
|
||
files owned by the effective user ID</p>
|
||
</li>
|
||
<li>
|
||
<p><code>G</code><br />
|
||
files owned by the effective group ID</p>
|
||
</li>
|
||
<li>
|
||
<p><code>u``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 ‘<code>u</code>’ 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
|
||
‘<code>[</code>’, ‘<code>{</code>’, and ‘<code><</code>’ match the final separators ‘<code>]</code>’, ‘<code>}</code>’,
|
||
and ‘<code>></code>’, respectively; any other character matches itself. The
|
||
selected files are those owned by this user. For example, ‘<code>u:foo:</code>’
|
||
or ‘<code>u[foo]</code>’ selects files owned by user ‘<code>foo</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>g``id</code><br />
|
||
like <code>u``id</code> but with group IDs or names</p>
|
||
</li>
|
||
<li>
|
||
<p><code>a</code>[<code>Mwhms</code>][<code>-</code>|<code>+</code>]<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 ‘<code>M</code>’, ‘<code>w</code>’, ‘<code>h</code>’, ‘<code>m</code>’ or
|
||
‘<code>s</code>’ (e.g. ‘<code>ah5</code>’) cause the check to be performed with months
|
||
(of 30 days), weeks, hours, minutes or seconds instead of days,
|
||
respectively. An explicit ‘<code>d</code>’ 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, ‘<code>echo *(ah-5)</code>’ would echo files accessed
|
||
within the last five hours, while ‘<code>echo *(ah+5)</code>’ would echo files
|
||
accessed at least six hours ago, as times strictly between five and
|
||
six hours are treated as five hours.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>m</code>[<code>Mwhms</code>][<code>-</code>|<code>+</code>]<code>n</code><br />
|
||
like the file access qualifier, except that it uses the file
|
||
modification time.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>c</code>[<code>Mwhms</code>][<code>-</code>|<code>+</code>]<code>n</code><br />
|
||
like the file access qualifier, except that it uses the file inode
|
||
change time.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>L</code>[<code>+</code>|<code>-</code>]<code>n</code><br />
|
||
files less than <code>n</code> bytes (<code>-</code>), more than <code>n</code> bytes (<code>+</code>), or
|
||
exactly <code>n</code> bytes in length.</p>
|
||
<p>If this flag is directly followed by a <em>size specifier</em> ‘<code>k</code>’
|
||
(‘<code>K</code>’), ‘<code>m</code>’ (‘<code>M</code>’), or ‘<code>p</code>’ (‘<code>P</code>’) (e.g. ‘<code>Lk-50</code>’) the
|
||
check is performed with kilobytes, megabytes, or blocks (of 512
|
||
bytes) instead. (On some systems additional specifiers are available
|
||
for gigabytes, ‘<code>g</code>’ or ‘<code>G</code>’, and terabytes, ‘<code>t</code>’ or ‘<code>T</code>’.) 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 ‘<code>*(Lm1)</code>’ 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
|
||
‘<code>*(Lm-1)</code>’ only matches files of zero size.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>^</code><br />
|
||
negates all qualifiers following it</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-</code><br />
|
||
toggles between making the qualifiers work on symbolic links (the
|
||
default) and the files they point to</p>
|
||
</li>
|
||
<li>
|
||
<p><code>M</code><br />
|
||
sets the <code>MARK_DIRS</code> option for the current pattern
|
||
<span id="index-MARK_005fDIRS_002c-setting-in-pattern"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>T</code><br />
|
||
appends a trailing qualifier mark to the filenames, analogous to the
|
||
<code>LIST_TYPES</code> option, for the current pattern (overrides <code>M</code>)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>N</code><br />
|
||
sets the <code>NULL_GLOB</code> option for the current pattern
|
||
<span id="index-NULL_005fGLOB_002c-setting-in-pattern"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>D</code><br />
|
||
sets the <code>GLOB_DOTS</code> option for the current pattern
|
||
<span id="index-GLOB_005fDOTS_002c-setting-in-pattern"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>n</code><br />
|
||
sets the <code>NUMERIC_GLOB_SORT</code> option for the current pattern
|
||
<span id="index-NUMERIC_005fGLOB_005fSORT_002c-setting-in-pattern"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>Y``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 <code>oN</code> when no <code>o``c</code> qualifier is used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>o``c</code><br />
|
||
specifies how the names of the files should be sorted. If <code>c</code> is <code>n</code>
|
||
they are sorted by name; if it is <code>L</code> they are sorted depending on
|
||
the size (length) of the files; if <code>l</code> they are sorted by the number
|
||
of links; if <code>a</code>, <code>m</code>, or <code>c</code> they are sorted by the time of the
|
||
last access, modification, or inode change respectively; if <code>d</code>,
|
||
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 ‘<code>odon</code>’ to sort on names for files within the
|
||
same directory; if <code>N</code>, no sorting is performed. Note that <code>a</code>, <code>m</code>,
|
||
and <code>c</code> compare the age against the current time, hence the first
|
||
name in the list is the youngest file. Also note that the modifiers
|
||
<code>^</code> and <code>-</code> are used, so ‘<code>*(^-oL)</code>’ gives a list of all files
|
||
sorted by file size in descending order, following any symbolic
|
||
links. Unless <code>oN</code> is used, multiple order specifiers may occur to
|
||
resolve ties.</p>
|
||
<p>The default sorting is <code>n</code> (by name) unless the <code>Y</code> glob qualifier
|
||
is used, in which case it is <code>N</code> (unsorted).</p>
|
||
<p><code>oe</code> and <code>o+</code> are special cases; they are each followed by shell
|
||
code, delimited as for the <code>e</code> glob qualifier and the <code>+</code> glob
|
||
qualifier respectively (see above). The code is executed for each
|
||
matched file with the parameter <code>REPLY</code> set to the name of the file
|
||
on entry and <code>globsort</code> appended to <code>zsh_eval_context</code>. The code
|
||
should modify the parameter <code>REPLY</code> 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, <code>oe</code> and <code>o+</code>
|
||
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>
|
||
</li>
|
||
<li>
|
||
<p><code>O``c</code><br />
|
||
like ‘<code>o</code>’, but sorts in descending order; i.e. ‘<code>*(^oc)</code>’ is the
|
||
same as ‘<code>*(Oc)</code>’ and ‘<code>*(^Oc)</code>’ is the same as ‘<code>*(oc)</code>’; ‘<code>Od</code>’
|
||
puts files in the current directory before those in subdirectories
|
||
at each level of the search.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>[``beg</code>[<code>,``end</code>]<code>]</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.: ‘<code>*(-OL[1,3])</code>’ gives a list of the
|
||
names of the three largest files.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>P``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 <code>e</code>
|
||
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 ‘<code>*(P:-f:)</code>’
|
||
produces the command line arguments ‘<code>-f</code> <code>file1</code> <code>-f</code> <code>file2</code> ...’</p>
|
||
<p>If the modifier <code>^</code> 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 ‘<code>*(P:foo:^P:bar:^P:baz:)</code>’ which produces the command line
|
||
arguments ‘<code>foo</code> <code>baz</code> <code>file1</code> <code>bar</code> ...’</p>
|
||
</li>
|
||
</ul>
|
||
<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 ‘<code>M</code>’, ‘<code>T</code>’,
|
||
‘<code>N</code>’, ‘<code>D</code>’, ‘<code>n</code>’, ‘<code>o</code>’, ‘<code>O</code>’ and the subscripts given in brackets
|
||
(‘<code>[``...``]</code>’).</p>
|
||
<p>If a ‘<code>:</code>’ 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 ‘<code>:</code>’. 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 <code>NULL_GLOB</code>.
|
||
Thus:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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-example">ls -ld -- *(-@)
|
||
</code></pre>
|
||
</div>
|
||
<p>lists all broken symbolic links, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ls -ld -- *(%W)
|
||
</code></pre>
|
||
</div>
|
||
<div class="example">
|
||
<pre><code class="language-example">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-example">print -rC1 /tmp/foo*(u0^@:t)
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs the basename of all root-owned files beginning with the string
|
||
‘<code>foo</code>’ in <code>/tmp</code>, ignoring symlinks, and</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 <code>GLOB_DOTS</code> is explicitly
|
||
switched off) except for <code>lex.c</code>, <code>lex.h</code>, <code>parse.c</code> and <code>parse.h</code>.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">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 ‘<code>.</code>’ is applied first, then the colon
|
||
modifiers in order from left to right. So if <code>EXTENDED_GLOB</code> is set and
|
||
the base pattern matches the regular file <code>builtin.pro</code>, the shell will
|
||
print ‘<code>shmiltin.shmo</code>’.</p>
|
||
<hr />
|
||
<p>This document was generated on <em>February 15, 2020</em> using
|
||
<a href="http://www.nongnu.org/texi2html/"><em>texi2html 5.0</em></a>.<br />
|
||
Zsh version 5.8, released on February 14, 2020.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
|
||
<a rel="prev" href="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">
|
||
var socket = new WebSocket("ws://localhost:3000/__livereload");
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|