Linux cli command zshexpn

NAME 🖥️ zshexpn 🖥️

zsh expansion and substitution

DESCRIPTION

The following types of expansions are performed in the indicated order in five steps:

History Expansion This is performed only in interactive shells.

Alias Expansion
Aliases are expanded immediately before the command line is parsed as explained under Aliasing in zshmisc(1).

Process Substitution

Parameter Expansion

Command Substitution

Arithmetic Expansion

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 `**’,`’’ and `"**’ are removed.

Filename Expansion
If the SH_FILE_EXPANSION option is set, the order of expansion is modified for compatibility with sh and ksh. In that case filename expansion is performed immediately after alias expansion, preceding the set of five expansions mentioned above.

Filename Generation
This expansion, commonly referred to as globbing, is always done last.

The following sections explain the types of expansion in detail.

HISTORY EXPANSION

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.

Immediately before execution, each command is saved in the history list, the size of which is controlled by the HISTSIZE parameter. The one most recent command is always retained in any case. Each saved command in the history list is called a history 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 EXPANSION OF PROMPT SEQUENCES in zshmisc(1)) is the number that is to be assigned to the next command.

Overview

A history expansion begins with the first character of the histchars parameter, which is `!’ by default, and may occur anywhere on the command line, including inside double quotes (but not inside single quotes ’…’ or C-style quotes $’…’ nor when escaped with a backslash).

The first character is followed by an optional event designator (see the section `Event Designators’) and then an optional word designator (the section `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. However, if the option CSH_JUNKIE_HISTORY is set, then every history reference with no event specification always refers to the previous command.

For example, `!’ is the event designator for the previous command, so `!!:1’ always refers to the first word of the previous command, and `!!$’ always refers to the last word of the previous command. With CSH_JUNKIE_HISTORY set, then `!:1’ and `!$’ function in the same manner as `!!:1’ and `!!$’, respectively. Conversely, if CSH_JUNKIE_HISTORY is unset, then `!:1’ and `!$’ refer to the first and last words, respectively, of the same event referenced by the nearest other history reference preceding them on the current command line, or to the previous command if there is no preceding reference.

The character sequence `^foo^bar’ (where `^’ is actually the second character of the histchars parameter) repeats the last command, replacing the string foo with bar. More precisely, the sequence `^foo^bar^’ is synonymous with `!!:s^foo^bar^’, hence other modifiers (see the section `Modifiers’) may follow the final `^’. In particular, `^foo^bar^:G’ performs a global substitution.

If the shell encounters the character sequence `!"’ in the input, the history mechanism is temporarily disabled until the current list (see zshmisc(1)) is fully parsed. The `!"’ is removed from the input, and any subsequent `!’ characters have no special significance.

A less convenient but more comprehensible form of command history support is provided by the fc builtin.

Event Designators

An event designator is a reference to a command-line entry in the history list. In the list below, remember that the initial `!’ in each item may be changed to another character by setting the histchars parameter.

! Start a history expansion, except when followed by a blank, newline, `=’ or `(’. If followed immediately by a word designator (see the section `Word Designators’), this forms a history reference with no event designator (see the section `Overview’).

!!
Refer to the previous command. By itself, this expansion repeats the previous command.

**!**n
Refer to command-line n.

**!-**n
Refer to the current command-line minus n.

**!**str
Refer to the most recent command starting with str.

!?str[?]
Refer to the most recent command containing str. The trailing `?’ is necessary if this reference is to be followed by a modifier or followed by any text that is not to be considered part of str.

!#
Refer to the current command line typed in so far. The line is treated as if it were complete up to and including the word before the one with the `!#’ reference.

!{…}
Insulate a history reference from adjacent characters (if necessary).

Word Designators

A word designator indicates which word or words of a given command line are to be included in a history reference. A `:’ usually separates the event specification from the word designator. It may be omitted only if the word designator begins with a `^’, `$’, `*’, `-’ or `%’. Word designators include:

0
The first input word (command).

n
The nth argument.

^
The first argument. That is, 1.

$
The last argument.

%
The word matched by (the most recent) **?**str search.

x**-**y
A range of words; x defaults to 0.

*
All the arguments, or a null value if there are none.

x*****
Abbreviates `x**-$**'.

x**-**
Like `x*****’ but omitting word $.

Note that a `%’ word designator works only when used in one of `!%’, `!:%’ or `!?str?:%’, and only when used after a !? expansion (possibly in an earlier command). Anything else results in an error, although the error may not be the most obvious one.

Modifiers

After the optional word designator, you can add a sequence of one or more of the following modifiers, each preceded by a `:’. These modifiers also work on the result of filename generation and parameter expansion, except where noted.

a Turn a file name into an absolute path: prepends the current directory, if necessary; remove `.’ path segments; and remove `..’ path segments and the segments that immediately precede them.

This transformation is agnostic about what is in the filesystem, i.e. is on the logical, not the physical directory. It takes place in the same manner as when changing directories when neither of the options CHASE_DOTS or CHASE_LINKS is set. For example, `/before/here/../after’ is always transformed to `/before/after’, regardless of whether `/before/here’ exists or what kind of object (dir, file, symlink, etc.) it is.

A
Turn a file name into an absolute path as the `a’ modifier does, and then pass the result through the realpath(3) library function to resolve symbolic links.

Note: on systems that do not have a realpath(3) library function, symbolic links are not resolved, so on those systems `a’ and `A’ are equivalent.

Note: foo:A and realpath(foo) are different on some inputs. For realpath(foo) semantics, see the `P` modifier.

c
Resolve a command name into an absolute path by searching the command path given by the PATH variable. This does not work for commands containing directory parts. Note also that this does not usually work as a glob qualifier unless a file of the same name is found in the current directory.

e
Remove all but the part of the filename extension following the `.’; see the definition of the filename extension in the description of the r modifier below. Note that according to that definition the result will be empty if the string ends with a `.'.

h [ digits ]
Remove a trailing pathname component, shortening the path by one directory level: this is the `head’ of the pathname. This works like `dirname’. If the h is followed immediately (with no spaces or other separator) by any number of decimal digits, and the value of the resulting number is non-zero, that number of leading components is preserved instead of the final component being removed. In an absolute path the leading `/’ is the first component, so, for example, if var=/my/path/to/something, then ${var:h3} substitutes /my/path. Consecutive `/’s are treated the same as a single `/’. In parameter substitution, digits may only be used if the expression is in braces, so for example the short form substitution $var:h2 is treated as ${var:h}2, not as ${var:h2}. No restriction applies to the use of digits in history substitution or globbing qualifiers. If more components are requested than are present, the entire path is substituted (so this does not trigger a `failed modifier’ error in history expansion).

