zsh: Modifiers

Previous: Word Designators, Up: History Expansion [Contents][Index]

#### 14.1.4 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, and resolves any use of ‘`..`’ and ‘`.`’ in the path. Note that the transformation takes place even if the file or any intervening directories do not exist.

`A`

  As ‘`a`’, but also resolve use of symbolic links where possible. Note that resolution of ‘`..`’ occurs before resolution of symbolic links. This call is equivalent to `a` unless your system has the `realpath` system call (modern systems do).

`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`

  Remove a trailing pathname component, leaving the head. This works like ‘`dirname`’.

`l`

  Convert the words to all lowercase.

`p`

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

`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`

  Remove all leading pathname components, leaving the tail. This works like ‘`basename`’.

`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 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 `(#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 *.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.

Previous: Word Designators, Up: History Expansion [Contents][Index]