mirror of
git://git.code.sf.net/p/zsh/code
synced 2024-05-09 17:16:19 +02:00
3208 lines
136 KiB
Plaintext
3208 lines
136 KiB
Plaintext
texinode(Expansion)(Parameters)(Prompt Expansion)(Top)
|
|
chapter(Expansion)
|
|
ifnztexi(sect(Description))
|
|
cindex(expansion)
|
|
The following types of expansions are performed in the indicated order in
|
|
five steps:
|
|
|
|
startitem()
|
|
item(em(History Expansion))(
|
|
This is performed only in interactive shells.
|
|
)
|
|
item(em(Alias Expansion))(
|
|
Aliases are expanded immediately before the command line is parsed as
|
|
explained
|
|
ifzman(under Aliasing in zmanref(zshmisc))\
|
|
ifnzman(in noderef(Aliasing))\
|
|
.
|
|
)
|
|
xitem(em(Process Substitution))
|
|
xitem(em(Parameter Expansion))
|
|
xitem(em(Command Substitution))
|
|
xitem(em(Arithmetic Expansion))
|
|
item(em(Brace Expansion))(
|
|
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 `tt(\)',`tt(')' and `tt(")' are
|
|
removed.
|
|
)
|
|
item(em(Filename Expansion))(
|
|
If the tt(SH_FILE_EXPANSION) option is set, the order of expansion is
|
|
modified for compatibility with bf(sh) and bf(ksh). In that case
|
|
em(filename expansion) is performed immediately after em(alias expansion),
|
|
preceding the set of five expansions mentioned above.
|
|
)
|
|
cindex(globbing)
|
|
item(em(Filename Generation))(
|
|
This expansion, commonly referred to as bf(globbing), is always done last.
|
|
)
|
|
enditem()
|
|
|
|
The following sections explain the types of expansion in detail.
|
|
|
|
startmenu()
|
|
menu(History Expansion)
|
|
menu(Process Substitution)
|
|
menu(Parameter Expansion)
|
|
menu(Command Substitution)
|
|
menu(Arithmetic Expansion)
|
|
menu(Brace Expansion)
|
|
menu(Filename Expansion)
|
|
menu(Filename Generation)
|
|
endmenu()
|
|
texinode(History Expansion)(Process Substitution)()(Expansion)
|
|
sect(History Expansion)
|
|
cindex(history)
|
|
cindex(history expansion)
|
|
cindex(expansion, history)
|
|
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.
|
|
|
|
vindex(HISTSIZE, use of)
|
|
Immediately before execution, each command is saved in the history list,
|
|
the size of which is controlled by the tt(HISTSIZE) parameter. The one
|
|
most recent command is always retained in any case. Each saved command in
|
|
the history list is called a history em(event) 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
|
|
ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
|
|
ifnzman(noderef(Prompt Expansion))\
|
|
) is the number that is to be assigned to the em(next) command.
|
|
|
|
startmenu()
|
|
menu(Overview)
|
|
menu(Event Designators)
|
|
menu(Word Designators)
|
|
menu(Modifiers)
|
|
endmenu()
|
|
texinode(Overview)(Event Designators)()(History Expansion)
|
|
subsect(Overview)
|
|
vindex(histchars, use of)
|
|
A history expansion begins with the first character of the tt(histchars)
|
|
parameter, which is `tt(!)' by default, and may occur anywhere on the
|
|
command line, including inside double quotes (but not inside single quotes
|
|
tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).
|
|
|
|
The first character is followed by an optional event designator
|
|
(ifzman(see )noderef(Event Designators)) and then an optional word
|
|
designator (noderef(Word Designators)); if neither of these designators is
|
|
present, no history expansion occurs.
|
|
|
|
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.
|
|
|
|
History expansions do not nest.
|
|
|
|
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.
|
|
pindex(CSH_JUNKIE_HISTORY, use of)
|
|
However, if the option tt(CSH_JUNKIE_HISTORY) is set, then every history
|
|
reference with no event specification em(always) refers to the previous
|
|
command.
|
|
|
|
For example, `tt(!)' is the event designator for the previous command, so
|
|
`tt(!!:1)' always refers to the first word of the previous command, and
|
|
`tt(!!$)' always refers to the last word of the previous command. With
|
|
tt(CSH_JUNKIE_HISTORY) set, then `tt(!:1)' and `tt(!$)' function in the
|
|
same manner as `tt(!!:1)' and `tt(!!$)', respectively. Conversely, if
|
|
tt(CSH_JUNKIE_HISTORY) is unset, then `tt(!:1)' and `tt(!$)' 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.
|
|
|
|
The character sequence `tt(^)var(foo)tt(^)var(bar)' (where `tt(^)' is
|
|
actually the second character of the tt(histchars) parameter)
|
|
repeats the last command, replacing the string var(foo) with var(bar).
|
|
More precisely, the sequence `tt(^)var(foo)tt(^)var(bar)tt(^)' is
|
|
synonymous with `tt(!!:s)tt(^)var(foo)tt(^)var(bar)tt(^)', hence other
|
|
modifiers (see noderef(Modifiers)) may follow the final `tt(^)'.
|
|
In particular, `tt(^)var(foo)tt(^)var(bar)tt(^:G)' performs a global
|
|
substitution.
|
|
|
|
If the shell encounters the character sequence `tt(!")'
|
|
in the input, the history mechanism is temporarily disabled until
|
|
the current list (see
|
|
ifzman(zmanref(zshmisc))\
|
|
ifnzman(noderef(Shell Grammar))\
|
|
) is fully parsed. The `tt(!")' is removed from the input, and any
|
|
subsequent `tt(!)' characters have no special significance.
|
|
|
|
findex(fc, use of)
|
|
A less convenient but more comprehensible form of command history support
|
|
is provided by the tt(fc) builtin.
|
|
texinode(Event Designators)(Word Designators)(Overview)(History Expansion)
|
|
subsect(Event Designators)
|
|
cindex(history event designators)
|
|
cindex(event designators, history)
|
|
An event designator is a reference to a command-line entry in the history
|
|
list. In the list below, remember that the initial tt(`!') in each item
|
|
may be changed to another character by setting the tt(histchars)
|
|
parameter.
|
|
|
|
startitem()
|
|
item(tt(!))(
|
|
Start a history expansion, except when followed by a blank, newline,
|
|
`tt(=)' or `tt(LPAR())'. If followed immediately by a word designator
|
|
(ifzman(see )noderef(Word Designators)), this forms a history reference
|
|
with no event designator (ifzman(see )noderef(Overview)).
|
|
)
|
|
item(tt(!!))(
|
|
Refer to the previous command.
|
|
By itself, this expansion
|
|
repeats the previous command.
|
|
)
|
|
item(tt(!)var(n))(
|
|
Refer to command-line var(n).
|
|
)
|
|
item(tt(!-)var(n))(
|
|
Refer to the current command-line minus var(n).
|
|
)
|
|
item(tt(!)var(str))(
|
|
Refer to the most recent command starting with var(str).
|
|
)
|
|
item(tt(!?)var(str)[tt(?)])(
|
|
Refer to the most recent command containing var(str). The trailing
|
|
`tt(?)' 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 var(str).
|
|
)
|
|
item(tt(!#))(
|
|
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 `tt(!#)' reference.
|
|
)
|
|
item(tt(!{)...tt(}))(
|
|
Insulate a history reference from adjacent characters (if necessary).
|
|
)
|
|
enditem()
|
|
texinode(Word Designators)(Modifiers)(Event Designators)(History Expansion)
|
|
subsect(Word Designators)
|
|
cindex(history word designators)
|
|
cindex(word designators, history)
|
|
A word designator indicates which word or words of a given command line are
|
|
to be included in a history reference. A `tt(:)' usually
|
|
separates the event specification from the word designator.
|
|
It may be omitted only if the word designator begins with a
|
|
`tt(^)', `tt($)', `tt(*)', `tt(-)' or `tt(%)'.
|
|
Word designators include:
|
|
|
|
startsitem()
|
|
sitem(tt(0))(The first input word (command).)
|
|
sitem(var(n))(The var(n)th argument.)
|
|
sitem(tt(^))(The first argument. That is, tt(1).)
|
|
sitem(tt($))(The last argument.)
|
|
sitem(tt(%))(The word matched by (the most recent) tt(?)var(str) search.)
|
|
sitem(var(x)tt(-)var(y))(A range of words; var(x) defaults to tt(0).)
|
|
sitem(tt(*))(All the arguments, or a null value if there are none.)
|
|
sitem(var(x)tt(*))(Abbreviates `var(x)tt(-$)'.)
|
|
sitem(var(x)tt(-))(Like `var(x)tt(*)' but omitting word tt($).)
|
|
endsitem()
|
|
|
|
Note that a `tt(%)' word designator works only when used in one of
|
|
`tt(!%)', `tt(!:%)' or `tt(!?)var(str)tt(?:%)', and only when used after a
|
|
tt(!?) expansion (possibly in an earlier command). Anything else results
|
|
in an error, although the error may not be the most obvious one.
|
|
texinode(Modifiers)()(Word Designators)(History Expansion)
|
|
subsect(Modifiers)
|
|
cindex(modifiers)
|
|
cindex(colon modifiers)
|
|
cindex(history modifiers)
|
|
cindex(globbing modifiers)
|
|
cindex(parameter modifiers)
|
|
After the optional word designator, you can add
|
|
a sequence of one or more of the following modifiers,
|
|
each preceded by a `tt(:)'. These modifiers also work on the result
|
|
of em(filename generation) and em(parameter expansion), except where
|
|
noted.
|
|
|
|
startitem()
|
|
item(tt(a))(
|
|
Turn a file name into an absolute path: prepends the current directory,
|
|
if necessary; remove `tt(.)' path segments; and remove `tt(..)' path segments
|
|
and the segments that immediately precede them.
|
|
|
|
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
|
|
tt(CHASE_DOTS) or tt(CHASE_LINKS) is set. For example,
|
|
`tt(/before/here/../after)' is always transformed to
|
|
`tt(/before/after)', regardless of whether `tt(/before/here)' exists or what
|
|
kind of object (dir, file, symlink, etc.) it is.
|
|
)
|
|
item(tt(A))(
|
|
Turn a file name into an absolute path as the `tt(a)' modifier does, and
|
|
em(then) pass the result through the tt(realpath+LPAR()3+RPAR()) library
|
|
function to resolve symbolic links.
|
|
|
|
Note: on systems that do not have a tt(realpath+LPAR()3+RPAR()) library
|
|
function, symbolic links are not resolved, so on those systems `tt(a)' and
|
|
`tt(A)' are equivalent.
|
|
|
|
Note: tt(foo:A) and tt(realpath+LPAR()foo+RPAR()) are different on some inputs.
|
|
For tt(realpath+LPAR()foo+RPAR()) semantics, see the `tt(P)` modifier.
|
|
)
|
|
item(tt(c))(
|
|
Resolve a command name into an absolute path by searching the command
|
|
path given by the tt(PATH) variable. This does not work for commands
|
|
containing directory parts. Note also that this does not usually work as
|
|
a glob qualifier unless a file of the same name is found in the
|
|
current directory.
|
|
)
|
|
item(tt(e))(
|
|
Remove all but the part of the filename extension following the `tt(.)';
|
|
see the definition of the filename extension in the description of the
|
|
tt(r) modifier below. Note that according to that definition the result
|
|
will be empty if the string ends with a `tt(.)'.
|
|
)
|
|
item(tt(h) [ var(digits) ])(
|
|
Remove a trailing pathname component, shortening the path by one
|
|
directory level: this is the `head' of the pathname. This works like
|
|
`tt(dirname)'. If the tt(h) is followed immediately (with no spaces or
|
|
other separator) by any number of decimal digits, and the value of the
|
|
resulting number is non-zero, that number of leading components is
|
|
preserved instead of the final component being removed. In an
|
|
absolute path the leading `tt(/)' is the first component, so,
|
|
for example, if tt(var=/my/path/to/something), then tt(${var:h3})
|
|
substitutes tt(/my/path). Consecutive `/'s are treated the same as
|
|
a single `/'. In parameter substitution, digits may only be
|
|
used if the expression is in braces, so for example the short form
|
|
substitution tt($var:h2) is treated as tt(${var:h}2), not as
|
|
tt(${var:h2}). No restriction applies to the use of digits in history
|
|
substitution or globbing qualifiers. If more components are requested
|
|
than are present, the entire path is substituted (so this does not
|
|
trigger a `failed modifier' error in history expansion).
|
|
)
|
|
item(tt(l))(
|
|
Convert the words to all lowercase.
|
|
)
|
|
item(tt(p))(
|
|
Print the new command but do not execute it. Only works with history
|
|
expansion.
|
|
)
|
|
item(tt(P))(
|
|
Turn a file name into an absolute path, like tt(realpath+LPAR()3+RPAR()).
|
|
The resulting path will be absolute,
|
|
will refer to the same directory entry as the input filename,
|
|
and none of its components will be symbolic links or equal to
|
|
`tt(.)' or `tt(..)'.
|
|
|
|
Unlike tt(realpath+LPAR()3+RPAR()), non-existent trailing components are
|
|
permitted and preserved.
|
|
)
|
|
item(tt(q))(
|
|
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 tt(eval).
|
|
)
|
|
item(tt(Q))(
|
|
Remove one level of quotes from the substituted words.
|
|
)
|
|
item(tt(r))(
|
|
Remove a filename extension leaving the root name. Strings with no
|
|
filename extension are not altered. A filename
|
|
extension is a `tt(.)' followed by any number of characters (including
|
|
zero) that are neither `tt(.)' nor `tt(/)' and that continue to the end
|
|
of the string. For example, the extension of
|
|
`tt(foo.orig.c)' is `tt(.c)', and `tt(dir.c/foo)' has no extension.
|
|
)
|
|
xitem(tt(s/)var(l)tt(/)var(r)[tt(/)])
|
|
item(tt(S/)var(l)tt(/)var(r)[tt(/)])(
|
|
Substitute var(r) for var(l) as described below.
|
|
The substitution is done only for the
|
|
first string that matches var(l). For arrays and for filename
|
|
generation, this applies to each word of the expanded text. See
|
|
below for further notes on substitutions.
|
|
|
|
The forms `tt(gs/)var(l)tt(/)var(r)' and `tt(s/)var(l)tt(/)var(r)tt(/:G)'
|
|
perform global substitution, i.e. substitute every occurrence of var(r)
|
|
for var(l). Note that the tt(g) or tt(:G) must appear in exactly the
|
|
position shown.
|
|
|
|
The use of tt(S) instead of tt(s) is identical except that
|
|
the source is treated as a pattern, just as if the option
|
|
tt(HIST_SUBST_PATTERN) were set.
|
|
|
|
See further notes on this form of substitution below.
|
|
)
|
|
item(tt(&))(
|
|
Repeat the previous tt(s) or tt(S) substitution, whichever was most
|
|
recent. Like tt(s) and tt(S), may be preceded immediately by a tt(g).
|
|
In parameter expansion the tt(&) must appear inside braces, and in
|
|
filename generation it must be quoted with a backslash.
|
|
)
|
|
item(tt(t) [ var(digits) ])(
|
|
Remove all leading pathname components, leaving the final component (tail).
|
|
This works like `tt(basename)'. Any trailing slashes are first removed.
|
|
Decimal digits are handled as described above for (h), but in this
|
|
case that number of trailing components is preserved instead of
|
|
the default 1; 0 is treated the same as 1.
|
|
)
|
|
item(tt(u))(
|
|
Convert the words to all uppercase.
|
|
)
|
|
item(tt(x))(
|
|
Like tt(q), but break into words at whitespace. Does not work with
|
|
parameter expansion.
|
|
)
|
|
enditem()
|
|
|
|
The tt(s/)var(l)tt(/)var(r)tt(/) 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 `tt(/)'. A backslash quotes the delimiter character. The character
|
|
`tt(&)', in the right-hand-side var(r), is replaced by the text from the
|
|
left-hand-side var(l). The `tt(&)' can be quoted with a backslash. A
|
|
null var(l) uses the previous string either from the previous var(l) or
|
|
from the contextual scan string var(s) from `tt(!?)var(s)'. You can
|
|
omit the rightmost delimiter if a newline immediately follows var(r);
|
|
the rightmost `tt(?)' in a context scan can similarly be omitted. Note
|
|
the same record of the last var(l) and var(r) is maintained across all
|
|
forms of expansion.
|
|
|
|
Note that if a `tt(&)' is used within glob qualifiers an extra backslash
|
|
is needed as a tt(&) is a special character in this case.
|
|
|
|
Also note that the order of expansions affects the interpretation of
|
|
var(l) and var(r). When used in a history expansion, which occurs before
|
|
any other expansions, var(l) and var(r) are treated as literal strings
|
|
(except as explained for tt(HIST_SUBST_PATTERN) below). When used in
|
|
parameter expansion, the replacement of var(r) 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 var(l) 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 `tt(:s)' expression itself is divided into
|
|
var(l) and var(r) sides.
|
|
|
|
If the option tt(HIST_SUBST_PATTERN) is set or the original substitution
|
|
was started with a capital tt(S), var(l) is treated as
|
|
a pattern of the usual form described in
|
|
ifzman(the section FILENAME GENERATION below)\
|
|
ifnzman(noderef(Filename Generation)). 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
|
|
tt(LPAR()#q:s/)var(...)tt(/)var(...)tt(/RPAR()) 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 tt(NO_BAD_PATTERN) option so will cause an error.
|
|
|
|
When tt(HIST_SUBST_PATTERN) is set, var(l) may start with a tt(#)
|
|
to indicate that the pattern must match at the start of the string
|
|
to be substituted, and a tt(%) may appear at the start or after an tt(#)
|
|
to indicate that the pattern must match at the end of the string
|
|
to be substituted. The tt(%) or tt(#) may be quoted with two
|
|
backslashes.
|
|
|
|
For example, the following piece of filename generation code
|
|
with the tt(EXTENDED_GLOB) option:
|
|
|
|
example(print -r -- *.c+LPAR()#q:s/#%+LPAR()#b+RPAR()s+LPAR()*+RPAR().c/'S${match[1]}.C'/+RPAR())
|
|
|
|
takes the expansion of tt(*.c) and applies the glob qualifiers in the
|
|
tt(LPAR()#q)var(...)tt(RPAR()) expression, which consists of a substitution
|
|
modifier anchored to the start and end of each word (tt(#%)). This
|
|
turns on backreferences (tt(LPAR()#b+RPAR())), so that the parenthesised
|
|
subexpression is available in the replacement string as tt(${match[1]}).
|
|
The replacement string is quoted so that the parameter is not substituted
|
|
before the start of filename generation.
|
|
|
|
The following tt(f), tt(F), tt(w) and tt(W) modifiers work only with
|
|
parameter expansion and filename generation. They are listed here to
|
|
provide a single point of reference for all modifiers.
|
|
|
|
startitem()
|
|
item(tt(f))(
|
|
Repeats the immediately (without a colon) following modifier until the
|
|
resulting word doesn't change any more.
|
|
)
|
|
item(tt(F:)var(expr)tt(:))(
|
|
Like tt(f), but repeats only var(n) times if the expression
|
|
var(expr) evaluates to var(n). Any character can be used instead of
|
|
the `tt(:)'; if `tt(LPAR())', `tt([)', or `tt({)'
|
|
is used as the opening delimiter,
|
|
the closing delimiter should be 'tt(RPAR())', `tt(])', or `tt(})',
|
|
respectively.
|
|
)
|
|
item(tt(w))(
|
|
Makes the immediately following modifier work on each word in the
|
|
string.
|
|
)
|
|
item(tt(W:)var(sep)tt(:))(
|
|
Like tt(w) but words are considered to be the parts of the string
|
|
that are separated by var(sep). Any character can be used instead of
|
|
the `tt(:)'; opening parentheses are handled specially, see above.
|
|
)
|
|
enditem()
|
|
texinode(Process Substitution)(Parameter Expansion)(History Expansion)(Expansion)
|
|
sect(Process Substitution)
|
|
cindex(process substitution)
|
|
cindex(substitution, process)
|
|
Each part of a command argument that takes the form
|
|
`tt(<LPAR())var(list)tt(RPAR())',
|
|
`tt(>LPAR())var(list)tt(RPAR())' or
|
|
`tt(=LPAR())var(list)tt(RPAR())'
|
|
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.
|
|
|
|
Note that `tt(<<LPAR())var(list)tt(RPAR())' is not a special syntax; it
|
|
is equivalent to `tt(< <LPAR())var(list)tt(RPAR())', 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.
|
|
|
|
In the case of the tt(<) or tt(>) forms, the shell runs the commands in
|
|
var(list) as a subprocess of the job executing the shell command line.
|
|
If the system supports the tt(/dev/fd)
|
|
mechanism, the command argument is the name of the device file
|
|
corresponding to a file descriptor; otherwise, if the system supports named
|
|
pipes (FIFOs), the command argument will be a named pipe. If the form with
|
|
tt(>) is selected then writing on this special file will provide input for
|
|
var(list). If tt(<) is used, then the file passed as an argument will
|
|
be connected to the output of the var(list) process. For example,
|
|
|
|
example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() |
|
|
tee >LPAR())var(process1)tt(RPAR() >LPAR())var(process2)tt(RPAR() >/dev/null))
|
|
|
|
cuts fields 1 and 3 from the files var(file1) and var(file2) respectively,
|
|
pastes the results together, and sends it to the processes
|
|
var(process1) and var(process2).
|
|
|
|
If tt(=LPAR())var(...)tt(RPAR()) is used instead of
|
|
tt(<LPAR())var(...)tt(RPAR()),
|
|
then the file passed as an argument will be the name
|
|
of a temporary file containing the output of the var(list)
|
|
process. This may be used instead of the tt(<)
|
|
form for a program that expects to lseek (see manref(lseek)(2))
|
|
on the input file.
|
|
|
|
There is an optimisation for substitutions of the form
|
|
tt(=LPAR()<<<)var(arg)tt(RPAR()), where var(arg) is a single-word argument
|
|
to the here-string redirection tt(<<<). This form produces a file name
|
|
containing the value of var(arg) after any substitutions have been
|
|
performed. This is handled entirely within the current shell. This is
|
|
effectively the reverse of the special form tt($LPAR()<)var(arg)tt(RPAR())
|
|
which treats var(arg) as a file name and replaces it with the file's
|
|
contents.
|
|
|
|
The tt(=) form is useful as both the tt(/dev/fd) and the named pipe
|
|
implementation of tt(<LPAR())var(...)tt(RPAR()) 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 manref(lseek)(2)) on the file will not work.
|
|
|
|
Also note that the previous example can be more compactly and
|
|
efficiently written (provided the tt(MULTIOS) option is set) as:
|
|
|
|
example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\
|
|
)tt(> >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
|
|
|
|
The shell uses pipes instead of FIFOs to implement the latter
|
|
two process substitutions in the above example.
|
|
|
|
There is an additional problem with tt(>LPAR())var(process)tt(RPAR()); when
|
|
this is attached to an external command, the parent shell does not wait
|
|
for var(process) 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) in
|
|
ifzman(zmanref(zshmisc))\
|
|
ifnzman(noderef(Redirection)). Hence in a simplified
|
|
version of the example above:
|
|
|
|
example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) tt(> >LPAR())var(process)tt(RPAR()))
|
|
|
|
(note that no tt(MULTIOS) are involved), var(process) will be run
|
|
asynchronously as far as the parent shell is concerned. The workaround is:
|
|
|
|
example(tt({ paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR() }) tt(> >LPAR())var(process)tt(RPAR()))
|
|
|
|
The extra processes here are
|
|
spawned from the parent shell which will wait for their completion.
|
|
|
|
Another problem arises any time a job with a substitution that requires
|
|
a temporary file is disowned by the shell, including the case where
|
|
`tt(&!)' or `tt(&|)' 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,
|
|
|
|
example(LPAR()mycmd =(myoutput)RPAR() &!)
|
|
|
|
as the forked subshell will wait for the command to finish then remove
|
|
the temporary file.
|
|
|
|
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:
|
|
|
|
example(LPAR()RPAR() {
|
|
print File $1:
|
|
cat $1
|
|
} =+LPAR()print This be the verse+RPAR())
|
|
|
|
outputs something resembling the following
|
|
|
|
example(File /tmp/zsh6nU0kS:
|
|
This be the verse)
|
|
|
|
The temporary file created by the process substitution will be deleted
|
|
when the function exits.
|
|
|
|
texinode(Parameter Expansion)(Command Substitution)(Process Substitution)(Expansion)
|
|
sect(Parameter Expansion)
|
|
cindex(parameter expansion)
|
|
cindex(expansion, parameter)
|
|
The character `tt($)' is used to introduce parameter expansions.
|
|
See
|
|
ifzman(\
|
|
zmanref(zshparam)
|
|
)\
|
|
ifnzman(\
|
|
noderef(Parameters)
|
|
)\
|
|
for a description of parameters, including arrays, associative arrays,
|
|
and subscript notation to access individual array elements.
|
|
|
|
Note in particular the fact that words of unquoted parameters are not
|
|
automatically split on whitespace unless the option tt(SH_WORD_SPLIT) is
|
|
set; see references to this option below for more details. This is an
|
|
important difference from other shells. However, as in other shells,
|
|
null words are elided from unquoted parameters' expansions.
|
|
|
|
With default options, after the assignments:
|
|
|
|
example(array=("first word" "" "third word")
|
|
scalar="only word")
|
|
|
|
then tt($array) substitutes two words, `tt(first word)' and `tt(third
|
|
word)', and tt($scalar) substitutes a single word `tt(only word)'. Note
|
|
that second element of tt(array) was elided. Scalar parameters can
|
|
be elided too if their value is null (empty). To avoid elision, use quoting as
|
|
follows: tt("$scalar") for scalars and tt("${array[@]}") or tt("${(@)array}")
|
|
for arrays. (The last two forms are equivalent.)
|
|
|
|
Parameter expansions can involve em(flags), as in `tt(${(@kv)aliases})',
|
|
and other operators, such as `tt(${PREFIX:-"/usr/local"})'. Parameter
|
|
expansions can also be nested. These topics will be introduced below.
|
|
The full rules are complicated and are noted at the end.
|
|
|
|
cindex(namespace)
|
|
Parameter expansions may optionally include a em(namespace) prefix in
|
|
the format `tt(.)var(identifier)tt(.)' This currently has no special
|
|
meaning to the shell, but provides a convenient means of grouping
|
|
related parameters. Expansions using a namespace em(must) include
|
|
braces (tt({) and tt(})) as shown in the descriptions below, and
|
|
only one namespace prefix is allowed. Note that, for support of
|
|
possible future features, the first `tt(.)' is optional, but omitting
|
|
it is discouraged.
|
|
|
|
In the expansions discussed below that require a pattern, the form of
|
|
the pattern is the same as that used for filename generation;
|
|
see noderef(Filename Generation). 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
|
|
noderef(Modifiers) in noderef(History Expansion) can be
|
|
applied: for example, tt(${i:s/foo/bar/}) performs string
|
|
substitution on the expansion of parameter tt($i).
|
|
|
|
In the following descriptions, `var(word)' refers to a single word
|
|
substituted on the command line, not necessarily a space delimited word.
|
|
The reference to `var(name)' in each description presumes any optional
|
|
namespace prefix.
|
|
|
|
startitem()
|
|
item(tt(${)var(name)tt(}))(
|
|
The value, if any, of the parameter var(name) 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 var(name). In addition, more complicated forms of substitution
|
|
usually require the braces to be present; exceptions, which only apply if
|
|
the option tt(KSH_ARRAYS) is not set, are a single subscript or any colon
|
|
modifiers appearing after the name, or any of the characters `tt(^)',
|
|
`tt(=)', `tt(~)', `tt(#)' or `tt(+)' appearing before the name, all of
|
|
which work with or without braces.
|
|
|
|
If var(name) is an array parameter, and the tt(KSH_ARRAYS) option is not
|
|
set, then the value of each
|
|
element of var(name) is substituted, one element per word. Otherwise, the
|
|
expansion results in one word only; with tt(KSH_ARRAYS), this is the first
|
|
element of an array. No field splitting is done on the result unless the
|
|
tt(SH_WORD_SPLIT) option is set.
|
|
See also the flags tt(=) and tt(s:)var(string)tt(:).
|
|
)
|
|
item(tt(${PLUS())var(name)tt(}))(
|
|
If var(name) is the name of a set parameter `tt(1)' is substituted,
|
|
otherwise `tt(0)' is substituted.
|
|
)
|
|
xitem(tt(${)var(name)tt(-)var(word)tt(}))
|
|
item(tt(${)var(name)tt(:-)var(word)tt(}))(
|
|
If var(name) is set, or in the second form is non-null, then substitute
|
|
its value; otherwise substitute var(word). In the second form var(name)
|
|
may be omitted, in which case var(word) is always substituted.
|
|
)
|
|
xitem(tt(${)var(name)tt(PLUS())var(word)tt(}))
|
|
item(tt(${)var(name)tt(:PLUS())var(word)tt(}))(
|
|
If var(name) is set, or in the second form is non-null, then substitute
|
|
var(word); otherwise substitute nothing.
|
|
)
|
|
xitem(tt(${)var(name)tt(=)var(word)tt(}))
|
|
xitem(tt(${)var(name)tt(:=)var(word)tt(}))
|
|
item(tt(${)var(name)tt(::=)var(word)tt(}))(
|
|
In the first form, if var(name) is unset then set it to var(word); in the
|
|
second form, if var(name) is unset or null then set it to var(word); and
|
|
in the third form, unconditionally set var(name) to var(word). In all
|
|
forms, the value of the parameter is then substituted.
|
|
)
|
|
xitem(tt(${)var(name)tt(?)var(word)tt(}))
|
|
item(tt(${)var(name)tt(:?)var(word)tt(}))(
|
|
In the first form, if var(name) is set, or in the second form if var(name)
|
|
is both set and non-null, then substitute its value; otherwise, print
|
|
var(word) and exit from the shell. Interactive shells instead return to
|
|
the prompt. If var(word) is omitted, then a standard message is
|
|
printed. Note that var(word) is expanded even though its value
|
|
is not substituted onto the command line.
|
|
)
|
|
enditem()
|
|
|
|
In any of the above expressions that test a variable and substitute an
|
|
alternate var(word), note that you can use standard shell quoting in the
|
|
var(word) value to selectively override the splitting done by the
|
|
tt(SH_WORD_SPLIT) option and the tt(=) flag, but not splitting by the
|
|
tt(s:)var(string)tt(:) flag.
|
|
|
|
In the following expressions, when var(name) is an array and
|
|
the substitution is not quoted, or if the `tt((@))' flag or the
|
|
var(name)tt([@]) syntax is used, matching and replacement is
|
|
performed on each array element separately.
|
|
|
|
startitem()
|
|
xitem(tt(${)var(name)tt(#)var(pattern)tt(}))
|
|
item(tt(${)var(name)tt(##)var(pattern)tt(}))(
|
|
If the var(pattern) matches the beginning of the value of
|
|
var(name), then substitute the value of var(name) with
|
|
the matched portion deleted; otherwise, just
|
|
substitute the value of var(name). In the first
|
|
form, the smallest matching pattern is preferred;
|
|
in the second form, the largest matching pattern is
|
|
preferred.
|
|
)
|
|
xitem(tt(${)var(name)tt(%)var(pattern)tt(}))
|
|
item(tt(${)var(name)tt(%%)var(pattern)tt(}))(
|
|
If the var(pattern) matches the end of the value of
|
|
var(name), then substitute the value of var(name) with
|
|
the matched portion deleted; otherwise, just
|
|
substitute the value of var(name). In the first
|
|
form, the smallest matching pattern is preferred;
|
|
in the second form, the largest matching pattern is
|
|
preferred.
|
|
)
|
|
item(tt(${)var(name)tt(:#)var(pattern)tt(}))(
|
|
If the var(pattern) matches the value of var(name), then substitute
|
|
the empty string; otherwise, just substitute the value of var(name).
|
|
If var(name) is an array
|
|
the matching array elements are removed (use the `tt((M))' flag to
|
|
remove the non-matched elements).
|
|
)
|
|
item(tt(${)var(name)tt(:|)var(arrayname)tt(}))(
|
|
If var(arrayname) is the name (N.B., not contents) of an array
|
|
variable, then any elements contained in var(arrayname) are removed
|
|
from the substitution of var(name). If the substitution is scalar,
|
|
either because var(name) is a scalar variable or the expression is
|
|
quoted, the elements of var(arrayname) are instead tested against the
|
|
entire expression.
|
|
)
|
|
item(tt(${)var(name)tt(:*)var(arrayname)tt(}))(
|
|
Similar to the preceding substitution, but in the opposite sense,
|
|
so that entries present in both the original substitution and as
|
|
elements of var(arrayname) are retained and others removed.
|
|
)
|
|
xitem(tt(${)var(name)tt(:^)var(arrayname)tt(}))
|
|
item(tt(${)var(name)tt(:^^)var(arrayname)tt(}))(
|
|
Zips two arrays, such that the output array is twice as long as the
|
|
shortest (longest for `tt(:^^)') of tt(name) and tt(arrayname), with
|
|
the elements alternatingly being picked from them. For `tt(:^)', if one
|
|
of the input arrays is longer, the output will stop when the end of the
|
|
shorter array is reached. Thus,
|
|
|
|
example(a=(1 2 3 4); b=(a b); print ${a:^b})
|
|
|
|
will output `tt(1 a 2 b)'. For `tt(:^^)', then the input is repeated
|
|
until all of the longer array has been used up and the above will output
|
|
`tt(1 a 2 b 3 a 4 b)'.
|
|
|
|
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.
|
|
|
|
Currently the following code will output `tt(a b)' and `tt(1)' as two separate
|
|
elements, which can be unexpected. The second print provides a workaround which
|
|
should continue to work if this is changed.
|
|
|
|
example(a=(a b); b=(1 2); print -l "${a:^b}"; print -l "${${a:^b}}")
|
|
)
|
|
xitem(tt(${)var(name)tt(:)var(offset)tt(}))
|
|
item(tt(${)var(name)tt(:)var(offset)tt(:)var(length)tt(}))(
|
|
This syntax gives effects similar to parameter subscripting
|
|
in the form tt($)var(name)tt([)var(start)tt(,)var(end)tt(]), but is
|
|
compatible with other shells; note that both var(offset) and var(length)
|
|
are interpreted differently from the components of a subscript.
|
|
|
|
If var(offset) is non-negative, then if the variable var(name) is a
|
|
scalar substitute the contents starting var(offset) characters from the
|
|
first character of the string, and if var(name) is an array substitute
|
|
elements starting var(offset) elements from the first element. If
|
|
var(length) is given, substitute that many characters or elements,
|
|
otherwise the entire rest of the scalar or array.
|
|
|
|
A positive var(offset) is always treated as the offset of a character or
|
|
element in var(name) 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 tt(KSH_ARRAYS).
|
|
|
|
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.
|
|
|
|
When positive, var(length) counts from the var(offset) position
|
|
toward the end of the scalar or array. When negative, var(length)
|
|
counts back from the end. If this results in a position smaller
|
|
than var(offset), a diagnostic is printed and nothing is substituted.
|
|
|
|
The option tt(MULTIBYTE) is obeyed, i.e. the offset and length
|
|
count multibyte characters where appropriate.
|
|
|
|
var(offset) and var(length) undergo the same set of shell substitutions
|
|
as for scalar assignment; in addition, they are then subject to arithmetic
|
|
evaluation. Hence, for example
|
|
|
|
example(print ${foo:3}
|
|
print ${foo: 1 + 2}
|
|
print ${foo:$(( 1 + 2))}
|
|
print ${foo:$(echo 1 + 2)})
|
|
|
|
all have the same effect, extracting the string starting at the fourth
|
|
character of tt($foo) if the substitution would otherwise return a scalar,
|
|
or the array starting at the fourth element if tt($foo) would return an
|
|
array. Note that with the option tt(KSH_ARRAYS) tt($foo) always returns
|
|
a scalar (regardless of the use of the offset syntax) and a form
|
|
such as tt(${foo[*]:3}) is required to extract elements of an array named
|
|
tt(foo).
|
|
|
|
If var(offset) is negative, the tt(-) may not appear immediately
|
|
after the tt(:) as this indicates the
|
|
tt(${)var(name)tt(:-)var(word)tt(}) form of substitution. Instead, a space
|
|
may be inserted before the tt(-). Furthermore, neither var(offset) nor
|
|
var(length) may begin with an alphabetic character or tt(&) 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 tt($) as this
|
|
signifies the intention (parameter substitution can easily be rendered
|
|
unreadable); however, as arithmetic substitution is performed, the
|
|
expression tt(${var: offs}) does work, retrieving the offset from
|
|
tt($offs).
|
|
|
|
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. tt($@) or tt($*), then offset 0
|
|
instead refers to tt($0), offset 1 refers to tt($1), and so on. In
|
|
other words, the positional parameter array is effectively extended by
|
|
prepending tt($0). Hence tt(${*:0:1}) substitutes tt($0) and
|
|
tt(${*:1:1}) substitutes tt($1).
|
|
)
|
|
xitem(tt(${)var(name)tt(/)var(pattern)tt(/)var(repl)tt(}))
|
|
xitem(tt(${)var(name)tt(//)var(pattern)tt(/)var(repl)tt(}))
|
|
item(tt(${)var(name)tt(:/)var(pattern)tt(/)var(repl)tt(}))(
|
|
Replace the longest possible match of var(pattern) in the expansion of
|
|
parameter var(name) by string var(repl). The first form
|
|
replaces just the first occurrence, the second form all occurrences,
|
|
and the third form replaces only if var(pattern) matches the entire string.
|
|
Both var(pattern) and var(repl) are subject to double-quoted substitution,
|
|
so that expressions like tt(${name/$opat/$npat}) will work, but obey the
|
|
usual rule that pattern characters in tt($opat) are not treated specially
|
|
unless either the option tt(GLOB_SUBST) is set, or tt($opat) is instead
|
|
substituted as tt(${~opat}).
|
|
|
|
The var(pattern) may begin with a `tt(#)', in which case the
|
|
var(pattern) must match at the start of the string, or `tt(%)', in
|
|
which case it must match at the end of the string, or `tt(#%)' in which
|
|
case the var(pattern) must match the entire string. The var(repl) may
|
|
be an empty string, in which case the final `tt(/)' may also be omitted.
|
|
To quote the final `tt(/)' in other cases it should be preceded by a
|
|
single backslash; this is not necessary if the
|
|
`tt(/)' occurs inside a substituted parameter. Note also that the `tt(#)',
|
|
`tt(%)' and `tt(#%) are not active if they occur inside a substituted
|
|
parameter, even at the start.
|
|
|
|
If, after quoting rules apply, tt(${)var(name)tt(}) expands to an array,
|
|
the replacements act on each element individually. Note also the
|
|
effect of the tt(I) and tt(S) parameter expansion flags below; however,
|
|
the flags tt(M), tt(R), tt(B), tt(E) and tt(N) are not useful.
|
|
|
|
For example,
|
|
|
|
example(foo="twinkle twinkle little star" sub="t*e" rep="spy"
|
|
print ${foo//${~sub}/$rep}
|
|
print ${(S)foo//${~sub}/$rep})
|
|
|
|
Here, the `tt(~)' ensures that the text of tt($sub) is treated as a
|
|
pattern rather than a plain string. In the first case, the longest
|
|
match for tt(t*e) is substituted and the result is `tt(spy star)',
|
|
while in the second case, the shortest matches are taken and the
|
|
result is `tt(spy spy lispy star)'.
|
|
)
|
|
item(tt(${#)var(spec)tt(}))(
|
|
If var(spec) is one of the above substitutions, substitute
|
|
the length in characters of the result instead of
|
|
the result itself. If var(spec) 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 var(spec).
|
|
Note that `tt(^)', `tt(=)', and `tt(~)', below, must appear
|
|
to the left of `tt(#)' when these forms are combined.
|
|
|
|
If the option tt(POSIX_IDENTIFIERS) is not set, and var(spec) is a
|
|
simple name, then the braces are optional; this is true even
|
|
for special parameters so e.g. tt($#-) and tt($#*) take the length
|
|
of the string tt($-) and the array tt($*) respectively. If
|
|
tt(POSIX_IDENTIFIERS) is set, then braces are required for
|
|
the tt(#) to be treated in this fashion.
|
|
)
|
|
xitem(tt(${^)var(spec)tt(}))
|
|
item(tt(${^^)var(spec)tt(}))(
|
|
pindex(RC_EXPAND_PARAM, toggle)
|
|
cindex(array expansion style, rc)
|
|
cindex(rc, array expansion style)
|
|
Turn on the tt(RC_EXPAND_PARAM) option for the
|
|
evaluation of var(spec); if the `tt(^)' is doubled, turn it off.
|
|
When this option is set, array expansions of the form
|
|
var(foo)tt(${)var(xx)tt(})var(bar),
|
|
where the parameter var(xx)
|
|
is set to tt(LPAR())var(a b c)tt(RPAR()), are substituted with
|
|
`var(fooabar foobbar foocbar)' instead of the default
|
|
`var(fooa b cbar)'. Note that an empty array will therefore cause
|
|
all arguments to be removed.
|
|
|
|
Internally, each such expansion is converted into the
|
|
equivalent list for brace expansion. E.g., tt(${^var}) becomes
|
|
tt({$var[1],$var[2],)...tt(}), and is processed as described in
|
|
noderef(Brace Expansion) below: note, however, the expansion
|
|
happens immediately, with any explicit brace expansion
|
|
happening later. If word splitting is also in effect the
|
|
tt($var[)var(N)tt(]) may themselves be split into different list
|
|
elements.
|
|
)
|
|
xitem(tt(${=)var(spec)tt(}))
|
|
item(tt(${==)var(spec)tt(}))(
|
|
pindex(SH_WORD_SPLIT, toggle)
|
|
cindex(field splitting, sh style, parameter)
|
|
cindex(sh, field splitting style, parameter)
|
|
Perform word splitting using the rules for tt(SH_WORD_SPLIT) during the
|
|
evaluation of var(spec), but regardless of whether the parameter appears in
|
|
double quotes; if the `tt(=)' is doubled, turn it off.
|
|
vindex(IFS, use of)
|
|
This forces parameter expansions to be split into
|
|
separate words before substitution, using tt(IFS) as a delimiter.
|
|
This is done by default in most other shells.
|
|
|
|
Note that splitting is applied to var(word) in the assignment forms
|
|
of var(spec) em(before) the assignment to var(name) is performed.
|
|
This affects the result of array assignments with the tt(A) flag.
|
|
)
|
|
xitem(tt(${~)var(spec)tt(}))
|
|
item(tt(${~~)var(spec)tt(}))(
|
|
pindex(GLOB_SUBST, toggle)
|
|
Turn on the tt(GLOB_SUBST) option for the evaluation of
|
|
var(spec); if the `tt(~)' 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 `tt(=)' and `tt(!=)' operators in conditions.
|
|
|
|
In nested substitutions, note that the effect of the tt(~) 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 tt(foo) is set to tt(*), tt(${~foo//\*/*.c}) is substituted by
|
|
the pattern tt(*.c), which may be expanded by filename generation, but
|
|
tt(${${~foo}//\*/*.c}) substitutes to the string tt(*.c), which will not
|
|
be further expanded.
|
|
)
|
|
enditem()
|
|
|
|
If a tt(${)...tt(}) type parameter expression or a
|
|
tt($LPAR())...tt(RPAR()) type command substitution is used in place of
|
|
var(name) above, it is expanded first and the result is used as if
|
|
it were the value of var(name). Thus it is
|
|
possible to perform nested operations: tt(${${foo#head}%tail})
|
|
substitutes the value of tt($foo) with both `tt(head)' and `tt(tail)'
|
|
deleted. The form with tt($LPAR())...tt(RPAR()) is often useful in
|
|
combination with the flags described next; see the examples below.
|
|
Each var(name) or nested tt(${)...tt(}) in a parameter expansion may
|
|
also be followed by a subscript expression as described in
|
|
ifzman(em(Array Parameters) in zmanref(zshparam))\
|
|
ifnzman(noderef(Array Parameters)).
|
|
|
|
Note that double quotes may appear around nested expressions, in which
|
|
case only the part inside is treated as quoted; for example,
|
|
tt(${(f)"$(foo)"}) quotes the result of tt($(foo)), but the flag `tt((f))'
|
|
(see below) is applied using the rules for unquoted expansions. Note
|
|
further that quotes are themselves nested in this context; for example, in
|
|
tt("${(@f)"$(foo)"}"), there are two sets of quotes, one surrounding the
|
|
whole expression, the other (redundant) surrounding the tt($(foo)) as
|
|
before.
|
|
|
|
subsect(Parameter Expansion Flags)
|
|
cindex(parameter expansion flags)
|
|
cindex(flags, parameter expansion)
|
|
cindex(substitution, parameter, flags)
|
|
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, `(tt(q%q%q))'
|
|
means the same thing as the more readable `(tt(%%qqq))'. The
|
|
following flags are supported:
|
|
|
|
startitem()
|
|
item(tt(!))(
|
|
When the parameter being expanded is a named reference, the reference
|
|
itself is examined and thus is em(not) resolved to its referent. In
|
|
ksh emulation, the parens around this flag are optional.
|
|
)
|
|
item(tt(#))(
|
|
Evaluate the resulting words as numeric expressions and interpret
|
|
these as character codes. Output the corresponding characters. Note
|
|
that this form is entirely distinct from use of the tt(#) without
|
|
parentheses.
|
|
|
|
If the tt(MULTIBYTE) option is set and the number is greater than 127
|
|
(i.e. not an ASCII character) it is treated as a Unicode character.
|
|
)
|
|
item(tt(%))(
|
|
Expand all tt(%) escapes in the resulting words in the same way as in
|
|
prompts (see
|
|
ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
|
|
ifnzman(noderef(Prompt Expansion))). If this flag is given twice,
|
|
full prompt expansion is done on the resulting words, depending on the
|
|
setting of the tt(PROMPT_PERCENT), tt(PROMPT_SUBST) and tt(PROMPT_BANG)
|
|
options.
|
|
)
|
|
item(tt(@))(
|
|
In double quotes, array elements are put into separate words.
|
|
E.g., `tt("${(@)foo}")' is equivalent to `tt("${foo[@]}")' and
|
|
`tt("${(@)foo[1,2]}")' is the same as `tt("$foo[1]" "$foo[2]")'.
|
|
This is distinct from em(field splitting) by the tt(f), tt(s)
|
|
or tt(z) flags, which still applies within each array element.
|
|
)
|
|
item(tt(A))(
|
|
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 tt(${${LPAR()A)tt(RPAR())var(name)tt(}[1]})
|
|
yields the full value of var(name) when var(name) is scalar.
|
|
|
|
This assigns an array parameter with `tt(${)...tt(=)...tt(})',
|
|
`tt(${)...tt(:=)...tt(})' or `tt(${)...tt(::=)...tt(})'.
|
|
If this flag is repeated (as in `tt(AA)'), assigns an associative
|
|
array parameter. Assignment is made before sorting or padding;
|
|
if field splitting is active, the var(word) part is split before
|
|
assignment. The var(name) part may be a subscripted range for
|
|
ordinary arrays; when assigning an associative array, the var(word)
|
|
part em(must) be converted to an array, for example by using
|
|
`tt(${(AA)=)var(name)tt(=)...tt(})' to activate field splitting.
|
|
|
|
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.
|
|
)
|
|
item(tt(a))(
|
|
Sort in array index order; when combined with `tt(O)' sort in reverse
|
|
array index order. Note that `tt(a)' is therefore equivalent to the
|
|
default but `tt(Oa)' is useful for obtaining an array's elements in reverse
|
|
order.
|
|
)
|
|
item(tt(b))(
|
|
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 tt(GLOB_SUBST), including the tt(${~)var(...)tt(}) switch.
|
|
|
|
Quoting using one of the tt(q) family of flags does not work
|
|
for this purpose since quotes are not stripped from non-pattern
|
|
characters by tt(GLOB_SUBST). In other words,
|
|
|
|
example(pattern=${(q)str}
|
|
[[ $str = ${~pattern} ]])
|
|
|
|
works if tt($str) is `tt(a*b)' but not if it is `tt(a b)', whereas
|
|
|
|
example(pattern=${(b)str}
|
|
[[ $str = ${~pattern} ]])
|
|
|
|
is always true for any possible value of tt($str).
|
|
)
|
|
item(tt(c))(
|
|
With tt(${#)var(name)tt(}), 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.
|
|
)
|
|
item(tt(C))(
|
|
Capitalize the resulting words. `Words' in this case refers to sequences
|
|
of alphanumeric characters separated by non-alphanumerics, em(not) to words
|
|
that result from field splitting.
|
|
)
|
|
item(tt(D))(
|
|
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 `tt(~)' substitution: see
|
|
ifnzman(noderef(Filename Expansion))\
|
|
ifzman(the section FILENAME EXPANSION below).
|
|
)
|
|
item(tt(e))(
|
|
Perform single word shell expansions, namely em(parameter expansion),
|
|
em(command substitution) and em(arithmetic expansion), on the
|
|
result. Such expansions can be nested but too deep recursion may have
|
|
unpredictable effects.
|
|
)
|
|
item(tt(f))(
|
|
Split the result of the expansion at newlines. This is a shorthand
|
|
for `tt(ps:\n:)'.
|
|
)
|
|
item(tt(F))(
|
|
Join the words of arrays together using newline as a separator.
|
|
This is a shorthand for `tt(pj:\n:)'.
|
|
)
|
|
item(tt(g:)var(opts)tt(:))(
|
|
Process escape sequences like the echo builtin when no options are given
|
|
(tt(g::)). With the tt(o) option, octal escapes don't take a leading
|
|
zero. With the tt(c) option, sequences like `tt(^X)' are also processed.
|
|
With the tt(e) option, processes `tt(\M-t)' and similar sequences like the
|
|
print builtin. With both of the tt(o) and tt(e) options, behaves like the
|
|
print builtin except that in none of these modes is `tt(\c)' interpreted.
|
|
)
|
|
item(tt(i))(
|
|
Sort case-insensitively. May be combined with `tt(n)' or `tt(O)'.
|
|
)
|
|
item(tt(k))(
|
|
If var(name) refers to an associative array, substitute the em(keys)
|
|
(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
|
|
tt(KSH_ARRAYS) option a subscript `tt([*])' or `tt([@])' is needed
|
|
to operate on the whole array, as usual.
|
|
)
|
|
item(tt(L))(
|
|
Convert all letters in the result to lower case, like `tt(typeset -l)'.
|
|
)
|
|
item(tt(n))(
|
|
Sort decimal integers numerically; if the first differing
|
|
characters of two test strings are not digits, sorting
|
|
is lexical. `tt(+)' and `tt(-)' are not treated specially; they are treated as
|
|
any other non-digit. Integers with more initial zeroes
|
|
are sorted before those with fewer or none. Hence the array `tt(foo+24 foo1 foo02
|
|
foo2 foo3 foo20 foo23)' is sorted into the order shown.
|
|
May be combined with `tt(i)' or `tt(O)'.
|
|
)
|
|
item(tt(-))(
|
|
As tt(n), but a leading minus sign indicates a negative decimal
|
|
integer. A leading minus sign not followed by an integer does not trigger
|
|
numeric sorting.
|
|
Note that `tt(+)' signs are not handled specially (this may change in the
|
|
future).
|
|
)
|
|
item(tt(o))(
|
|
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 `tt(a)', `tt(i)', `tt(n)' or `tt(-)'.
|
|
)
|
|
item(tt(O))(
|
|
Sort the resulting words in descending order; `tt(O)' without `tt(a)',
|
|
`tt(i)', `tt(n)' or `tt(-)' sorts in reverse lexical order. May be
|
|
combined with `tt(a)', `tt(i)', `tt(n)' or `tt(-)' to reverse the
|
|
order of sorting.
|
|
)
|
|
item(tt(P))(
|
|
This forces the value of the parameter var(name) to be interpreted as a
|
|
further parameter name, whose value will be used where appropriate.
|
|
Note that flags set with one of the tt(typeset) family of commands
|
|
(in particular case transformations) are not applied to the value of
|
|
var(name) used in this fashion.
|
|
|
|
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 `tt(foo=bar)' and `tt(bar=baz)', the strings tt(${(P)foo}),
|
|
tt(${(P)${foo}}), and tt(${(P)$(echo bar)}) will be expanded to
|
|
`tt(baz)'.
|
|
|
|
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 `tt(name=assoc)' where the parameter
|
|
tt(assoc) is an associative array, then
|
|
`tt(${${(P)name}[elt]})' refers to the element of the associative
|
|
subscripted `tt(elt)'.
|
|
)
|
|
item(tt(q))(
|
|
Quote characters that are special to the shell in the resulting words with
|
|
backslashes; unprintable or invalid characters are quoted using the
|
|
tt($'\)var(NNN)tt(') form, with separate quotes for each octet.
|
|
|
|
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
|
|
quotes; in these forms no special handling of unprintable or invalid
|
|
characters is attempted. If the flag is given four times, the words are
|
|
quoted in single quotes preceded by a tt($). 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.
|
|
|
|
If a tt(q-) is given (only a single tt(q) may appear), a minimal
|
|
form of single quoting is used that only quotes the string if needed to
|
|
protect special characters. Typically this form gives the most readable
|
|
output.
|
|
|
|
If a tt(q+) is given, an extended form of minimal quoting is used that
|
|
causes unprintable characters to be rendered using tt($')var(...)tt(').
|
|
This quoting is similar to that used by the output of values by the
|
|
tt(typeset) family of commands.
|
|
)
|
|
item(tt(Q))(
|
|
Remove one level of quotes from the resulting words.
|
|
)
|
|
item(tt(t))(
|
|
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 (`tt(-)'). The first keyword in the string describes
|
|
the main type, it can be one of `tt(scalar)', `tt(array)', `tt(integer)',
|
|
`tt(float)' or `tt(association)'. The other keywords describe the type in
|
|
more detail, in most cases corresponding to options of the `tt(typeset)'
|
|
command:
|
|
|
|
startitem()
|
|
item(tt(local))(
|
|
for local parameters
|
|
)
|
|
item(tt(left))(
|
|
for left justified parameters (tt(-L))
|
|
)
|
|
item(tt(right_blanks))(
|
|
for right justified parameters with leading blanks (tt(-R))
|
|
)
|
|
item(tt(right_zeros))(
|
|
for right justified parameters with leading zeros (tt(-Z))
|
|
)
|
|
item(tt(lower))(
|
|
for parameters whose value is converted to all lower case when it is
|
|
expanded (tt(-l))
|
|
)
|
|
item(tt(upper))(
|
|
for parameters whose value is converted to all upper case when it is
|
|
expanded (tt(-u))
|
|
)
|
|
item(tt(readonly))(
|
|
for readonly parameters (tt(-r))
|
|
)
|
|
item(tt(tag))(
|
|
for tagged parameters (tt(-t))
|
|
)
|
|
item(tt(tied))(
|
|
for parameters tied to another parameter in the manner of tt(PATH)
|
|
(colon-separated list) and tt(path) (array), whether these are
|
|
special parameters or user-defined with `tt(typeset -T)'
|
|
)
|
|
item(tt(export))(
|
|
for exported parameters (tt(-x) or `tt(export)')
|
|
)
|
|
item(tt(unique))(
|
|
for arrays which keep only the first occurrence of duplicated values (tt(-U))
|
|
)
|
|
item(tt(hide))(
|
|
for parameters with the `hide' flag (tt(-h))
|
|
)
|
|
item(tt(hideval))(
|
|
for parameters with the `hideval' flag (tt(-H))
|
|
)
|
|
item(tt(nameref))(
|
|
for named references (tt(typeset -n)) either having an empty value or
|
|
when combined with `tt(!)' as in `tt(${LPAR()!t)tt(RPAR()var(rname)})'
|
|
)
|
|
item(tt(special))(
|
|
for special parameters defined by the shell
|
|
)
|
|
enditem()
|
|
)
|
|
item(tt(u))(
|
|
Expand only the first occurrence of each unique word, like `tt(typeset -U)'.
|
|
)
|
|
item(tt(U))(
|
|
Convert all letters in the result to upper case, like `tt(typeset -u)'.
|
|
)
|
|
item(tt(v))(
|
|
Used with tt(k), substitute (as two consecutive words) both the key
|
|
and the value of each associative array element. Used with subscripts,
|
|
force values to be substituted even if the subscript form refers to
|
|
indices or keys.
|
|
)
|
|
item(tt(V))(
|
|
Make any special characters in the resulting words visible.
|
|
)
|
|
item(tt(w))(
|
|
With tt(${#)var(name)tt(}), count words in arrays or strings; the tt(s)
|
|
flag may be used to set a word delimiter.
|
|
)
|
|
item(tt(W))(
|
|
Similar to tt(w) with the difference that empty words between
|
|
repeated delimiters are also counted.
|
|
)
|
|
item(tt(X))(
|
|
With this flag, parsing errors occurring with the tt(Q), tt(e) and tt(#)
|
|
flags or the pattern matching forms such as
|
|
`tt(${)var(name)tt(#)var(pattern)tt(})' are reported. Without the flag,
|
|
errors are silently ignored.
|
|
)
|
|
item(tt(z))(
|
|
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 tt(INTERACTIVE_COMMENTS) option unset
|
|
(however, see the tt(Z) flag below for related options)
|
|
|
|
Note that this is done very late, even later than the `tt((s))' flag. So to
|
|
access single words in the result use nested expansions as
|
|
in `tt(${${(z)foo}[2]})'. Likewise, to remove the quotes in the
|
|
resulting words use `tt(${(Q)${(z)foo}})'.
|
|
)
|
|
item(tt(0))(
|
|
Split the result of the expansion on null bytes. This is a shorthand
|
|
for `tt(ps:\0:)'.
|
|
)
|
|
enditem()
|
|
|
|
The following flags (except tt(p)) are followed by one or more arguments
|
|
as shown. Any character, or the matching pairs `tt(LPAR())...tt(RPAR())',
|
|
`tt({)...tt(})', `tt([)...tt(])', or `tt(<)...tt(>)', 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.
|
|
|
|
startitem()
|
|
item(tt(p))(
|
|
Recognize the same escape sequences as the tt(print) builtin
|
|
in string arguments to any of the flags described below that
|
|
follow this argument.
|
|
|
|
Alternatively, with this option string arguments may be in the form
|
|
tt($)var(var) in which case the value of the variable is substituted.
|
|
Note this form is strict; the string argument does not undergo general
|
|
parameter expansion.
|
|
|
|
For example,
|
|
|
|
example(sep=:
|
|
val=a:b:c
|
|
print ${+LPAR()ps.$sep.+RPAR()val})
|
|
|
|
splits the variable on a tt(:).
|
|
)
|
|
item(tt(~))(
|
|
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 tt(~) within the same set of parentheses. Compare with tt(~)
|
|
outside parentheses, which forces the entire substituted string to
|
|
be treated as a pattern. Hence, for example,
|
|
|
|
example([[ "?" = ${(~j.|.)array} ]])
|
|
|
|
treats `tt(|)' as a pattern and succeeds if and only if tt($array)
|
|
contains the string `tt(?)' as an element. The tt(~) may be
|
|
repeated to toggle the behaviour; its effect only lasts to the
|
|
end of the parenthesised group.
|
|
)
|
|
item(tt(j:)var(string)tt(:))(
|
|
Join the words of arrays together using var(string) as a separator.
|
|
pindex(SH_WORD_SPLIT, use of)
|
|
Note that this occurs before field splitting by the tt(s:)var(string)tt(:)
|
|
flag or the tt(SH_WORD_SPLIT) option.
|
|
)
|
|
item(tt(l:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))(
|
|
Pad the resulting words on the left. Each word will be truncated if
|
|
required and placed in a field var(expr) characters wide.
|
|
|
|
The arguments tt(:)var(string1)tt(:) and tt(:)var(string2)tt(:) 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 var(string1) (concatenated as
|
|
often as needed) or spaces if var(string1) is not given. If both
|
|
var(string1) and var(string2) are given, var(string2) is inserted once
|
|
directly to the left of each word, truncated if necessary, before
|
|
var(string1) is used to produce any remaining padding.
|
|
|
|
If either of var(string1) or var(string2) is present but empty,
|
|
i.e. there are two delimiters together at that point, the first
|
|
character of tt($IFS) is used instead.
|
|
|
|
If the tt(MULTIBYTE) option is in effect, the flag tt(m) may also
|
|
be given, in which case widths will be used for the calculation of
|
|
padding; otherwise individual multibyte characters are treated as occupying
|
|
one unit of width.
|
|
|
|
If the tt(MULTIBYTE) option is not in effect, each byte in the string is
|
|
treated as occupying one unit of width.
|
|
|
|
Control characters are always assumed to be one unit wide; this allows the
|
|
mechanism to be used for generating repetitions of control characters.
|
|
)
|
|
item(tt(m))(
|
|
Only useful together with one of the flags tt(l) or tt(r) or with the
|
|
tt(#) length operator when the tt(MULTIBYTE) option
|
|
is in effect. Use the character width reported by the system in
|
|
calculating how much of the string it occupies or the overall
|
|
length of the string. Most printable characters have a width of one
|
|
unit, however certain Asian character sets and certain special effects
|
|
use wider characters; combining characters have zero width.
|
|
Non-printable characters are arbitrarily counted as zero width; how they
|
|
would actually be displayed will vary.
|
|
|
|
If the tt(m) is repeated, the character either counts zero (if it has
|
|
zero width), else one. For printable character strings this has the
|
|
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).
|
|
)
|
|
item(tt(r:)var(expr)tt(::)var(string1)tt(::)var(string2)tt(:))(
|
|
As tt(l), but pad the words on the right and insert var(string2)
|
|
immediately to the right of the string to be padded.
|
|
|
|
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.
|
|
)
|
|
item(tt(s:)var(string)tt(:))(
|
|
Force field splitting at the
|
|
separator var(string). Note that a var(string) 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 tt(IFS) parameter.
|
|
See also the tt(=) flag and the tt(SH_WORD_SPLIT) option. An empty
|
|
string may also be given in which case every character will be a separate
|
|
element.
|
|
|
|
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:
|
|
|
|
example(line="one::three"
|
|
print -l "${(s.:.)line}")
|
|
|
|
produces two lines of output for tt(one) and tt(three) and elides the
|
|
empty field. To override this behaviour, supply the `tt((@))' flag as well,
|
|
i.e. tt("${(@s.:.)line}").
|
|
)
|
|
item(tt(Z:)var(opts)tt(:))(
|
|
As tt(z) but takes a combination of option letters between a following
|
|
pair of delimiter characters. With no options the effect is identical
|
|
to tt(z). The following options are available:
|
|
|
|
startitem()
|
|
item(tt(LPAR()Z+PLUS()c+PLUS()RPAR()))(
|
|
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.
|
|
)
|
|
item(tt(LPAR()Z+PLUS()C+PLUS()RPAR()))(
|
|
causes comments to be parsed
|
|
and removed. The rule for comments is standard: anything between a word
|
|
starting with the third character of tt($HISTCHARS), default tt(#), up to
|
|
the next newline is a comment.
|
|
)
|
|
item(tt(LPAR()Z+PLUS()n+PLUS()RPAR()))(
|
|
causes
|
|
unquoted newlines to be treated as ordinary whitespace, else they are
|
|
treated as if they are shell code delimiters and converted to
|
|
semicolons.
|
|
)
|
|
enditem()
|
|
|
|
Options are combined within the same set of delimiters,
|
|
e.g. tt(LPAR()Z+PLUS()Cn+PLUS()RPAR()).
|
|
)
|
|
item(tt(_:)var(flags)tt(:))(
|
|
The underscore (tt(_)) flag is reserved for future use. As of this
|
|
revision of zsh, there are no valid var(flags); anything following an
|
|
underscore, other than an empty pair of delimiters, is treated as an
|
|
error, and the flag itself has no effect.
|
|
)
|
|
enditem()
|
|
|
|
The following flags are meaningful with the tt(${)...tt(#)...tt(}) or
|
|
tt(${)...tt(%)...tt(}) forms. The tt(S), tt(I), and tt(*) flags may also be
|
|
used with the tt(${)...tt(/)...tt(}) forms.
|
|
|
|
startitem()
|
|
item(tt(S))(
|
|
With tt(#) or tt(##), search for the match that starts closest to the start of
|
|
the string (a `substring match'). Of all matches at a particular position,
|
|
tt(#) selects the shortest and tt(##) the longest:
|
|
|
|
example(% str="aXbXc"
|
|
% echo ${+LPAR()S+RPAR()str#X*}
|
|
abXc
|
|
% echo ${+LPAR()S+RPAR()str##X*}
|
|
a
|
|
% )
|
|
|
|
With tt(%) or tt(%%), search for the match that starts closest to the end of
|
|
the string:
|
|
|
|
example(% str="aXbXc"
|
|
% echo ${+LPAR()S+RPAR()str%X*}
|
|
aXbc
|
|
% echo ${+LPAR()S+RPAR()str%%X*}
|
|
aXb
|
|
% )
|
|
|
|
(Note that tt(%) and tt(%%) don't search for the match that ends closest to the
|
|
end of the string, as one might expect.)
|
|
|
|
With substitution via tt(${)...tt(/)...tt(}) or
|
|
tt(${)...tt(//)...tt(}), specifies non-greedy matching, i.e. that the
|
|
shortest instead of the longest match should be replaced:
|
|
|
|
example(% str="abab"
|
|
% echo ${str/*b/_}
|
|
_
|
|
% echo ${+LPAR()S+RPAR()str/*b/_}
|
|
_ab
|
|
% )
|
|
)
|
|
item(tt(I:)var(expr)tt(:))(
|
|
Search the var(expr)th match (where var(expr) evaluates to a number).
|
|
This only applies when searching for substrings, either with the tt(S)
|
|
flag, or with tt(${)...tt(/)...tt(}) (only the var(expr)th match is
|
|
substituted) or tt(${)...tt(//)...tt(}) (all matches from the
|
|
var(expr)th on are substituted). The default is to take the first match.
|
|
|
|
The var(expr)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 tt(${)...tt(%)...tt(}) and tt(${)...tt(%%)...tt(}) 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.
|
|
|
|
Hence with the string
|
|
example(which switch is the right switch for Ipswich?)
|
|
substitutions of the form
|
|
tt(${)LPAR()tt(SI:)var(N)tt(:)RPAR()tt(string#w*ch}) as var(N) increases
|
|
from 1 will match and remove `tt(which)', `tt(witch)', `tt(witch)' and
|
|
`tt(wich)'; the form using `tt(##)' will match and remove `tt(which switch
|
|
is the right switch for Ipswich)', `tt(witch is the right switch for
|
|
Ipswich)', `tt(witch for Ipswich)' and `tt(wich)'. The form using `tt(%)'
|
|
will remove the same matches as for `tt(#)', but in reverse order, and the
|
|
form using `tt(%%)' will remove the same matches as for `tt(##)' in reverse
|
|
order.
|
|
)
|
|
item(tt(*))(
|
|
pindex(EXTENDED_GLOB, enable)
|
|
Enable tt(EXTENDED_GLOB) for substitution via tt(${)...tt(/)...tt(}) or
|
|
tt(${)...tt(//)...tt(}). Note that `tt(**)' does not disable extendedglob.
|
|
)
|
|
item(tt(B))(
|
|
Include the index of the beginning of the match in the result.
|
|
)
|
|
item(tt(E))(
|
|
Include the index one character past the end of the match in the result
|
|
(note this is inconsistent with other uses of parameter index).
|
|
)
|
|
item(tt(M))(
|
|
Include the matched portion in the result.
|
|
)
|
|
item(tt(N))(
|
|
Include the length of the match in the result.
|
|
)
|
|
item(tt(R))(
|
|
Include the unmatched portion in the result (the em(R)est).
|
|
)
|
|
enditem()
|
|
|
|
subsect(Named References)
|
|
cindex(named references)
|
|
cindex(namerefs)
|
|
cindex(reference variables)
|
|
cindex(parameters, nameref)
|
|
The command
|
|
ifzman()
|
|
indent(tt(typeset -n )var(pname)tt(=)var(rname))
|
|
|
|
initializes a parameter var(pname) as a reference to a second
|
|
parameter var(rname). With the few exceptions described here, when
|
|
var(pname) is used in any of the expansion forms described above, the
|
|
parameter var(rname) is expanded instead. This is similar to the
|
|
action of the `tt((P))' expansion flag, but when var(rname) has itself
|
|
been declared a named reference, that third parameter referenced by
|
|
var(pname) is also expanded, and so on. With `tt((P))' this must be
|
|
done explicitly, so for example
|
|
tt(${LPAR()P)tt(RPAR()${LPAR()P)tt(RPAR())var(name)tt(}}).
|
|
|
|
Unlike `tt((P))', named references in substitutions that perform
|
|
assignment, such as tt(${)var(pname)tt(::=)var(word)tt(}), do not
|
|
create new arrays when var(rname) is in the form of an array element
|
|
or slice and no such array (or associative array) is presently set.
|
|
This includes arrays declared, but not initialized, when the option
|
|
tt(TYPESET_TO_UNSET) is in effect. The var(word) is substituted but
|
|
no assignment occurs.
|
|
|
|
Also unlike `tt((P))' named references always expand parameters at
|
|
the scope in which var(rname) existed when `tt(typeset -n)' was
|
|
called. This can be used to expand or assign parameters from an
|
|
earlier scope even if a local of the same name has been declared at
|
|
a later scope. Example:
|
|
ifzman()
|
|
example(tt(caller=OUTER)
|
|
tt(func LPAR()RPAR() {)
|
|
tt( print before local: $caller)
|
|
tt( typeset -n outer=$1)
|
|
tt( local caller=INNER)
|
|
tt( print by reference: $outer)
|
|
tt( outer=RESULT)
|
|
tt(})
|
|
tt(func caller)
|
|
tt(print after func: $caller))
|
|
|
|
displays the output
|
|
ifzman()
|
|
example(tt(before local: OUTER)
|
|
tt(by reference: OUTER)
|
|
tt(after func: RESULT))
|
|
|
|
To force a named reference to refer to the outer scope, even if a local
|
|
has already been declared, add the tt(-u) option when declaring the
|
|
named reference. In this case var(rname) should already exist in the
|
|
outer scope, otherwise the behavior of assignment through var(pname)
|
|
is not defined and may change the scope of the reference or fail with
|
|
a status of 1. Example of correct usage:
|
|
ifzman()
|
|
example(tt(caller=OUTER)
|
|
tt(func LPAR()RPAR() {)
|
|
tt( print before local: $caller)
|
|
tt( local caller=INNER)
|
|
tt( print after local: $caller)
|
|
tt( typeset -n -u outer=$1)
|
|
tt( print by reference: $outer)
|
|
tt( outer=RESULT)
|
|
tt(})
|
|
tt(func caller)
|
|
tt(print after func: $caller))
|
|
|
|
Note, however, that named references to em(special) parameters acquire
|
|
the behavior of the special parameter, regardless of the scope where
|
|
the reference is declared.
|
|
|
|
When var(rname) includes an array subscript, the subscript expression
|
|
is interpreted at the time tt(${)var(pname)tt(}) is expanded. Any
|
|
form of subscript is allowed, including those that select individual
|
|
elements, substrings of scalar strings, or multiple elements as with
|
|
array slices or the `tt((i))', `tt((I))', `tt((r))', `tt((R))' and
|
|
`tt((w))' subscript flags. However, the subscript is evaluated with
|
|
the tt(NO_EXEC) option in effect, so command substitution and other
|
|
similar constructs produce no output, although are not syntactically
|
|
excluded.
|
|
|
|
When var(rname) is an array (but not an array element or slice), the
|
|
named reference may also be used in substitutions requiring an
|
|
var(arrayname), so these are equivalent:
|
|
ifzman()
|
|
example(tt(${)var(name)tt(:|)var(rname)tt(})
|
|
tt(${)var(name)tt(:|)var(pname)tt(}))
|
|
|
|
Expansions of the form `tt(${LPAR()t)tt(RPAR())var(pname)tt(})' expand
|
|
the type information of var(rname), unless var(rname) is empty, in which
|
|
case the expansion is `tt(nameref)', or when no variable var(rname)
|
|
exists, in which case the expansion is empty.
|
|
|
|
See also ifzman(zmanref(zshparam))ifnzman(noderef(Parameters)).
|
|
|
|
subsect(Rules)
|
|
cindex(parameter expansion rules)
|
|
cindex(rules, parameter expansion)
|
|
cindex(substitution, parameter, rules)
|
|
Here is a summary of the rules for substitution; this assumes that braces
|
|
are present around the substitution, i.e. tt(${)var(...)tt(}). Some particular
|
|
examples are given below. Note that the Zsh Development Group accepts
|
|
em(no responsibility) for any brain damage which may occur during the
|
|
reading of the following rules.
|
|
|
|
startitem()
|
|
item(tt(1.) em(Nested substitution))(
|
|
If multiple nested tt(${)var(...)tt(}) 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.
|
|
|
|
Note that, unless the `tt((P))' flag or a named reference is present,
|
|
the flags and any
|
|
subscripts apply directly to the value of the nested substitution; for
|
|
example, the expansion tt(${${foo}}) behaves exactly the same as
|
|
tt(${foo}). When a named reference or the `tt((P))' flag is used in a
|
|
nested substitution,
|
|
the other substitution rules are applied to the value em(before) it is
|
|
interpreted as a name, so tt(${${(P)foo}}) may differ from tt(${(P)foo}).
|
|
When both a named reference and the `tt((P))' flag appear, the named
|
|
reference is resolved before `tt((P))' is applied.
|
|
|
|
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 tt(~) and tt(=)). Thus, for example, tt(${${:-=cat}:h})
|
|
expands to the directory where the tt(cat) program resides. (Explanation:
|
|
the internal substitution has no parameter but a default value tt(=cat),
|
|
which is expanded by filename expansion to a full path; the outer
|
|
substitution then applies the modifier tt(:h) and takes the directory part
|
|
of the path.)
|
|
)
|
|
item(tt(2.) em(Internal parameter flags))(
|
|
Any parameter flags set by one of the tt(typeset) family of commands, in
|
|
particular the tt(-L), tt(-R), tt(-Z), tt(-u) and tt(-l) options for
|
|
padding and capitalization, are applied directly to the parameter value.
|
|
Note these flags are options to the command, e.g. `tt(typeset -Z)'; they
|
|
are not the same as the flags used within parameter substitutions.
|
|
|
|
At the outermost level of substitution, the `tt((P))' flag (rule tt(4.))
|
|
ignores these transformations and uses the unmodified value of the
|
|
parameter as the name to be replaced. This is usually the desired
|
|
behavior because padding may make the value syntactically illegal as a
|
|
parameter name, but if capitalization changes are desired, use the
|
|
tt(${${(P)foo}}) form (rule tt(25.)).
|
|
)
|
|
item(tt(3.) em(Parameter subscripting))(
|
|
If the value is a raw parameter reference with a subscript, such as
|
|
tt(${)var(var)tt([3]}), the effect of subscripting is applied directly to
|
|
the parameter. Subscripts are evaluated left to right; subsequent
|
|
subscripts apply to the scalar or array value yielded by the previous
|
|
subscript. Thus if tt(var) is an array, tt(${var[1][2]}) is the second
|
|
character of the first word, but tt(${var[2,4][2]}) is the entire third
|
|
word (the second word of the range of words two through four of the
|
|
original array). Any number of subscripts may appear. Flags such as
|
|
`tt((k))' and `tt((v))' which alter the result of subscripting are applied.
|
|
)
|
|
item(tt(4.) em(Parameter name replacement))(
|
|
At the outermost level of nesting only, the `tt((P))' flag is applied. This
|
|
treats the value so far as a parameter name (which may include a subscript
|
|
expression) and replaces that with the corresponding value. This
|
|
replacement occurs later if the `tt((P))' flag appears in a nested
|
|
substitution.
|
|
|
|
If the value so far names a parameter that has internal flags (rule tt(2.)),
|
|
those internal flags are applied to the new value after replacement.
|
|
)
|
|
item(tt(5.) em(Double-quoted joining))(
|
|
If the value after this process is an array, and the substitution
|
|
appears in double quotes, and neither an `tt((@))' flag nor a `tt(#)'
|
|
length operator is present at the current level, then words of the
|
|
value are joined with the first character of the parameter tt($IFS),
|
|
by default a space, between each word (single word arrays are not
|
|
modified). If the `tt((j))' flag is present, that is used for joining
|
|
instead of tt($IFS).
|
|
)
|
|
item(tt(6.) em(Nested subscripting))(
|
|
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
|
|
tt(3.), multiple subscripts can appear. Note that tt(${foo[2,4][2]}) is
|
|
thus equivalent to tt(${${foo[2,4]}[2]}) and also to
|
|
tt("${${(@)foo[2,4]}[2]}") (the nested substitution returns an array in
|
|
both cases), but not to tt("${${foo[2,4]}[2]}") (the nested substitution
|
|
returns a scalar because of the quotes).
|
|
)
|
|
item(tt(7.) em(Modifiers))(
|
|
Any modifiers, as specified by a trailing `tt(#)', `tt(%)', `tt(/)'
|
|
(possibly doubled) or by a set of modifiers of the form `tt(:...)' (see
|
|
noderef(Modifiers) in noderef(History Expansion)), are applied to the words
|
|
of the value at this level.
|
|
)
|
|
item(tt(8.) em(Character evaluation))(
|
|
Any `tt((#))' flag is applied, evaluating the result so far numerically
|
|
as a character.
|
|
)
|
|
item(tt(9.) em(Length))(
|
|
Any initial `tt(#)' modifier, i.e. in the form tt(${#)var(var)tt(}), is
|
|
used to evaluate the length of the expression so far.
|
|
)
|
|
item(tt(10.) em(Forced joining))(
|
|
If the `tt((j))' flag is present, or no `tt((j))' flag is present but
|
|
the string is to be split as given by rule tt(11.), and joining
|
|
did not take place at rule tt(5.), any words in the value are joined
|
|
together using the given string or the first character of tt($IFS) if none.
|
|
Note that the `tt((F))' flag implicitly supplies a string for joining in this
|
|
manner.
|
|
)
|
|
item(tt(11.) em(Simple word splitting))(
|
|
If one of the `tt((s))' or `tt((f))' flags are present, or the `tt(=)'
|
|
specifier was present (e.g. tt(${=)var(var)tt(})), the word is split on
|
|
occurrences of the specified string, or (for tt(=) with neither of the two
|
|
flags present) any of the characters in tt($IFS).
|
|
|
|
If no `tt((s))', `tt((f))' or `tt(=)' was given, but the word is not
|
|
quoted and the option tt(SH_WORD_SPLIT) is set, the word is split on
|
|
occurrences of any of the characters in tt($IFS). Note this step, too,
|
|
takes place at all levels of a nested substitution.
|
|
)
|
|
item(tt(12.) em(Case modification))(
|
|
Any case modification from one of the flags `tt((L))', `tt((U))' or `tt((C))'
|
|
is applied.
|
|
)
|
|
item(tt(13.) em(Escape sequence replacement))(
|
|
First any replacements from the `tt((g))' flag are performed, then any
|
|
prompt-style formatting from the `tt((%))' family of flags is applied.
|
|
)
|
|
item(tt(14.) em(Quote application))(
|
|
Any quoting or unquoting using `tt((q))' and `tt((Q))' and related flags
|
|
is applied.
|
|
)
|
|
item(tt(15.) em(Directory naming))(
|
|
Any directory name substitution using `tt((D))' flag is applied.
|
|
)
|
|
item(tt(16.) em(Visibility enhancement))(
|
|
Any modifications to make characters visible using the `tt((V))' flag
|
|
are applied.
|
|
)
|
|
item(tt(17.) em(Lexical word splitting))(
|
|
If the 'tt((z))' flag or one of the forms of the 'tt((Z))' flag is
|
|
present, the word is split as if it were a shell command line, so that
|
|
quotation marks and other metacharacters are used to decide what
|
|
constitutes a word. Note this form of splitting is entirely distinct
|
|
from that described by rule tt(11.): it does not use tt($IFS), and
|
|
does not cause forced joining.
|
|
)
|
|
item(tt(18.) em(Uniqueness))(
|
|
If the result is an array and the `tt((u))' flag was present, duplicate
|
|
elements are removed from the array.
|
|
)
|
|
item(tt(19.) em(Ordering))(
|
|
If the result is still an array and one of the `tt((o))' or `tt((O))' flags
|
|
was present, the array is reordered.
|
|
)
|
|
item(tt(20.) tt(RC_EXPAND_PARAM))(
|
|
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 tt(RC_EXPAND_PARAM) option or the `tt(^)' flag.
|
|
)
|
|
item(tt(21.) em(Re-evaluation))(
|
|
Any `tt((e))' flag is applied to the value, forcing it to be re-examined
|
|
for new parameter substitutions, but also for command and arithmetic
|
|
substitutions.
|
|
)
|
|
item(tt(22.) em(Padding))(
|
|
Any padding of the value by the `tt(LPAR()l.)var(fill)tt(.RPAR())' or
|
|
`tt(LPAR()r.)var(fill)tt(.RPAR())' flags is applied.
|
|
)
|
|
item(tt(23.) em(Semantic joining))(
|
|
In contexts where expansion semantics requires a single word to
|
|
result, all words are rejoined with the first character of tt(IFS)
|
|
between. So in `tt(${LPAR()P)tt(RPAR()${LPAR()f)tt(RPAR()lines}})'
|
|
the value of tt(${lines}) is split at newlines, but then must be
|
|
joined again before the `tt((P))' flag can be applied.
|
|
|
|
If a single word is not required, this rule is skipped.
|
|
)
|
|
item(tt(24.) em(Empty argument removal))(
|
|
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.
|
|
|
|
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.
|
|
)
|
|
item(tt(25.) em(Nested parameter name replacement))(
|
|
If the `tt((P))' flag is present and rule tt(4.) has not applied, the
|
|
value so far is treated as a parameter name (which may include a subscript
|
|
expression) and replaced with the corresponding value, with internal flags
|
|
(rule tt(2.)) applied to the new value.
|
|
)
|
|
enditem()
|
|
|
|
subsect(Examples)
|
|
cindex(parameter expansion, examples)
|
|
The flag tt(f) is useful to split a double-quoted substitution line by
|
|
line. For example, tt(${(f)"$LPAR()<)var(file)tt(RPAR()"})
|
|
substitutes the contents of var(file) divided so that each line is
|
|
an element of the resulting array. Compare this with the effect of
|
|
tt($)tt(LPAR()<)var(file)tt(RPAR()) 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.
|
|
|
|
The following illustrates the rules for nested parameter expansions.
|
|
Suppose that tt($foo) contains the array tt(LPAR()bar baz)tt(RPAR()):
|
|
|
|
startitem()
|
|
item(tt("${(@)${foo}[1]}"))(
|
|
This produces the result tt(b). First, the inner substitution
|
|
tt("${foo}"), which has no array (tt(@)) flag, produces a single word
|
|
result tt("bar baz"). The outer substitution tt("${(@)...[1]}") detects
|
|
that this is a scalar, so that (despite the `tt((@))' flag) the subscript
|
|
picks the first character.
|
|
)
|
|
item(tt("${${(@)foo}[1]}"))(
|
|
This produces the result `tt(bar)'. In this case, the inner substitution
|
|
tt("${(@)foo}") produces the array `tt(LPAR()bar baz)tt(RPAR())'. The outer
|
|
substitution tt("${...[1]}") detects that this is an array and picks the
|
|
first word. This is similar to the simple case tt("${foo[1]}").
|
|
)
|
|
enditem()
|
|
|
|
As an example of the rules for word splitting and joining, suppose tt($foo)
|
|
contains the array `tt(LPAR()ax1 bx1)tt(RPAR())'. Then
|
|
|
|
startitem()
|
|
item(tt(${(s/x/)foo}))(
|
|
produces the words `tt(a)', `tt(1 b)' and `tt(1)'.
|
|
)
|
|
item(tt(${(j/x/s/x/)foo}))(
|
|
produces `tt(a)', `tt(1)', `tt(b)' and `tt(1)'.
|
|
)
|
|
item(tt(${(s/x/)foo%%1*}))(
|
|
produces `tt(a)' and `tt( b)' (note the extra space). As substitution
|
|
occurs before either joining or splitting, the operation first generates
|
|
the modified array tt(LPAR()ax bx)tt(RPAR()), which is joined to give
|
|
tt("ax bx"), and then split to give `tt(a)', `tt( b)' and `'. The final
|
|
empty string will then be elided, as it is not in double quotes.
|
|
)
|
|
enditem()
|
|
|
|
texinode(Command Substitution)(Arithmetic Expansion)(Parameter Expansion)(Expansion)
|
|
sect(Command Substitution)
|
|
cindex(command substitution)
|
|
cindex(substitution, command)
|
|
A command enclosed in parentheses preceded by a dollar sign, like
|
|
`tt($LPAR())...tt(RPAR())', or quoted with grave accents, like
|
|
`tt(`)...tt(`)', is executed in a subshell and replaced by 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 tt(IFS) parameter.
|
|
vindex(IFS, use of)
|
|
|
|
The substitution `tt($LPAR()cat) var(foo)tt(RPAR())' may be replaced
|
|
by the faster `tt($LPAR()<)var(foo)tt(RPAR())'. In this case var(foo)
|
|
undergoes single word shell expansions (em(parameter expansion),
|
|
em(command substitution) and em(arithmetic expansion)), but not
|
|
filename generation. No subshell is created.
|
|
|
|
If the option tt(GLOB_SUBST) is set, the result of any unquoted command
|
|
substitution, including the special form just mentioned, is eligible for
|
|
filename generation.
|
|
|
|
A command with a leading pipe character, enclosed in braces prefixed by
|
|
a dollar sign, as in `tt(${|)...tt(})', is executed in the current shell
|
|
context, rather than in a subshell, and is replaced by the value of the
|
|
parameter tt(REPLY) at the end of the command. There em(must not) be
|
|
any whitespace between the opening brace and the pipe character. Any
|
|
prior value of tt($REPLY) is saved and restored around this substitution,
|
|
in the manner of a function local parameter. Other parameters declared
|
|
within the substitution also behave as locals, as if in a function,
|
|
unless `tt(typeset -g)' is used. Trailing newlines are em(not) deleted
|
|
from the final replacement in this case, and it is subject to filename
|
|
generation in the same way as `tt($LPAR())...tt(RPAR())' but is em(not)
|
|
split on tt(IFS) unless the tt(SH_WORD_SPLIT) option is set.
|
|
|
|
cindex(substitution, command, current shell)
|
|
cindex(substitution, command, non forking)
|
|
cindex(substitution, nofork)
|
|
Substitutions of the form `tt(${|)var(param)tt(|)...tt(})' are similar,
|
|
except that the substitution is replaced by the value of the parameter
|
|
named by var(param). No implicit save or restore applies to var(param)
|
|
except as noted for tt(REPLY), and var(param) should em(not) be declared
|
|
within the command. If, after evaluating the expression, var(param)
|
|
names an array, array expansion rules apply. However, tt(REPLY) is
|
|
always expanded in scalar context, even if assigned an array.
|
|
|
|
A command enclosed in braces preceded by a dollar sign, and set off from
|
|
the braces by whitespace, like `tt(${ )...tt( })', is replaced by its
|
|
standard output. Like `tt(${|)...tt(})' and unlike
|
|
`tt($LPAR())...tt(RPAR())', the command executes in the current shell
|
|
context with function local behaviors and does not create a subshell.
|
|
Word splitting does not apply unless tt(SH_WORD_SPLIT) is set, but a
|
|
single trailing newline is stripped unless the substitution is enclosed
|
|
in double quotes.
|
|
|
|
Note that because the `tt(${|)...tt(})' and `tt(${ )...tt( })' forms
|
|
must be parsed at once as both string tokens and commands, all other
|
|
braces (`tt({)' or `tt(})') within the command either must be quoted,
|
|
or must appear in syntactically valid pairs, such as around complex
|
|
commands, function bodies, or parameter references. Furthermore,
|
|
comments are always recognized, even when tt(NO_INTERACTIVE_COMMENTS)
|
|
is in effect.
|
|
|
|
texinode(Arithmetic Expansion)(Brace Expansion)(Command Substitution)(Expansion)
|
|
sect(Arithmetic Expansion)
|
|
cindex(arithmetic expansion)
|
|
cindex(expansion, arithmetic)
|
|
A string of the form `tt($[)var(exp)tt(])' or
|
|
`tt($LPAR()LPAR())var(exp)tt(RPAR()RPAR())' is substituted
|
|
with the value of the arithmetic expression var(exp). var(exp) is
|
|
subjected to em(parameter expansion), em(command substitution)
|
|
and em(arithmetic expansion) before it is evaluated.
|
|
See noderef(Arithmetic Evaluation).
|
|
texinode(Brace Expansion)(Filename Expansion)(Arithmetic Expansion)(Expansion)
|
|
sect(Brace Expansion)
|
|
cindex(brace expansion)
|
|
cindex(expansion, brace)
|
|
A string of the form
|
|
`var(foo)tt({)var(xx)tt(,)var(yy)tt(,)var(zz)tt(})var(bar)'
|
|
is expanded to the individual words
|
|
`var(fooxxbar)', `var(fooyybar)' and `var(foozzbar)'.
|
|
Left-to-right order is preserved. This construct
|
|
may be nested. Commas may be quoted in order to
|
|
include them literally in a word.
|
|
|
|
An expression of the form `tt({)var(n1)tt(..)var(n2)tt(})',
|
|
where var(n1) and var(n2) are integers,
|
|
is expanded to every number between
|
|
var(n1) and var(n2) 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 tt(-) character is also
|
|
included in the width. If the numbers are in decreasing order the
|
|
resulting sequence will also be in decreasing order.
|
|
|
|
An expression of the form `tt({)var(n1)tt(..)var(n2)tt(..)var(n3)tt(})',
|
|
where var(n1), var(n2), and var(n3) are integers,
|
|
is expanded as above, but only every var(n3)th number starting from var(n1)
|
|
is output. If var(n3) is negative the numbers are output in reverse order,
|
|
this is slightly different from simply swapping var(n1) and var(n2) in the case
|
|
that the step var(n3) 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 `tt({-99..100..01})' which is not possible to specify by putting a
|
|
0 on either of the first two numbers (i.e. pad to two characters).
|
|
|
|
An expression of the form `tt({)var(c1)tt(..)var(c2)tt(})', where
|
|
var(c1) and var(c2) are single characters (which may be multibyte
|
|
characters), is expanded to every character in the range from var(c1) to
|
|
var(c2) 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
|
|
printable, appropriate quotation is used to render it printable.
|
|
If the character sequence is reversed, the output is in reverse
|
|
order, e.g. `tt({d..a})' is substituted as `tt(d c b a)'.
|
|
|
|
If a brace expression matches none of the above forms, it is left
|
|
unchanged, unless the option tt(BRACE_CCL) (an abbreviation for `brace
|
|
character class') is set.
|
|
pindex(BRACE_CCL, use of)
|
|
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
|
|
tt([)...tt(]) expression in filename generation:
|
|
`tt(-)' is treated specially to denote a range of characters, but `tt(^)' or
|
|
`tt(!)' as the first character is treated normally. For example,
|
|
`tt({abcdef0-9})' expands to 16 words tt(0 1 2 3 4 5 6 7 8 9 a b c d e f).
|
|
|
|
Note that brace expansion is not part of filename generation (globbing); an
|
|
expression such as tt(*/{foo,bar}) is split into two separate words
|
|
tt(*/foo) and tt(*/bar) before filename generation takes place. In
|
|
particular, note that this is liable to produce a `no match' error if
|
|
em(either) of the two expressions does not match; this is to be contrasted
|
|
with tt(*/(foo|bar)), which is treated as a single pattern but otherwise
|
|
has similar effects.
|
|
|
|
To combine brace expansion with array expansion, see the
|
|
tt(${^)var(spec)tt(}) form described
|
|
ifzman(in the section `Parameter Expansion')\
|
|
ifnzman(in noderef(Parameter Expansion))
|
|
above.
|
|
|
|
texinode(Filename Expansion)(Filename Generation)(Brace Expansion)(Expansion)
|
|
sect(Filename Expansion)
|
|
cindex(filename expansion)
|
|
cindex(expansion, filename)
|
|
Each word is checked to see if it begins with an unquoted `tt(~)'.
|
|
If it does, then the word up to a `tt(/)',
|
|
or the end of the word if there is no `tt(/)',
|
|
is checked to see if it can be substituted in one of the ways
|
|
described here. If so, then the `tt(~)' and the checked portion are
|
|
replaced with the appropriate substitute value.
|
|
|
|
A `tt(~)' by itself is replaced by the value of tt($HOME).
|
|
A `tt(~)' followed by a `tt(PLUS())' or a `tt(-)' is replaced by current
|
|
or previous working directory, respectively.
|
|
|
|
A `tt(~)' followed by a number is replaced by the directory at that
|
|
position in the directory stack.
|
|
`tt(~0)' is equivalent to `tt(~PLUS())',
|
|
and `tt(~1)' is the top of the stack.
|
|
`tt(~PLUS())' followed by a number is replaced by the directory at that
|
|
position in the directory stack.
|
|
`tt(~PLUS()0)' is equivalent to `tt(~PLUS())',
|
|
and `tt(~PLUS()1)' is the top of the stack.
|
|
`tt(~-)' followed by a number is replaced by the directory that
|
|
many positions from the bottom of the stack.
|
|
`tt(~-0)' is the bottom of the stack.
|
|
pindex(PUSHD_MINUS, use of)
|
|
The tt(PUSHD_MINUS)
|
|
option exchanges the effects of `tt(~PLUS())' and `tt(~-)' where they are
|
|
followed by a number.
|
|
|
|
startmenu()
|
|
menu(Dynamic named directories)
|
|
menu(Static named directories)
|
|
menu(`=' expansion)
|
|
menu(Notes)
|
|
endmenu()
|
|
|
|
texinode(Dynamic named directories)(Static named directories)()(Filename Expansion)
|
|
subsect(Dynamic named directories)
|
|
cindex(directories, named, dynamic)
|
|
cindex(named directories, dynamic)
|
|
cindex(dynamic named directories)
|
|
If the function tt(zsh_directory_name) exists, or the shell variable
|
|
tt(zsh_directory_name_functions) exists and contains an array of
|
|
function names, then the functions are used to implement dynamic
|
|
directory naming. The functions are tried in order until one returns
|
|
status zero, so it is important that functions test whether they can
|
|
handle the case in question and return an appropriate status.
|
|
|
|
A `tt(~)' followed by a string var(namstr) in unquoted square brackets is
|
|
treated specially as a dynamic directory name. Note that the first
|
|
unquoted closing square bracket always terminates var(namstr). The shell
|
|
function is passed two arguments: the string tt(n) (for name) and
|
|
var(namstr). It should either set the array tt(reply) to a single element
|
|
which is the directory corresponding to the name and return status zero
|
|
(executing an assignment as the last statement is usually sufficient), or
|
|
it should return status non-zero. In the former case the element of reply
|
|
is used as the directory; in the latter case the substitution is deemed to
|
|
have failed. If all functions fail and the option tt(NOMATCH) is set,
|
|
an error results.
|
|
|
|
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 tt(%~) in prompts. In this case each function is passed two
|
|
arguments: the string tt(d) (for directory) and the candidate for dynamic
|
|
naming. The function should either return non-zero status, if the
|
|
directory cannot be named by the function, or it should set the array reply
|
|
to consist of two elements: the first is the dynamic name for the directory
|
|
(as would appear within `tt(~[)var(...)tt(])'), and the second is the
|
|
prefix length of the directory to be replaced. For example, if the trial
|
|
directory is tt(/home/myname/src/zsh) and the dynamic name for
|
|
tt(/home/myname/src) (which has 16 characters) is tt(s), then the function
|
|
sets
|
|
|
|
example(reply=(s 16))
|
|
|
|
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.
|
|
|
|
It is not a requirement that a function implements both
|
|
tt(n) and tt(d) calls; for example, it might be appropriate for certain
|
|
dynamic forms of expansion not to be contracted to names. In that case
|
|
any call with the first argument tt(d) should cause a non-zero status to
|
|
be returned.
|
|
|
|
The completion system calls `tt(zsh_directory_name c)' followed by
|
|
equivalent calls to elements of the array
|
|
tt(zsh_directory_name_functions), if it exists, in order to
|
|
complete dynamic names for directories. The code for this should be
|
|
as for any other completion function as described in
|
|
ifnzman(noderef(Completion System))\
|
|
ifzman(zmanref(zshcompsys)).
|
|
|
|
As a working example, here is a function that expands any dynamic names
|
|
beginning with the string tt(p:) to directories below
|
|
tt(/home/pws/perforce). In this simple case a static name for the
|
|
directory would be just as effective.
|
|
|
|
example(zsh_directory_name+LPAR()RPAR() {
|
|
emulate -L zsh -o extendedglob
|
|
local -a match mbegin mend
|
|
local base=/home/pws/perforce
|
|
case $1 in
|
|
( d ) # Turn the directory into a name.
|
|
[[ $2 == (#b)($base/)([^/]##)* ]] &&
|
|
reply=( p:$match[2] $(( $#match[1] + $#match[2] )) )
|
|
;;
|
|
( n ) # Turn the name into a directory.
|
|
[[ $2 == (#b)p:(?*) ]] &&
|
|
reply=( $base/$match[1] )
|
|
;;
|
|
( c ) # Complete names.
|
|
local -a dirs=( $base/*(/:t) )
|
|
# Completion system populates $expl with flags for compadd.
|
|
compadd "$expl[@]" p:$^dirs
|
|
;;
|
|
esac
|
|
})
|
|
|
|
texinode(Static named directories)(`=' expansion)(Dynamic named directories)(Filename Expansion)
|
|
subsect(Static named directories)
|
|
cindex(directories, named, static)
|
|
cindex(named directories, static)
|
|
cindex(static named directories)
|
|
A `tt(~)' followed by anything not already covered consisting
|
|
of any number of alphanumeric characters or underscore (`tt(_)'),
|
|
hyphen (`tt(-)'), or dot (`tt(.)') 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 `tt(~)' is the name
|
|
of a string shell parameter whose value begins with a `tt(/)'.
|
|
Note that trailing slashes will be removed from the path to the directory
|
|
(though the original parameter is not modified).
|
|
|
|
It is also possible to define directory names using the tt(-d) option to the
|
|
tt(hash) builtin.
|
|
|
|
When the shell prints a path (e.g. when expanding tt(%~) 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
|
|
`tt(~)' 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 tt($PWD) and tt($OLDPWD) are never abbreviated in this fashion.
|
|
|
|
texinode(`=' expansion)(Notes)(Static named directories)(Filename Expansion)
|
|
subsect(`=' expansion)
|
|
|
|
If a word begins with an unquoted `tt(=)'
|
|
and the tt(EQUALS) option is set,
|
|
the remainder of the word is taken as the
|
|
name of a command. If a command
|
|
exists by that name, the word is replaced
|
|
by the full pathname of the command.
|
|
|
|
texinode(Notes)()(`=' expansion)(Filename Expansion)
|
|
subsect(Notes)
|
|
cindex(filename expansion, notes)
|
|
Filename expansion is performed on the right hand side of a parameter
|
|
assignment, including those appearing after commands of the
|
|
tt(typeset) family. In this case, the right hand side will be treated
|
|
as a colon-separated list in the manner of the tt(PATH) parameter,
|
|
so that a `tt(~)' or an `tt(=)' following a `tt(:)' is eligible for expansion.
|
|
All such behaviour can be
|
|
disabled by quoting the `tt(~)', the `tt(=)', or the whole expression (but not
|
|
simply the colon); the tt(EQUALS) option is also respected.
|
|
|
|
If the option tt(MAGIC_EQUAL_SUBST) is set, any unquoted shell
|
|
argument in the form `var(identifier)tt(=)var(expression)' becomes eligible
|
|
for file expansion as described in the previous paragraph. Quoting the
|
|
first `tt(=)' also inhibits this.
|
|
|
|
texinode(Filename Generation)()(Filename Expansion)(Expansion)
|
|
sect(Filename Generation)
|
|
cindex(filename generation)
|
|
If a word contains an unquoted instance of one of the characters
|
|
`tt(*)', `tt(LPAR())', `tt(|)', `tt(<)', `tt([)', or `tt(?)', it is regarded
|
|
as a pattern for filename generation, unless the tt(GLOB) option is unset.
|
|
pindex(GLOB, use of)
|
|
If the tt(EXTENDED_GLOB) option is set,
|
|
pindex(EXTENDED_GLOB, use of)
|
|
the `tt(^)' and `tt(#)' characters also denote a pattern; otherwise
|
|
they are not treated specially by the shell.
|
|
|
|
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 tt(NULL_GLOB) option is set,
|
|
pindex(NULL_GLOB, use of)
|
|
in which case the word is deleted; or unless the tt(NOMATCH)
|
|
option is unset, in which case the word is left unchanged.
|
|
pindex(NOMATCH, use of)
|
|
|
|
In filename generation,
|
|
the character `tt(/)' must be matched explicitly;
|
|
also, a `tt(.)' must be matched
|
|
explicitly at the beginning of a pattern or after a `tt(/)', unless the
|
|
tt(GLOB_DOTS) option is set.
|
|
pindex(GLOB_DOTS, use of)
|
|
No filename generation pattern
|
|
matches the files `tt(.)' or `tt(..)'. In other instances of pattern
|
|
matching, the `tt(/)' and `tt(.)' are not treated specially.
|
|
subsect(Glob Operators)
|
|
cindex(glob operators)
|
|
startitem()
|
|
item(tt(*))(
|
|
Matches any string, including the null string.
|
|
)
|
|
item(tt(?))(
|
|
Matches any character.
|
|
)
|
|
item(tt([)...tt(]))(
|
|
Matches any of the enclosed characters. Ranges of characters
|
|
can be specified by separating two characters by a `tt(-)'.
|
|
A `tt(-)' or `tt(])' may be matched by including it as the
|
|
first character in the list.
|
|
cindex(character classes)
|
|
There are also several named classes of characters, in the form
|
|
`tt([:)var(name)tt(:])' 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
|
|
manref(ctype)(3):
|
|
|
|
startitem()
|
|
item(tt([:alnum:]))(
|
|
The character is alphanumeric
|
|
)
|
|
item(tt([:alpha:]))
|
|
(
|
|
The character is alphabetic
|
|
)
|
|
item(tt([:ascii:]))(
|
|
The character is 7-bit, i.e. is a single-byte character without
|
|
the top bit set.
|
|
)
|
|
item(tt([:blank:]))(
|
|
The character is a blank character
|
|
)
|
|
item(tt([:cntrl:]))(
|
|
The character is a control character
|
|
)
|
|
item(tt([:digit:]))(
|
|
The character is a decimal digit
|
|
)
|
|
item(tt([:graph:]))(
|
|
The character is a printable character other than whitespace
|
|
)
|
|
item(tt([:lower:]))(
|
|
The character is a lowercase letter
|
|
)
|
|
item(tt([:print:]))(
|
|
The character is printable
|
|
)
|
|
item(tt([:punct:]))(
|
|
The character is printable but neither alphanumeric nor whitespace
|
|
)
|
|
item(tt([:space:]))(
|
|
The character is whitespace
|
|
)
|
|
item(tt([:upper:]))(
|
|
The character is an uppercase letter
|
|
)
|
|
item(tt([:xdigit:]))(
|
|
The character is a hexadecimal digit
|
|
)
|
|
enditem()
|
|
|
|
Another set of named classes is handled internally by the shell and
|
|
is not sensitive to the locale:
|
|
|
|
startitem()
|
|
item(tt([:IDENT:]))(
|
|
The character is allowed to form part of a shell identifier, such
|
|
as a parameter name; this test respects the tt(POSIX_IDENTIFIERS)
|
|
option
|
|
)
|
|
item(tt([:IFS:]))(
|
|
The character is used as an input field separator, i.e. is contained in the
|
|
tt(IFS) parameter
|
|
)
|
|
item(tt([:IFSSPACE:]))(
|
|
The character is an IFS white space character; see the documentation
|
|
for tt(IFS) in
|
|
ifzman(the zmanref(zshparam) manual page)\
|
|
ifnzman(noderef(Parameters Used By The Shell))\
|
|
.
|
|
)
|
|
item(tt([:INCOMPLETE:]))(
|
|
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
|
|
`tt([[:INCOMPLETE:]]*)'. This will never match a sequence starting
|
|
with a valid multibyte character.
|
|
)
|
|
item(tt([:INVALID:]))(
|
|
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.
|
|
)
|
|
item(tt([:WORD:]))(
|
|
The character is treated as part of a word; this test is sensitive
|
|
to the value of the tt(WORDCHARS) parameter
|
|
)
|
|
enditem()
|
|
|
|
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 `tt([[:alnum:]])'. Named
|
|
character sets can be used alongside other types,
|
|
e.g. `tt([[:alpha:]0-9])'.
|
|
)
|
|
xitem(tt([^)...tt(]))
|
|
item(tt([!)...tt(]))(
|
|
Like tt([)...tt(]), except that it matches any character which is
|
|
not in the given set.
|
|
)
|
|
item(tt(<)[var(x)]tt(-)[var(y)]tt(>))(
|
|
Matches any number in the range var(x) to var(y), inclusive.
|
|
Either of the numbers may be omitted to make the range open-ended;
|
|
hence `tt(<->)' matches any number. To match individual digits, the
|
|
tt([)...tt(]) form is more efficient.
|
|
|
|
Be careful when using other wildcards adjacent to patterns of this form;
|
|
for example, tt(<0-9>*) will actually match any number whatsoever at the
|
|
start of the string, since the `tt(<0-9>)' will match the first digit, and
|
|
the `tt(*)' will match any others. This is a trap for the unwary, but is
|
|
in fact an inevitable consequence of the rule that the longest possible
|
|
match always succeeds. Expressions such as `tt(<0-9>[^[:digit:]]*)' can be
|
|
used instead.
|
|
)
|
|
item(tt(LPAR())...tt(RPAR()))(
|
|
Matches the enclosed pattern. This is used for grouping.
|
|
If the tt(KSH_GLOB) option is set, then a
|
|
`tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)' immediately preceding
|
|
the `tt(LPAR())' is treated specially, as detailed below. The option
|
|
tt(SH_GLOB) prevents bare parentheses from being used in this way, though
|
|
the tt(KSH_GLOB) option is still available.
|
|
|
|
Note that grouping cannot extend over multiple directories: it is an error
|
|
to have a `tt(/)' within a group (this only applies for patterns used in
|
|
filename generation). There is one exception: a group of the form
|
|
tt(LPAR())var(pat)tt(/RPAR()#) appearing as a complete path segment can
|
|
match a sequence of directories. For example, tt(foo/(a*/)#bar) matches
|
|
tt(foo/bar), tt(foo/any/bar), tt(foo/any/anyother/bar), and so on.
|
|
)
|
|
item(var(x)tt(|)var(y))(
|
|
Matches either var(x) or var(y).
|
|
This operator has lower precedence than any other.
|
|
The `tt(|)' character
|
|
must be within parentheses, to avoid interpretation as a pipeline.
|
|
The alternatives are tried in order from left to right.
|
|
)
|
|
item(tt(^)var(x))(
|
|
(Requires tt(EXTENDED_GLOB) to be set.)
|
|
Matches anything except the pattern var(x).
|
|
This has a higher precedence than `tt(/)', so `tt(^foo/bar)'
|
|
will search directories in `tt(.)' except `tt(./foo)'
|
|
for a file named `tt(bar)'.
|
|
)
|
|
item(var(x)tt(~)var(y))(
|
|
(Requires tt(EXTENDED_GLOB) to be set.)
|
|
Match anything that matches the pattern var(x) but does not match var(y).
|
|
This has lower precedence than any operator except `tt(|)', so
|
|
`tt(*/*~foo/bar)' will search for all files in all directories in `tt(.)'
|
|
and then exclude `tt(foo/bar)' if there was such a match.
|
|
Multiple patterns can be excluded by
|
|
`var(foo)tt(~)var(bar)tt(~)var(baz)'.
|
|
In the exclusion pattern (var(y)), `tt(/)' and `tt(.)' are not treated
|
|
specially the way they usually are in globbing.
|
|
)
|
|
item(var(x)tt(#))(
|
|
(Requires tt(EXTENDED_GLOB) to be set.)
|
|
Matches zero or more occurrences of the pattern var(x).
|
|
This operator has high precedence; `tt(12#)' is equivalent to `tt(1(2#))',
|
|
rather than `tt((12)#)'. It is an error for an unquoted `tt(#)' to follow
|
|
something which cannot be repeated; this includes an empty string, a
|
|
pattern already followed by `tt(##)', or parentheses when part of a
|
|
tt(KSH_GLOB) pattern (for example, `tt(!LPAR())var(foo)tt(RPAR()#)' is
|
|
invalid and must be replaced by
|
|
`tt(*LPAR()!LPAR())var(foo)tt(RPAR()RPAR())').
|
|
)
|
|
item(var(x)tt(##))(
|
|
(Requires tt(EXTENDED_GLOB) to be set.)
|
|
Matches one or more occurrences of the pattern var(x).
|
|
This operator has high precedence; `tt(12##)' is equivalent to `tt(1(2##))',
|
|
rather than `tt((12)##)'. No more than two active `tt(#)' characters may
|
|
appear together. (Note the potential clash with glob qualifiers in the
|
|
form `tt(1(2##))' which should therefore be avoided.)
|
|
)
|
|
enditem()
|
|
subsect(ksh-like Glob Operators)
|
|
pindex(KSH_GLOB, use of)
|
|
If the tt(KSH_GLOB) option is set, the effects of parentheses can be
|
|
modified by a preceding `tt(@)', `tt(*)', `tt(+)', `tt(?)' or `tt(!)'.
|
|
This character need not be unquoted to have special effects,
|
|
but the `tt(LPAR())' must be.
|
|
|
|
startitem()
|
|
item(tt(@LPAR())...tt(RPAR()))(
|
|
Match the pattern in the parentheses. (Like `tt(LPAR())...tt(RPAR())'.)
|
|
)
|
|
item(tt(*LPAR())...tt(RPAR()))(
|
|
Match any number of occurrences. (Like `tt(LPAR())...tt(RPAR()#)',
|
|
except that recursive directory searching is not supported.)
|
|
)
|
|
item(tt(PLUS()LPAR())...tt(RPAR()))(
|
|
Match at least one occurrence. (Like `tt(LPAR())...tt(RPAR()##)',
|
|
except that recursive directory searching is not supported.)
|
|
)
|
|
item(tt(?LPAR())...tt(RPAR()))(
|
|
Match zero or one occurrence. (Like `tt(LPAR()|)...tt(RPAR())'.)
|
|
)
|
|
item(tt(!LPAR())...tt(RPAR()))(
|
|
Match anything but the expression in parentheses.
|
|
(Like `tt(LPAR()^LPAR())...tt(RPAR()RPAR())'.)
|
|
)
|
|
enditem()
|
|
subsect(Precedence)
|
|
cindex(precedence of glob operators)
|
|
The precedence of the operators given above is (highest) `tt(^)', `tt(/)',
|
|
`tt(~)', `tt(|)' (lowest); the
|
|
remaining operators are simply treated from left to right as part of a
|
|
string, with `tt(#)' and `tt(##)' applying to the shortest possible
|
|
preceding unit (i.e. a character, `tt(?)', `tt([)...tt(])',
|
|
`tt(<)...tt(>)', or a parenthesised expression). As mentioned
|
|
above, a `tt(/)' used as a directory separator may not appear inside
|
|
parentheses, while a `tt(|)' must do so; in patterns used in other contexts
|
|
than filename generation (for example, in tt(case) statements and tests
|
|
within `tt([[)...tt(]])'), a `tt(/)' is not special; and `tt(/)' is also
|
|
not special after a `tt(~)' appearing outside parentheses in a filename
|
|
pattern.
|
|
subsect(Globbing Flags)
|
|
cindex(globbing flags)
|
|
cindex(glob flags)
|
|
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 tt(EXTENDED_GLOB) option. All take the form
|
|
tt(LPAR()#)var(X)tt(RPAR()) where var(X) may have one of the following
|
|
forms:
|
|
|
|
startitem()
|
|
item(tt(i))(
|
|
Case insensitive: upper or lower case characters in the pattern match
|
|
upper or lower case characters.
|
|
)
|
|
item(tt(l))(
|
|
Lower case characters in the pattern match upper or lower case
|
|
characters; upper case characters in the pattern still only match
|
|
upper case characters.
|
|
)
|
|
item(tt(I))(
|
|
Case sensitive: locally negates the effect of tt(i) or tt(l) from
|
|
that point on.
|
|
)
|
|
vindex(match)
|
|
vindex(mbegin)
|
|
vindex(mend)
|
|
item(tt(b))(
|
|
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 tt($match), the indices of the beginning of the matched
|
|
parentheses in the array tt($mbegin), and the indices of the end in the array
|
|
tt($mend), with the first element of each array corresponding to the first
|
|
parenthesised group, and so on. These arrays are not otherwise special to
|
|
the shell. The indices use the same convention as does parameter
|
|
substitution, so that elements of tt($mend) and tt($mbegin) may be used in
|
|
subscripts; the tt(KSH_ARRAYS) option is respected. Sets of globbing flags
|
|
are not considered parenthesised groups; only the first nine active
|
|
parentheses can be referenced.
|
|
|
|
For example,
|
|
|
|
example(foo="a_string_with_a_message"
|
|
if [[ $foo = (a|an)_(#b)(*) ]]; then
|
|
print ${foo[$mbegin[1],$mend[1]]}
|
|
fi)
|
|
|
|
prints `tt(string_with_a_message)'.
|
|
Note that the first set of parentheses is before the
|
|
tt((#b)) and does not create a backreference.
|
|
|
|
Backreferences work with all forms of pattern matching other than filename
|
|
generation, but note that when performing matches on an entire array, such
|
|
as tt(${)var(array)tt(#)var(pattern)tt(}), or a global substitution, such
|
|
as tt(${)var(param)tt(//)var(pat)tt(/)var(repl)tt(}), 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 tt(m) flag below.
|
|
|
|
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 `tt(#)' or `tt(##)'. Only the last match of the parenthesis is
|
|
remembered: for example, in `tt([[ abab = (#b)([ab])# ]])', only the final
|
|
`tt(b)' is stored in tt(match[1]). Thus extra parentheses may be necessary
|
|
to match the complete segment: for example, use
|
|
`tt(X+LPAR()(ab|cd)#+RPAR()Y)' to match
|
|
a whole string of either `tt(ab)' or `tt(cd)' between `tt(X)' and `tt(Y)',
|
|
using the value of tt($match[1]) rather than tt($match[2]).
|
|
|
|
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 DASH()- which happens if they are in an alternate
|
|
branch which fails to match, or if they are followed by tt(#) and matched
|
|
zero times DASH()- then the matched string is set to the empty string, and the
|
|
start and end indices are set to -1.
|
|
|
|
Pattern matching with backreferences is slightly slower than without.
|
|
)
|
|
item(tt(B))(
|
|
Deactivate backreferences, negating the effect of the tt(b) flag from that
|
|
point on.
|
|
)
|
|
item(tt(c)var(N)tt(,)var(M))(
|
|
The flag tt(LPAR()#c)var(N)tt(,)var(M)tt(RPAR()) can be used anywhere
|
|
that the tt(#) or tt(##) operators can be used except in the expressions
|
|
`tt((*/)#)' and `tt((*/)##)' in filename generation, where `tt(/)'
|
|
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 tt({)var(N)tt(,)var(M)tt(}) in regular expressions. The previous
|
|
character or group is required to match between var(N) and var(M) times,
|
|
inclusive. The form tt(LPAR()#c)var(N)tt(RPAR()) requires exactly tt(N)
|
|
matches; tt(LPAR()#c,)var(M)tt(RPAR()) is equivalent to specifying var(N)
|
|
as 0; tt(LPAR()#c)var(N)tt(,RPAR()) specifies that there is no maximum
|
|
limit on the number of matches.
|
|
)
|
|
vindex(MATCH)
|
|
vindex(MBEGIN)
|
|
vindex(MEND)
|
|
item(tt(m))(
|
|
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 tt($MATCH), tt($MBEGIN) and tt($MEND) will be set to
|
|
the string matched and to the indices of the beginning and end of the
|
|
string, respectively. This is most useful in parameter substitutions, as
|
|
otherwise the string matched is obvious.
|
|
|
|
For example,
|
|
|
|
example(arr=(veldt jynx grimps waqf zho buck)
|
|
print ${arr//(#m)[aeiou]/${(U)MATCH}})
|
|
|
|
forces all the matches (i.e. all vowels) into uppercase, printing
|
|
`tt(vEldt jynx grImps wAqf zhO bUck)'.
|
|
|
|
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.
|
|
)
|
|
item(tt(M))(
|
|
Deactivate the tt(m) flag, hence no references to match data will be
|
|
created.
|
|
)
|
|
item(tt(a)var(num))(
|
|
Approximate matching: var(num) errors are allowed in the string matched by
|
|
the pattern. The rules for this are described in the next subsection.
|
|
)
|
|
item(tt(s), tt(e))(
|
|
Unlike the other flags, these have only a local effect, and each must
|
|
appear on its own: `tt((#s))' and `tt((#e))' are the only valid forms.
|
|
The `tt((#s))' flag succeeds only at the start of the test string, and the
|
|
`tt((#e))' flag succeeds only at the end of the test string; they
|
|
correspond to `tt(^)' and `tt($)' 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, `tt(*((#s)|/)test+LPAR()(#e)|/+RPAR()*)' matches
|
|
a path segment `tt(test)' in any of the following strings: tt(test),
|
|
tt(test/at/start), tt(at/end/test), tt(in/test/middle).
|
|
|
|
Another use is in parameter substitution; for example
|
|
`tt(${array/(#s)A*Z+LPAR()#e+RPAR()})' will remove only elements of an
|
|
array which
|
|
match the complete pattern `tt(A*Z)'. There are other ways of performing
|
|
many operations of this type, however the combination of the substitution
|
|
operations `tt(/)' and `tt(//)' with the `tt((#s))' and `tt((#e))' flags
|
|
provides a single simple and memorable method.
|
|
|
|
Note that assertions of the form `tt((^(#s)))' also work, i.e. match
|
|
anywhere except at the start of the string, although this actually means
|
|
`anything except a zero-length portion at the start of the string'; you
|
|
need to use `tt((""~(#s)))' to match a zero-length portion of the string
|
|
not at the start.
|
|
)
|
|
item(tt(q))(
|
|
A `tt(q)' and everything up to the closing parenthesis of the globbing
|
|
flags are ignored by the pattern matching code. This is intended to
|
|
support the use of glob qualifiers, see below. The result is that
|
|
the pattern `tt((#b)(*).c+LPAR()#q.+RPAR())' can be used both for globbing
|
|
and for
|
|
matching against a string. In the former case, the `tt((#q.))' will be
|
|
treated as a glob qualifier and the `tt((#b))' will not be useful, while in
|
|
the latter case the `tt((#b))' is useful for backreferences and the
|
|
`tt((#q.))' will be ignored. Note that colon modifiers in the glob
|
|
qualifiers are also not applied in ordinary pattern matching.
|
|
)
|
|
item(tt(u))(
|
|
Respect the current locale in determining the presence of multibyte
|
|
characters in a pattern, provided the shell was compiled with
|
|
tt(MULTIBYTE_SUPPORT). This overrides the tt(MULTIBYTE)
|
|
option; the default behaviour is taken from the option. Compare tt(U).
|
|
(Mnemonic: typically multibyte characters are from Unicode in the UTF-8
|
|
encoding, although any extension of ASCII supported by the system
|
|
library may be used.)
|
|
)
|
|
item(tt(U))(
|
|
All characters are considered to be a single byte long. The opposite
|
|
of tt(u). This overrides the tt(MULTIBYTE) option.
|
|
)
|
|
enditem()
|
|
|
|
For example, the test string tt(fooxx) can be matched by the pattern
|
|
tt(LPAR()#i)tt(RPAR()FOOXX), but not by tt(LPAR()#l)tt(RPAR()FOOXX),
|
|
tt(LPAR()#i)tt(RPAR()FOO)tt(LPAR()#I)tt(RPAR()XX) or
|
|
tt(LPAR()LPAR()#i)tt(RPAR()FOOX)tt(RPAR()X). The string
|
|
tt(LPAR()#ia2)tt(RPAR()readme) specifies case-insensitive matching of
|
|
tt(readme) with up to two errors.
|
|
|
|
When using the ksh syntax for grouping both tt(KSH_GLOB) and
|
|
tt(EXTENDED_GLOB) must be set and the left parenthesis should be
|
|
preceded by tt(@). Note also that the flags do not affect letters
|
|
inside tt([)...tt(]) groups, in other words tt(LPAR()#i)tt(RPAR()[a-z])
|
|
still matches only lowercase letters. Finally, note that when
|
|
examining whole paths case-insensitively every directory must be
|
|
searched for all files which match, so that a pattern of the form
|
|
tt(LPAR()#i)tt(RPAR()/foo/bar/...) is potentially slow.
|
|
|
|
subsect(Approximate Matching)
|
|
cindex(approximate matching)
|
|
cindex(matching, approximate)
|
|
When matching approximately, the shell keeps a count of the errors found,
|
|
which cannot exceed the number specified in the
|
|
tt(LPAR()#a)var(num)tt(RPAR()) flags. Four types of error are recognised:
|
|
|
|
startitem()
|
|
item(1.)(
|
|
Different characters, as in tt(fooxbar) and tt(fooybar).
|
|
)
|
|
item(2.)(
|
|
Transposition of characters, as in tt(banana) and tt(abnana).
|
|
)
|
|
item(3.)(
|
|
A character missing in the target string, as with the pattern tt(road) and
|
|
target string tt(rod).
|
|
)
|
|
item(4.)(
|
|
An extra character appearing in the target string, as with tt(stove)
|
|
and tt(strove).
|
|
)
|
|
enditem()
|
|
|
|
Thus, the pattern tt(LPAR()#a3)tt(RPAR()abcd) matches tt(dcba), with the
|
|
errors occurring by using the first rule twice and the second once,
|
|
grouping the string as tt([d][cb][a]) and tt([a][bc][d]).
|
|
|
|
Non-literal parts of the pattern must match exactly, including characters
|
|
in character ranges: hence tt(LPAR()#a1)tt(RPAR()???) 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 tt(?) must match. Other characters
|
|
which must match exactly are initial dots in filenames (unless the
|
|
tt(GLOB_DOTS) option is set), and all slashes in filenames, so that
|
|
tt(a/bc) is two errors from tt(ab/c) (the slash cannot be transposed with
|
|
another character). Similarly, errors are counted separately for
|
|
non-contiguous strings in the pattern, so that tt(LPAR()ab|cd)tt(RPAR()ef)
|
|
is two errors from tt(aebf).
|
|
|
|
When using exclusion via the tt(~) operator, approximate matching is
|
|
treated entirely separately for the excluded part and must be activated
|
|
separately. Thus, tt(LPAR()#a1)tt(RPAR()README~READ_ME) matches
|
|
tt(READ.ME) but not tt(READ_ME), as the trailing tt(READ_ME) is matched
|
|
without approximation. However,
|
|
tt(LPAR()#a1)tt(RPAR()README~LPAR()#a1)tt(RPAR()READ_ME)
|
|
does not match any pattern of the form tt(READ)var(?)tt(ME) as all
|
|
such forms are now excluded.
|
|
|
|
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,
|
|
tt(LPAR()#a1)tt(RPAR()cat)tt(LPAR()LPAR()#a0)tt(RPAR()dog)tt(RPAR()fox)
|
|
allows one error in total, which may not occur in the tt(dog) section, and
|
|
the pattern
|
|
tt(LPAR()#a1)tt(RPAR()cat)tt(LPAR()#a0)tt(RPAR()dog)tt(LPAR()#a1)tt(RPAR()fox)
|
|
is equivalent. Note that the point at which an error is first found is the
|
|
crucial one for establishing whether to use approximation; for example,
|
|
tt((#a1)abc+LPAR()#a0+RPAR()xyz) will not match tt(abcdxyz), because the
|
|
error occurs at the `tt(x)', where approximation is turned off.
|
|
|
|
Entire path segments may be matched approximately, so that
|
|
`tt((#a1)/foo/d/is/available/at/the/bar)' allows one error in any path
|
|
segment. This is much less efficient than without the tt((#a1)), however,
|
|
since every directory in the path must be scanned for a possible
|
|
approximate match. It is best to place the tt((#a1)) after any path
|
|
segments which are known to be correct.
|
|
|
|
subsect(Recursive Globbing)
|
|
cindex(recursive globbing)
|
|
cindex(globbing, recursive)
|
|
A pathname component of the form `tt(LPAR())var(foo)tt(/RPAR()#)'
|
|
matches a path consisting of zero or more directories
|
|
matching the pattern var(foo).
|
|
|
|
As a shorthand, `tt(**/)' is equivalent to `tt((*/)#)'; note that this
|
|
therefore matches files in the current directory as well as
|
|
subdirectories.
|
|
Thus:
|
|
|
|
example(ls -ld -- (*/)#bar)
|
|
|
|
or
|
|
|
|
example(ls -ld -- **/bar)
|
|
|
|
does a recursive directory search for files named `tt(bar)' (potentially
|
|
including the file `tt(bar)' in the current directory). This form does not
|
|
follow symbolic links; the alternative form `tt(***/)' 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 `tt(*)'
|
|
operators revert to their usual effect.
|
|
|
|
Even shorter forms are available when the option tt(GLOB_STAR_SHORT) is
|
|
set. In that case if no tt(/) immediately follows a tt(**) or tt(***)
|
|
they are treated as if both a tt(/) plus a further tt(*) are present.
|
|
Hence:
|
|
|
|
example(setopt GLOBSTARSHORT
|
|
ls -ld -- **.c)
|
|
|
|
is equivalent to
|
|
|
|
example(ls -ld -- **/*.c)
|
|
subsect(Glob Qualifiers)
|
|
cindex(globbing, qualifiers)
|
|
cindex(qualifiers, globbing)
|
|
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.
|
|
|
|
pindex(BARE_GLOB_QUAL, use of)
|
|
If the option tt(BARE_GLOB_QUAL) is set, then a trailing set of parentheses
|
|
containing no `tt(|)' or `tt(LPAR())' characters (or `tt(~)' 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 `tt((^x))', can be forced to be treated as part of
|
|
the glob pattern by doubling the parentheses, in this case producing
|
|
`tt(((^x)))'.
|
|
|
|
If the option tt(EXTENDED_GLOB) is set, a different syntax for glob
|
|
qualifiers is available, namely `tt(LPAR()#q)var(x)tt(RPAR())'
|
|
where var(x) 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 `tt(|)', `tt(LPAR())' or
|
|
`tt(~)' 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
|
|
the pattern, for example `tt(*(#q*)(.))' will recognise executable regular
|
|
files if both options are set; however, mixed syntax should probably be
|
|
avoided for the sake of clarity. Note that within conditions using the
|
|
`tt([[)' form the presence of a parenthesised expression
|
|
tt(LPAR()#q)var(...)tt(RPAR()) 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 tt(LPAR()#q+RPAR()). This does
|
|
not apply to the right hand side of pattern match operators as the
|
|
syntax already has special significance.
|
|
|
|
A qualifier may be any one of the following:
|
|
|
|
startitem()
|
|
item(tt(/))(
|
|
directories
|
|
)
|
|
item(tt(F))(
|
|
`full' (i.e. non-empty) directories. Note that the
|
|
opposite sense tt(LPAR()^F)tt(RPAR()) expands to empty directories
|
|
and all non-directories. Use tt(LPAR()/^F)tt(RPAR()) for
|
|
empty directories.
|
|
)
|
|
item(tt(.))(
|
|
plain files
|
|
)
|
|
item(tt(@))(
|
|
symbolic links
|
|
)
|
|
item(tt(=))(
|
|
sockets
|
|
)
|
|
item(tt(p))(
|
|
named pipes (FIFOs)
|
|
)
|
|
item(tt(*))(
|
|
executable plain files (0100 or 0010 or 0001)
|
|
)
|
|
item(tt(%))(
|
|
device files (character or block special)
|
|
)
|
|
item(tt(%b))(
|
|
block special files
|
|
)
|
|
item(tt(%c))(
|
|
character special files
|
|
)
|
|
item(tt(r))(
|
|
owner-readable files (0400)
|
|
)
|
|
item(tt(w))(
|
|
owner-writable files (0200)
|
|
)
|
|
item(tt(x))(
|
|
owner-executable files (0100)
|
|
)
|
|
item(tt(A))(
|
|
group-readable files (0040)
|
|
)
|
|
item(tt(I))(
|
|
group-writable files (0020)
|
|
)
|
|
item(tt(E))(
|
|
group-executable files (0010)
|
|
)
|
|
item(tt(R))(
|
|
world-readable files (0004)
|
|
)
|
|
item(tt(W))(
|
|
world-writable files (0002)
|
|
)
|
|
item(tt(X))(
|
|
world-executable files (0001)
|
|
)
|
|
item(tt(s))(
|
|
setuid files (04000)
|
|
)
|
|
item(tt(S))(
|
|
setgid files (02000)
|
|
)
|
|
item(tt(t))(
|
|
files with the sticky bit (01000)
|
|
)
|
|
item(tt(f)var(spec))(
|
|
files with access rights matching var(spec). This var(spec) may be a
|
|
octal number optionally preceded by a `tt(=)', a `tt(PLUS())', or a
|
|
`tt(-)'. If none of these characters is given, the behavior is the
|
|
same as for `tt(=)'. The octal number describes the mode bits to be
|
|
expected, if combined with a `tt(=)', the value given must match the
|
|
file-modes exactly, with a `tt(PLUS())', at least the bits in the
|
|
given number must be set in the file-modes, and with a `tt(-)', the
|
|
bits in the number must not be set. Giving a `tt(?)' 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 `tt(=)'.
|
|
|
|
If the qualifier `tt(f)' is followed by any other character anything
|
|
up to the next matching character (`tt([)', `tt({)', and `tt(<)' match
|
|
`tt(])', `tt(})', and `tt(>)' respectively, any other character
|
|
matches itself) is taken as a list of comma-separated
|
|
var(sub-spec)s. Each var(sub-spec) may be either an octal number as
|
|
described above or a list of any of the characters `tt(u)', `tt(g)',
|
|
`tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a
|
|
`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)',
|
|
`tt(x)', `tt(s)', and `tt(t)', or an octal digit. The first list of
|
|
characters specify which access rights are to be checked. If a `tt(u)'
|
|
is given, those for the owner of the file are used, if a `tt(g)' is
|
|
given, those of the group are checked, a `tt(o)' means to test those
|
|
of other users, and the `tt(a)' says to test all three groups. The
|
|
`tt(=)', `tt(PLUS())', and `tt(-)' 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: `tt(r)' for read access, `tt(w)' for write access,
|
|
`tt(x)' for the right to execute the file (or to search a directory),
|
|
`tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky
|
|
bit.
|
|
|
|
Thus, `tt(*(f70?))' gives the files for which the owner has read,
|
|
write, and execute permission, and for which other group members have
|
|
no rights, independent of the permissions for other users. The pattern
|
|
`tt(*(f-100))' gives all files for which the owner does not have
|
|
execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which
|
|
the owner and the other members of the group have at least write
|
|
permission, and for which other users don't have read or execute
|
|
permission.
|
|
)
|
|
xitem(tt(e)var(string))
|
|
item(tt(PLUS())var(cmd))(
|
|
The var(string) 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).
|
|
|
|
In the first form, the first character after the `tt(e)'
|
|
will be used as a separator and anything up to the next matching separator
|
|
will be taken as the var(string); `tt([)', `tt({)', and `tt(<)' match
|
|
`tt(])', `tt(})', and `tt(>)', respectively, while any other character
|
|
matches itself. Note that expansions must be quoted in the var(string)
|
|
to prevent them from being expanded before globbing is done.
|
|
var(string) is then executed as shell code. The string tt(globqual)
|
|
is appended to the array tt(zsh_eval_context) the duration of
|
|
execution.
|
|
|
|
vindex(REPLY, use of)
|
|
vindex(reply, use of)
|
|
During the execution of var(string) the filename currently being tested is
|
|
available in the parameter tt(REPLY); the parameter may be altered to
|
|
a string to be inserted into the list instead of the original
|
|
filename. In addition, the parameter tt(reply) may be set to an array or a
|
|
string, which overrides the value of tt(REPLY). If set to an array, the
|
|
latter is inserted into the command line word by word.
|
|
|
|
For example, suppose a directory contains a single file `tt(lonely)'. Then
|
|
the expression `tt(*(e:'reply=(${REPLY}{1,2})':))' will cause the words
|
|
`tt(lonely1)' and `tt(lonely2)' to be inserted into the command line. Note
|
|
the quoting of var(string).
|
|
|
|
The form tt(PLUS())var(cmd) has the same effect, but no delimiters appear
|
|
around var(cmd). Instead, var(cmd) is taken as the longest sequence of
|
|
characters following the tt(PLUS()) that are alphanumeric or underscore.
|
|
Typically var(cmd) will be the name of a shell function that contains the
|
|
appropriate test. For example,
|
|
|
|
example(nt+LPAR()RPAR() { [[ $REPLY -nt $NTREF ]] }
|
|
NTREF=reffile
|
|
ls -ld -- *(+nt))
|
|
|
|
lists all files in the directory that have been modified more recently than
|
|
tt(reffile).
|
|
)
|
|
item(tt(d)var(dev))(
|
|
files on the device var(dev)
|
|
)
|
|
item(tt(l)[tt(-)|tt(PLUS())]var(ct))(
|
|
files having a link count less than var(ct) (tt(-)), greater than
|
|
var(ct) (tt(PLUS())), or equal to var(ct)
|
|
)
|
|
item(tt(U))(
|
|
files owned by the effective user ID
|
|
)
|
|
item(tt(G))(
|
|
files owned by the effective group ID
|
|
)
|
|
item(tt(u)var(id))(
|
|
files owned by user ID var(id) if that is a number. Otherwise,
|
|
var(id) specifies a user name: the
|
|
character after the `tt(u)' will be taken as a separator and the string
|
|
between it and the next matching separator will be taken as a user name.
|
|
The starting separators `tt([)', `tt({)', and `tt(<)'
|
|
match the final separators `tt(])', `tt(})', and `tt(>)', respectively;
|
|
any other character matches itself. The selected files are those
|
|
owned by this user. For example, `tt(u:foo:)' or `tt(u[foo])' selects
|
|
files owned by user `tt(foo)'.
|
|
)
|
|
item(tt(g)var(id))(
|
|
like tt(u)var(id) but with group IDs or names
|
|
)
|
|
item(tt(a)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
|
|
files accessed exactly var(n) days ago. Files accessed within the last
|
|
var(n) days are selected using a negative value for var(n) (tt(-)var(n)).
|
|
Files accessed more than var(n) days ago are selected by a positive var(n)
|
|
value (tt(PLUS())var(n)). Optional unit specifiers `tt(M)', `tt(w)',
|
|
`tt(h)', `tt(m)' or `tt(s)' (e.g. `tt(ah5)') cause the check to be
|
|
performed with months (of 30 days), weeks, hours, minutes or seconds
|
|
instead of days, respectively. An explicit `tt(d)' for days is also
|
|
allowed.
|
|
|
|
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, `tt(echo *(ah-5))' would echo files accessed within the last
|
|
five hours, while `tt(echo *(ah+5))' would echo files accessed at least
|
|
six hours ago, as times strictly between five and six hours are treated
|
|
as five hours.
|
|
)
|
|
item(tt(m)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
|
|
like the file access qualifier, except that it uses the file modification
|
|
time.
|
|
)
|
|
item(tt(c)[tt(Mwhms)][tt(-)|tt(PLUS())]var(n))(
|
|
like the file access qualifier, except that it uses the file inode change
|
|
time.
|
|
)
|
|
item(tt(L)[tt(PLUS())|tt(-)]var(n))(
|
|
files less than var(n) bytes (tt(-)), more than var(n) bytes (tt(PLUS())), or
|
|
exactly var(n) bytes in length.
|
|
|
|
If this flag is directly followed by a em(size specifier) `tt(k)' (`tt(K)'),
|
|
`tt(m)' (`tt(M)'), or `tt(p)' (`tt(P)') (e.g. `tt(Lk-50)') the check is
|
|
performed with kilobytes, megabytes, or blocks (of 512 bytes) instead.
|
|
(On some systems additional specifiers are available for gigabytes,
|
|
`tt(g)' or `tt(G)', and terabytes, `tt(t)' or `tt(T)'.) If a size specifier
|
|
is used a file is regarded as "exactly" the size if the file size rounded up
|
|
to the next unit is equal to the test size. Hence `tt(*LPAR()Lm1+RPAR())'
|
|
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 `tt(*LPAR()Lm-1+RPAR())' only matches
|
|
files of zero size.
|
|
)
|
|
item(tt(^))(
|
|
negates all qualifiers following it
|
|
)
|
|
item(tt(-))(
|
|
toggles between making the qualifiers work on symbolic links (the
|
|
default) and the files they point to, if any; any symbolic link for
|
|
whose target the `tt(stat)' system call fails (whatever the cause of the
|
|
failure) is treated as a file in its own right
|
|
)
|
|
item(tt(M))(
|
|
sets the tt(MARK_DIRS) option for the current pattern
|
|
pindex(MARK_DIRS, setting in pattern)
|
|
)
|
|
item(tt(T))(
|
|
appends a trailing qualifier mark to the filenames, analogous to the
|
|
tt(LIST_TYPES) option, for the current pattern (overrides tt(M))
|
|
)
|
|
item(tt(N))(
|
|
sets the tt(NULL_GLOB) option for the current pattern
|
|
pindex(NULL_GLOB, setting in pattern)
|
|
)
|
|
item(tt(D))(
|
|
sets the tt(GLOB_DOTS) option for the current pattern
|
|
pindex(GLOB_DOTS, setting in pattern)
|
|
)
|
|
item(tt(n))(
|
|
sets the tt(NUMERIC_GLOB_SORT) option for the current pattern
|
|
pindex(NUMERIC_GLOB_SORT, setting in pattern)
|
|
)
|
|
item(tt(Y)var(n))(
|
|
enables short-circuit mode: the pattern will expand to at most var(n)
|
|
filenames. If more than var(n) matches exist, only the first var(n)
|
|
matches in directory traversal order will be considered.
|
|
|
|
Implies tt(oN) when no tt(o)var(c) qualifier is used.
|
|
)
|
|
item(tt(o)var(c))(
|
|
specifies how the names of the files should be sorted. The following values
|
|
of var(c) sort in the following ways:
|
|
|
|
startsitem()
|
|
sitem(tt(n))(By name.)
|
|
sitem(tt(L))(By the size (length) of the files.)
|
|
sitem(tt(l))(By number of links.)
|
|
sitem(tt(a))(By time of last access, youngest first.)
|
|
sitem(tt(m))(By time of last modification, youngest first.)
|
|
sitem(tt(c))(By time of last inode change, youngest first.)
|
|
sitem(tt(d))(By directories: files in subdirectories appear before
|
|
those in the current directory at each level of the search DASH()- this is best
|
|
combined with other criteria, for example `tt(odon)' to sort on names for
|
|
files within the same directory.)
|
|
sitem(tt(N))(No sorting is performed.)
|
|
xitem(tt(e)var(string))
|
|
sitem(tt(+)var(cmd))(Sort by shell code (see below).)
|
|
endsitem()
|
|
|
|
Note that the modifiers tt(^) and tt(-) are used,
|
|
so `tt(*(^-oL))' gives a list of all files sorted by file size in descending
|
|
order, following any symbolic links. Unless tt(oN) is used, multiple order
|
|
specifiers may occur to resolve ties.
|
|
|
|
The default sorting is tt(n) (by name) unless the tt(Y) glob qualifier is used,
|
|
in which case it is tt(N) (unsorted).
|
|
|
|
tt(oe) and tt(o+) are special cases; they are each followed by shell code,
|
|
delimited as for the tt(e) glob qualifier and the tt(+) glob qualifier
|
|
respectively (see above). The code is executed for each matched file with
|
|
the parameter tt(REPLY) set to the name of the file on entry and
|
|
tt(globsort) appended to tt(zsh_eval_context). The code
|
|
should modify the parameter tt(REPLY) in some fashion. On return, the
|
|
value of the parameter is used instead of the file name as the string on
|
|
which to sort. Unlike other sort operators, tt(oe) and tt(o+) may be
|
|
repeated, but note that the maximum number of sort operators of any kind
|
|
that may appear in any glob expression is 12.
|
|
)
|
|
item(tt(O)var(c))(
|
|
like `tt(o)', but sorts in descending order; i.e. `tt(*+LPAR()^o)var(c)tt(+RPAR())' is the
|
|
same as `tt(*+LPAR()O)var(c)tt(+RPAR())' and `tt(*+LPAR()^O)var(c)tt(+RPAR())' is the same as `tt(*+LPAR()o)var(c)tt(+RPAR())'; `tt(Od)'
|
|
puts files in the current directory before those in subdirectories at each
|
|
level of the search.
|
|
)
|
|
item(tt([)var(beg)[tt(,)var(end)]tt(]))(
|
|
specifies which of the matched filenames should be included in the
|
|
returned list. The syntax is the same as for array
|
|
subscripts. var(beg) and the optional var(end) may be mathematical
|
|
expressions. As in parameter subscripting they may be negative to make
|
|
them count from the last match backward. E.g.: `tt(*(-OL[1,3]))'
|
|
gives a list of the names of the three largest files.
|
|
)
|
|
item(tt(P)var(string))(
|
|
The var(string) will be prepended to each glob match as a separate
|
|
word. var(string) is delimited in the same way as arguments to the
|
|
tt(e) glob qualifier described above. The qualifier can be repeated;
|
|
the words are prepended separately so that the resulting command
|
|
line contains the words in the same order they were given in the
|
|
list of glob qualifiers.
|
|
|
|
A typical use for this is to prepend an option before all occurrences
|
|
of a file name; for example, the pattern `tt(*(P:-f:))' produces the
|
|
command line arguments `tt(-f) var(file1) tt(-f) var(file2) ...'
|
|
|
|
If the modifier tt(^) is active, then var(string) 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
|
|
`tt(*(P:foo:^P:bar:^P:baz:))' which produces the command line arguments
|
|
`tt(foo) tt(baz) var(file1) tt(bar) ...'
|
|
)
|
|
enditem()
|
|
|
|
Multiple consecutive qualifiers are joined into a list by implicit logical AND.
|
|
More than one of these lists can be combined using comma `tt(,)' as logical OR.
|
|
The whole list matches if at least one of the sublists matches.
|
|
Some qualifiers,
|
|
however, affect all matches generated, independent of the sublist in
|
|
which they are given. These are the qualifiers `tt(M)', `tt(T)',
|
|
`tt(N)', `tt(D)', `tt(n)', `tt(o)', `tt(O)' and the subscripts given
|
|
in brackets (`tt([)var(...)tt(])').
|
|
|
|
If a `tt(:)' appears in a qualifier list, the remainder of the expression in
|
|
parenthesis is interpreted as a modifier (see noderef(Modifiers)
|
|
in noderef(History Expansion)). Each modifier must be introduced by a
|
|
separate `tt(:)'. 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 `tt(LPAR():)var(...)tt(RPAR())'
|
|
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 tt(NULL_GLOB). Thus:
|
|
|
|
example(ls -ld -- *(-/))
|
|
|
|
lists all directories and symbolic links that point to directories,
|
|
and
|
|
|
|
example(ls -ld -- *(-@))
|
|
|
|
lists all broken symbolic links, and
|
|
|
|
example(ls -ld -- *(%W))
|
|
|
|
lists all world-writable device files in the current directory, and
|
|
|
|
example(ls -ld -- *(W,X))
|
|
|
|
lists all files in the current directory that are
|
|
world-writable or world-executable, and
|
|
|
|
example(print -rC1 /tmp/foo*(u0^@:t))
|
|
|
|
outputs the basename of all root-owned files beginning with the string
|
|
`tt(foo)' in tt(/tmp), ignoring symlinks, and
|
|
|
|
example(ls -ld -- *.*~(lex|parse).[ch](^D^l1))
|
|
|
|
lists all files having a link count of one whose names contain a dot
|
|
(but not those starting with a dot, since tt(GLOB_DOTS) is explicitly
|
|
switched off) except for tt(lex.c), tt(lex.h), tt(parse.c) and tt(parse.h).
|
|
|
|
example(print -rC1 b*.pro+LPAR()#q:s/pro/shmo/+RPAR()(#q.:s/builtin/shmiltin/))
|
|
|
|
demonstrates how colon modifiers and other qualifiers may be chained
|
|
together. The ordinary qualifier `tt(.)' is applied first, then the colon
|
|
modifiers in order from left to right. So if tt(EXTENDED_GLOB) is set and
|
|
the base pattern matches the regular file tt(builtin.pro), the shell will
|
|
print `tt(shmiltin.shmo)'.
|