l
Convert the words to all lowercase.

p
Print the new command but do not execute it. Only works with history expansion.

P
Turn a file name into an absolute path, like realpath(3). The resulting path will be absolute, will refer to the same directory entry as the input filename, and none of its components will be symbolic links or equal to `.’ or `..'.

Unlike realpath(3), non-existent trailing components are permitted and preserved.

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 eval.

Q
Remove one level of quotes from the substituted words.

r
Remove a filename extension leaving the root name. Strings with no filename extension are not altered. A filename extension is a `.’ followed by any number of characters (including zero) that are neither `.’ nor `/’ and that continue to the end of the string. For example, the extension of `foo.orig.c’ is `.c’, and `dir.c/foo’ has no extension.

s/l/r[/]
Substitute r for l as described below. The substitution is done only for the first string that matches 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 `**gs/l/**r’ and `s/l/r/:G’ perform global substitution, i.e. substitute every occurrence of r for l. Note that the g or :G must appear in exactly the position shown.

See further notes on this form of substitution below.

&
Repeat the previous s substitution. Like s, may be preceded immediately by a g. In parameter expansion the & must appear inside braces, and in filename generation it must be quoted with a backslash.

t [ digits ]
Remove all leading pathname components, leaving the final component (tail). This works like `basename’. Any trailing slashes are first removed. Decimal digits are handled as described above for (h), but in this case that number of trailing components is preserved instead of the default 1; 0 is treated the same as 1.

u
Convert the words to all uppercase.

x
Like q, but break into words at whitespace. Does not work with parameter expansion.

The s/l/r/ substitution works as follows. By default the left-hand side of substitutions are not patterns, but character strings. Any character can be used as the delimiter in place of `/’. A backslash quotes the delimiter character. The character `&’, in the right-hand-side r, is replaced by the text from the left-hand-side l. The `&’ can be quoted with a backslash. A null l uses the previous string either from the previous l or from the contextual scan string s from `!?s’. You can omit the rightmost delimiter if a newline immediately follows r; the rightmost `?’ in a context scan can similarly be omitted. Note the same record of the last l and r is maintained across all forms of expansion.

Note that if a `&’ is used within glob qualifiers an extra backslash is needed as a & is a special character in this case.

Also note that the order of expansions affects the interpretation of l and r. When used in a history expansion, which occurs before any other expansions, l and r are treated as literal strings (except as explained for HIST_SUBST_PATTERN below). When used in parameter expansion, the replacement of 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 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 `:s’ expression itself is divided into l and r sides.

If the option HIST_SUBST_PATTERN is set, l is treated as a pattern of the usual form described in the section FILENAME GENERATION below. This can be used in all the places where modifiers are available; note, however, that in globbing qualifiers parameter substitution has already taken place, so parameters in the replacement string should be quoted to ensure they are replaced at the correct time. Note also that complicated patterns used in globbing qualifiers may need the extended glob qualifier notation (#q:s/…/…/) in order for the shell to recognize the expression as a glob qualifier. Further, note that bad patterns in the substitution are not subject to the NO_BAD_PATTERN option so will cause an error.

When HIST_SUBST_PATTERN is set, l may start with a # to indicate that the pattern must match at the start of the string to be substituted, and a % may appear at the start or after an # to indicate that the pattern must match at the end of the string to be substituted. The % or # may be quoted with two backslashes.

For example, the following piece of filename generation code with the EXTENDED_GLOB option:

print -r – .c(#q:s/#%(#b)s().c/‘S${match[1]}.C’/)

takes the expansion of *.c and applies the glob qualifiers in the (#q*…) expression, which consists of a substitution modifier anchored to the start and end of each word (#%). This turns on backreferences ((#b)*), so that the parenthesised subexpression is available in the replacement string as ${match[1]}. The replacement string is quoted so that the parameter is not substituted before the start of filename generation.

The following f, F, w and W modifiers work only with parameter expansion and filename generation. They are listed here to provide a single point of reference for all modifiers.

f Repeats the immediately (without a colon) following modifier until the resulting word doesn’t change any more.

F:expr:
Like f, but repeats only n times if the expression expr evaluates to n. Any character can be used instead of the `:’; if `(’, `[’, or `{’ is used as the opening delimiter, the closing delimiter should be ‘)’, `]’, or `}’, respectively.

w
Makes the immediately following modifier work on each word in the string.

W:sep:
Like w but words are considered to be the parts of the string that are separated by sep. Any character can be used instead of the `:’; opening parentheses are handled specially, see above.

PROCESS SUBSTITUTION

Each part of a command argument that takes the form `<(list)’, `>(list)’ or `=(list)’ 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 `<<(list)’ is not a special syntax; it is equivalent to `< <(list)’, 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 < or > forms, the shell runs the commands in list as a subprocess of the job executing the shell command line. If the system supports the /dev/fd mechanism, the command argument is the name of the device file corresponding to a file descriptor; otherwise, if the system supports named pipes (FIFOs), the command argument will be a named pipe. If the form with > is selected then writing on this special file will provide input for list. If < is used, then the file passed as an argument will be connected to the output of the list process. For example,

paste <(cut -f1 file1) <(cut -f3 file2) | tee >(process1) >(process2) >/dev/null

cuts fields 1 and 3 from the files file1 and file2 respectively, pastes the results together, and sends it to the processes process1 and process2**.**

If =(…) is used instead of <(…), then the file passed as an argument will be the name of a temporary file containing the output of the list process. This may be used instead of the < form for a program that expects to lseek (see lseek**(2))** on the input file.

There is an optimisation for substitutions of the form =(<<<arg), where arg is a single-word argument to the here-string redirection <<<. This form produces a file name containing the value of arg after any substitutions have been performed. This is handled entirely within the current shell. This is effectively the reverse of the special form $(<arg) which treats arg as a file name and replaces it with the file’s contents.

The = form is useful as both the /dev/fd and the named pipe implementation of <(…) have drawbacks. In the former case, some programmes may automatically close the file descriptor in question before examining the file on the command line, particularly if this is necessary for security reasons such as when the programme is running setuid. In the second case, if the programme does not actually open the file, the subshell attempting to read from or write to the pipe will (in a typical implementation, different operating systems may have different behaviour) block for ever and have to be killed explicitly. In both cases, the shell actually supplies the information using a pipe, so that programmes that expect to lseek (see lseek**(2)) on the file will not work.**

Also note that the previous example can be more compactly and efficiently written (provided the MULTIOS option is set) as:

paste <(cut -f1 file1) <(cut -f3 file2) > >(process1) > >(process2)

The shell uses pipes instead of FIFOs to implement the latter two process substitutions in the above example.

There is an additional problem with >(process); when this is attached to an external command, the parent shell does not wait for 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 MULTIOS in zshmisc**(1). Hence in a simplified** version of the example above:

paste <(cut -f1 file1) <(cut -f3 file2) > >(process)

(note that no MULTIOS are involved), process will be run asynchronously as far as the parent shell is concerned. The workaround is:

{ paste <(cut -f1 file1) <(cut -f3 file2) } > >(process)

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 `&!’ or `&|’ appears at the end of a command containing a substitution. In that case the temporary file will not be cleaned up as the shell no longer has any memory of the job. A workaround is to use a subshell, for example,

(mycmd =(myoutput)) &!

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:

() { print File $1: cat $1 } =(print This be the verse)

outputs something resembling the following

File /tmp/zsh6nU0kS: This be the verse

The temporary file created by the process substitution will be deleted when the function exits.

PARAMETER EXPANSION

The character `$’ is used to introduce parameter expansions. See zshparam**(1)** 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 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:

array=(“first word” "" “third word”) scalar=“only word”

then $array substitutes two words, `first word’ and `third word**’, and $scalar substitutes a single word `only word’. Note** that second element of array was elided. Scalar parameters can be elided too if their value is null (empty). To avoid elision, use quoting as follows: "$scalar" for scalars and “${array[@]}” or “${(@)array}” for arrays. (The last two forms are equivalent.)

Parameter expansions can involve flags**, as in `${(@kv)aliases}’,** and other operators, such as `${PREFIX:-"/usr/local"}’. Parameter expansions can also be nested. These topics will be introduced below. The full rules are complicated and are noted at the end.

In the expansions discussed below that require a pattern, the form of the pattern is the same as that used for filename generation; see the section `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 the section `Modifiers’ in the section `History Expansion’ can be applied: for example, ${i:s/foo/bar/} performs string substitution on the expansion of parameter $i.

In the following descriptions, `word**’ refers to a single word** substituted on the command line, not necessarily a space delimited word.

${name} The value, if any, of the parameter 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 name**. In addition, more complicated forms of substitution** usually require the braces to be present; exceptions, which only apply if the option KSH_ARRAYS is not set, are a single subscript or any colon modifiers appearing after the name, or any of the characters `^’, `=’, `~’, `#’ or `+’ appearing before the name, all of which work with or without braces.

If name is an array parameter, and the KSH_ARRAYS option is not set, then the value of each element of name is substituted, one element per word. Otherwise, the expansion results in one word only; with KSH_ARRAYS, this is the first element of an array. No field splitting is done on the result unless the SH_WORD_SPLIT option is set. See also the flags = and s:string:.

${+name}
If name is the name of a set parameter `1’ is substituted, otherwise `0’ is substituted.

${name-word}

${name:-word} If name is set, or in the second form is non-null, then substitute its value; otherwise substitute word**. In the second form** name may be omitted, in which case word is always substituted.

${name+word}

${name:+word} If name is set, or in the second form is non-null, then substitute word**; otherwise substitute nothing.**

${name=word}

${name:=word}

${name::=word} In the first form, if name is unset then set it to word**; in the** second form, if name is unset or null then set it to word**; and** in the third form, unconditionally set name to word**. In all** forms, the value of the parameter is then substituted.

${name?word}

${name:?word} In the first form, if name is set, or in the second form if name is both set and non-null, then substitute its value; otherwise, print word and exit from the shell. Interactive shells instead return to the prompt. If word is omitted, then a standard message is printed.

In any of the above expressions that test a variable and substitute an alternate word**, note that you can use standard shell quoting in the** word value to selectively override the splitting done by the SH_WORD_SPLIT option and the = flag, but not splitting by the s:string: flag.

In the following expressions, when name is an array and the substitution is not quoted, or if the `(@)’ flag or the name**[@] syntax is used, matching and replacement is** performed on each array element separately.

${name#pattern}

${name##pattern} If the pattern matches the beginning of the value of name**, then substitute the value of** name with the matched portion deleted; otherwise, just substitute the value of name**. In the first** form, the smallest matching pattern is preferred; in the second form, the largest matching pattern is preferred.

${name%pattern}

${name%%pattern} If the pattern matches the end of the value of name**, then substitute the value of** name with the matched portion deleted; otherwise, just substitute the value of name**. In the first** form, the smallest matching pattern is preferred; in the second form, the largest matching pattern is preferred.

${name:#pattern}
If the pattern matches the value of name**, then substitute** the empty string; otherwise, just substitute the value of name**.** If name is an array the matching array elements are removed (use the `(M)’ flag to remove the non-matched elements).

${name:|arrayname}
If arrayname is the name (N.B., not contents) of an array variable, then any elements contained in arrayname are removed from the substitution of name**. If the substitution is scalar,** either because name is a scalar variable or the expression is quoted, the elements of arrayname are instead tested against the entire expression.

${name:*arrayname}
Similar to the preceding substitution, but in the opposite sense, so that entries present in both the original substitution and as elements of arrayname are retained and others removed.

${name:^arrayname}

${name:^^arrayname} Zips two arrays, such that the output array is twice as long as the shortest (longest for `:^^’) of name and arrayname, with the elements alternatingly being picked from them. For `:^’, if one of the input arrays is longer, the output will stop when the end of the shorter array is reached. Thus,

a=(1 2 3 4); b=(a b); print ${a:^b}

will output `1 a 2 b’. For `:^^’, then the input is repeated until all of the longer array has been used up and the above will output `1 a 2 b 3 a 4 b’.

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 `a b’ and `1’ as two separate elements, which can be unexpected. The second print provides a workaround which should continue to work if this is changed.

a=(a b); b=(1 2); print -l “${a:^b}”; print -l “${${a:^b}}”

${name:offset}

${name:offset:length} This syntax gives effects similar to parameter subscripting in the form $name[start,end], but is compatible with other shells; note that both offset and length are interpreted differently from the components of a subscript.

If offset is non-negative, then if the variable name is a scalar substitute the contents starting offset characters from the first character of the string, and if name is an array substitute elements starting offset elements from the first element. If length is given, substitute that many characters or elements, otherwise the entire rest of the scalar or array.

A positive offset is always treated as the offset of a character or element in 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 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, length counts from the offset position toward the end of the scalar or array. When negative, length counts back from the end. If this results in a position smaller than offset**, a diagnostic is printed and nothing is substituted.**

The option MULTIBYTE is obeyed, i.e. the offset and length count multibyte characters where appropriate.

offset and length undergo the same set of shell substitutions as for scalar assignment; in addition, they are then subject to arithmetic evaluation. Hence, for 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 $foo if the substitution would otherwise return a scalar, or the array starting at the fourth element if $foo would return an array. Note that with the option KSH_ARRAYS $foo always returns a scalar (regardless of the use of the offset syntax) and a form such as ${foo[*]:3} is required to extract elements of an array named foo.

If offset is negative, the - may not appear immediately after the : as this indicates the ${name:-word} form of substitution. Instead, a space may be inserted before the -. Furthermore, neither offset nor length may begin with an alphabetic character or & as these are used to indicate history-style modifiers. To substitute a value from a variable, the recommended approach is to precede it with a $ as this signifies the intention (parameter substitution can easily be rendered unreadable); however, as arithmetic substitution is performed, the expression ${var: offs} does work, retrieving the offset from $offs.

For further compatibility with other shells there is a special case for array offset 0. This usually accesses the first element of the array. However, if the substitution refers to the positional parameter array, e.g. $@ or $*, then offset 0 instead refers to $0, offset 1 refers to $1, and so on. In other words, the positional parameter array is effectively extended by prepending $0. Hence ${*:0:1} substitutes $0 and ${*:1:1} substitutes $1.

${name/pattern/repl}

${name//pattern/repl}

${name:/pattern/repl} Replace the longest possible match of pattern in the expansion of parameter name by string repl**. The first form** replaces just the first occurrence, the second form all occurrences, and the third form replaces only if pattern matches the entire string. Both pattern and repl are subject to double-quoted substitution, so that expressions like ${name/$opat/$npat} will work, but obey the usual rule that pattern characters in $opat are not treated specially unless either the option GLOB_SUBST is set, or $opat is instead substituted as ${~opat}.

The pattern may begin with a `#’, in which case the pattern must match at the start of the string, or `%’, in which case it must match at the end of the string, or `#%’ in which case the pattern must match the entire string. The repl may be an empty string, in which case the final `/’ may also be omitted. To quote the final `/’ in other cases it should be preceded by a single backslash; this is not necessary if the `/’ occurs inside a substituted parameter. Note also that the `#’, `%’ and `#% are not active if they occur inside a substituted parameter, even at the start.

If, after quoting rules apply, ${name} expands to an array, the replacements act on each element individually. Note also the effect of the I and S parameter expansion flags below; however, the flags M, R, B, E and N are not useful.

For example,

foo=“twinkle twinkle little star” sub=“t*e” rep=“spy” print ${foo//${~sub}/$rep} print ${(S)foo//${~sub}/$rep}

Here, the `~’ ensures that the text of $sub is treated as a pattern rather than a plain string. In the first case, the longest match for t*e is substituted and the result is `spy star’, while in the second case, the shortest matches are taken and the result is `spy spy lispy star’.

${#spec}
If spec is one of the above substitutions, substitute the length in characters of the result instead of the result itself. If 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 spec**.** Note that `^’, `=’, and `~’, below, must appear to the left of `#’ when these forms are combined.

If the option POSIX_IDENTIFIERS is not set, and spec is a simple name, then the braces are optional; this is true even for special parameters so e.g. $#- and $#* take the length of the string $- and the array $* respectively. If POSIX_IDENTIFIERS is set, then braces are required for the # to be treated in this fashion.

${^spec}

${^^spec} Turn on the RC_EXPAND_PARAM option for the evaluation of spec**; if the `^’ is doubled, turn it off.** When this option is set, array expansions of the form foo**${xx}bar,** where the parameter xx is set to (a b c), are substituted with `fooabar foobbar foocbar**’ instead of the default** `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., ${^var} becomes {$var[1],$var[2],…}, and is processed as described in the section `Brace Expansion’ below: note, however, the expansion happens immediately, with any explicit brace expansion happening later. If word splitting is also in effect the $var[N] may themselves be split into different list elements.

${=spec}

${==spec} Perform word splitting using the rules for SH_WORD_SPLIT during the evaluation of spec**, but regardless of whether the parameter appears in** double quotes; if the `=’ is doubled, turn it off. This forces parameter expansions to be split into separate words before substitution, using IFS as a delimiter. This is done by default in most other shells.

Note that splitting is applied to word in the assignment forms of spec before the assignment to name is performed. This affects the result of array assignments with the A flag.

${~spec}

${~~spec} Turn on the GLOB_SUBST option for the evaluation of spec**; if the `~’ is doubled, turn it off. When this option is** set, the string resulting from the expansion will be interpreted as a pattern anywhere that is possible, such as in filename expansion and filename generation and pattern-matching contexts like the right hand side of the `=’ and `!=’ operators in conditions.

In nested substitutions, note that the effect of the ~ applies to the result of the current level of substitution. A surrounding pattern operation on the result may cancel it. Hence, for example, if the parameter foo is set to *, ${~foo///*.c} is substituted by the pattern *.c, which may be expanded by filename generation, but ${${~foo}///*.c} substitutes to the string *.c, which will not be further expanded.

If a ${…} type parameter expression or a $(…) type command substitution is used in place of name above, it is expanded first and the result is used as if it were the value of name**. Thus it is** possible to perform nested operations: ${${foo#head}%tail} substitutes the value of $foo with both `head’ and `tail’ deleted. The form with $(…) is often useful in combination with the flags described next; see the examples below. Each name or nested ${…} in a parameter expansion may also be followed by a subscript expression as described in Array Parameters in zshparam**(1).**

Note that double quotes may appear around nested expressions, in which case only the part inside is treated as quoted; for example, ${(f)"$(foo)"} quotes the result of $(foo), but the flag `(f)’ (see below) is applied using the rules for unquoted expansions. Note further that quotes are themselves nested in this context; for example, in "${(@f)"$(foo)"}", there are two sets of quotes, one surrounding the whole expression, the other (redundant) surrounding the $(foo) as before.

Parameter Expansion 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, `(q%q%q)’ means the same thing as the more readable `(%%qqq)’. The following flags are supported:

# Evaluate the resulting words as numeric expressions and interpret these as character codes. Output the corresponding characters. Note that this form is entirely distinct from use of the # without parentheses.

If the MULTIBYTE option is set and the number is greater than 127 (i.e. not an ASCII character) it is treated as a Unicode character.

%
Expand all % escapes in the resulting words in the same way as in prompts (see EXPANSION OF PROMPT SEQUENCES in zshmisc**(1)). If this flag is given twice,** full prompt expansion is done on the resulting words, depending on the setting of the PROMPT_PERCENT, PROMPT_SUBST and PROMPT_BANG options.

@
In double quotes, array elements are put into separate words. E.g., `"${(@)foo}"’ is equivalent to `"${foo[@]}"’ and `"${(@)foo[1,2]}"’ is the same as `"$foo[1]" “$foo[2]”’. This is distinct from field splitting by the f, s or z flags, which still applies within each array element.

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 ${${(A)name}[1]} yields the full value of name when name is scalar.

This assigns an array parameter with `${…=…}’, `${…:=…}’ or `${…::=…}’. If this flag is repeated (as in `AA’), assigns an associative array parameter. Assignment is made before sorting or padding; if field splitting is active, the word part is split before assignment. The name part may be a subscripted range for ordinary arrays; when assigning an associative array, the word part must be converted to an array, for example by using `${(AA)=name=…}’ 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.

a
Sort in array index order; when combined with `O’ sort in reverse array index order. Note that `a’ is therefore equivalent to the default but `Oa’ is useful for obtaining an array’s elements in reverse order.

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 GLOB_SUBST, including the ${~…} switch.

Quoting using one of the q family of flags does not work for this purpose since quotes are not stripped from non-pattern characters by GLOB_SUBST. In other words,

pattern=${(q)str} [[ $str = ${~pattern} ]]

works if $str is `a*b’ but not if it is `a b’, whereas

pattern=${(b)str} [[ $str = ${~pattern} ]]

is always true for any possible value of $str.

c
With ${#name}, 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.

C
Capitalize the resulting words. `Words’ in this case refers to sequences of alphanumeric characters separated by non-alphanumerics, not to words that result from field splitting.

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 `~’ substitution: see the section FILENAME EXPANSION below.

e
Perform single word shell expansions, namely parameter expansion**,** command substitution and arithmetic expansion**, on the** result. Such expansions can be nested but too deep recursion may have unpredictable effects.

f
Split the result of the expansion at newlines. This is a shorthand for `ps: :’.

F
Join the words of arrays together using newline as a separator. This is a shorthand for `pj: :’.

g:opts:
Process escape sequences like the echo builtin when no options are given (g::). With the o option, octal escapes don’t take a leading zero. With the c option, sequences like `^X’ are also processed. With the e option, processes `\M-t’ and similar sequences like the print builtin. With both of the o and e options, behaves like the print builtin except that in none of these modes is `**