22.38 The zsh/zutil Module

The zsh/zutil module only adds some builtins:

zstyle [ -L [ metapattern [ style ] ] ]
zstyle [ -e | - | -- ] pattern style string ...
zstyle -d [ pattern [ style ... ] ]
zstyle -g name [ pattern [ style ] ]
zstyle -{a|b|s} context style name [ sep ]
zstyle -{T|t} context style [ string ... ]
zstyle -m context style pattern

This builtin command is used to define and lookup styles. Styles are pairs of names and values, where the values consist of any number of strings. They are stored together with patterns and lookup is done by giving a string, called the ‘context’, which is matched against the patterns. The definition stored for the most specific pattern that matches will be returned.

A pattern is considered to be more specific than another if it contains more components (substrings separated by colons) or if the patterns for the components are more specific, where simple strings are considered to be more specific than patterns and complex patterns are considered to be more specific than the pattern ‘*’. A ‘*’ in the pattern will match zero or more characters in the context; colons are not treated specially in this regard. If two patterns are equally specific, the tie is broken in favour of the pattern that was defined first.

Example

For example, a fictional ‘weather’ plugin might state in its documentation that it looks up the preferred-precipitation style under the ‘:weather:continent:day-of-the-week:phase-of-the-moon’ context. According to this, you might set the following in your zshrc:

zstyle ':weather:europe:*' preferred-precipitation rain
zstyle ':weather:*:Sunday:*' preferred-precipitation snow

Then the plugin would run under the hood a command such as

zstyle -s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred-precipitation REPLY

in order to retrieve your preference into the scalar variable $REPLY. On Sundays $REPLY would be set to ‘snow’; in Europe it would be set to ‘rain’; and on Sundays in Europe it would be set to ‘snow’ again, because the patterns ‘:weather:europe:*’ and ‘:weather:*:Sunday:*’ both match the context argument to zstyle -s, are equally specific, and the latter is more specific (because it has more colon-separated components).

Usage

The forms that operate on patterns are the following.

zstyle [ -L [ metapattern [ style ] ] ]

Without arguments, lists style definitions. Styles are shown in alphabetic order and patterns are shown in the order zstyle will test them.

If the -L option is given, listing is done in the form of calls to zstyle. The optional first argument, metapattern, is a pattern which will be matched against the string supplied as pattern when the style was defined. Note: this means, for example, ‘zstyle -L ":completion:*"’ will match any supplied pattern beginning ‘:completion:’, not just ":completion:*": use ':completion:\*' to match that. The optional second argument limits the output to a specific style (not a pattern). -L is not compatible with any other options.

zstyle [ - | -- | -e ] pattern style string ...

Defines the given style for the pattern with the strings as the value. If the -e option is given, the strings will be concatenated (separated by spaces) and the resulting string will be evaluated (in the same way as it is done by the eval builtin command) when the style is looked up. In this case the parameter ‘reply’ must be assigned to set the strings returned after the evaluation. Before evaluating the value, reply is unset, and if it is still unset after the evaluation, the style is treated as if it were not set.

zstyle -d [ pattern [ style ... ] ]

Delete style definitions. Without arguments all definitions are deleted, with a pattern all definitions for that pattern are deleted and if any styles are given, then only those styles are deleted for the pattern.

zstyle -g name [ pattern [ style ] ]

Retrieve a style definition. The name is used as the name of an array in which the results are stored. Without any further arguments, all patterns defined are returned. With a pattern the styles defined for that pattern are returned and with both a pattern and a style, the value strings of that combination is returned.

The other forms can be used to look up or test styles for a given context.

zstyle -s context style name [ sep ]

The parameter name is set to the value of the style interpreted as a string. If the value contains several strings they are concatenated with spaces (or with the sep string if that is given) between them.

Return 0 if the style is set, 1 otherwise.

zstyle -b context style name

The value is stored in name as a boolean, i.e. as the string ‘yes’ if the value has only one string and that string is equal to one of ‘yes’, ‘true’, ‘on’, or ‘1’. If the value is any other string or has more than one string, the parameter is set to ‘no’.

Return 0 if name is set to ‘yes’, 1 otherwise.

zstyle -a context style name

The value is stored in name as an array. If name is declared as an associative array, the first, third, etc. strings are used as the keys and the other strings are used as the values.

Return 0 if the style is set, 1 otherwise.

zstyle -t context style [ string ... ]
zstyle -T context style [ string ... ]

Test the value of a style, i.e. the -t option only returns a status (sets $?). Without any string the return status is zero if the style is defined for at least one matching pattern, has only one string in its value, and that is equal to one of ‘true’, ‘yes’, ‘on’ or ‘1’. If any strings are given the status is zero if and only if at least one of the strings is equal to at least one of the strings in the value. If the style is defined but doesn’t match, the return status is 1. If the style is not defined, the status is 2.

The -T option tests the values of the style like -t, but it returns status zero (rather than 2) if the style is not defined for any matching pattern.

zstyle -m context style pattern

Match a value. Returns status zero if the pattern matches at least one of the strings in the value.

zformat -f param format spec ...
zformat -F param format spec ...
zformat -a array sep spec ...

This builtin provides different forms of formatting. The first form is selected with the -f option. In this case the format string will be modified by replacing sequences starting with a percent sign in it with strings from the specs. Each spec should be of the form ‘char:string’ which will cause every appearance of the sequence ‘%char’ in format to be replaced by the string. The ‘%’ sequence may also contain optional minimum and maximum field width specifications between the ‘%’ and the ‘char’ in the form ‘%min.maxc’, i.e. the minimum field width is given first and if the maximum field width is used, it has to be preceded by a dot. Specifying a minimum field width makes the result be padded with spaces to the right if the string is shorter than the requested width. Padding to the left can be achieved by giving a negative minimum field width. If a maximum field width is specified, the string will be truncated after that many characters. After all ‘%’ sequences for the given specs have been processed, the resulting string is stored in the parameter param.

The %-escapes also understand ternary expressions in the form used by prompts. The % is followed by a ‘(’ and then an ordinary format specifier character as described above. There may be a set of digits either before or after the ‘(’; these specify a test number, which defaults to zero. Negative numbers are also allowed. An arbitrary delimiter character follows the format specifier, which is followed by a piece of ‘true’ text, the delimiter character again, a piece of ‘false’ text, and a closing parenthesis. The complete expression (without the digits) thus looks like ‘%(X.text1.text2)’, except that the ‘.’ character is arbitrary. The value given for the format specifier in the char:string expressions is evaluated as a mathematical expression, and compared with the test number. If they are the same, text1 is output, else text2 is output. A parenthesis may be escaped in text2 as %). Either of text1 or text2 may contain nested %-escapes.

For example:

zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3

outputs "The answer is ’yes’." to REPLY since the value for the format specifier c is 3, agreeing with the digit argument to the ternary expression.

With -F instead of -f, ternary expressions choose between the ‘true’ or ‘false’ text on the basis of whether the format specifier is present and non-empty. A test number indicates a minimum width for the value given in the format specifier. Negative numbers reverse this, so the test is for whether the value exceeds a maximum width.

The form, using the -a option, can be used for aligning strings. Here, the specs are of the form ‘left:right’ where ‘left’ and ‘right’ are arbitrary strings. These strings are modified by replacing the colons by the sep string and padding the left strings with spaces to the right so that the sep strings in the result (and hence the right strings after them) are all aligned if the strings are printed below each other. All strings without a colon are left unchanged and all strings with an empty right string have the trailing colon removed. In both cases the lengths of the strings are not used to determine how the other strings are to be aligned. A colon in the left string can be escaped with a backslash. The resulting strings are stored in the array.

zregexparse

This implements some internals of the _regex_arguments function.

zparseopts [ -D -E -F -K -M ] [ -a array ] [ -A assoc ] [ - ] spec ...

This builtin simplifies the parsing of options in positional parameters, i.e. the set of arguments given by $*. Each spec describes one option and must be of the form ‘opt[=array]’. If an option described by opt is found in the positional parameters it is copied into the array specified with the -a option; if the optional ‘=array’ is given, it is instead copied into that array, which should be declared as a normal array and never as an associative array.

Note that it is an error to give any spec without an ‘=array’ unless one of the -a or -A options is used.

Unless the -E option is given, parsing stops at the first string that isn’t described by one of the specs. Even with -E, parsing always stops at a positional parameter equal to ‘-’ or ‘--’. See also -F.

The opt description must be one of the following. Any of the special characters can appear in the option name provided it is preceded by a backslash.

name
name+

The name is the name of the option without the leading ‘-’. To specify a GNU-style long option, one of the usual two leading ‘-’ must be included in name; for example, a ‘--file’ option is represented by a name of ‘-file’.

If a ‘+’ appears after name, the option is appended to array each time it is found in the positional parameters; without the ‘+’ only the last occurrence of the option is preserved.

If one of these forms is used, the option takes no argument, so parsing stops if the next positional parameter does not also begin with ‘-’ (unless the -E option is used).

name:
name:-
name::

If one or two colons are given, the option takes an argument; with one colon, the argument is mandatory and with two colons it is optional. The argument is appended to the array after the option itself.

An optional argument is put into the same array element as the option name (note that this makes empty strings as arguments indistinguishable). A mandatory argument is added as a separate element unless the ‘:-’ form is used, in which case the argument is put into the same element.

A ‘+’ as described above may appear between the name and the first colon.

In all cases, option-arguments must appear either immediately following the option in the same positional parameter or in the next one. Even an optional argument may appear in the next parameter, unless it begins with a ‘-’. There is no special handling of ‘=’ as with GNU-style argument parsers; given the spec-foo:’, the positional parameter ‘--foo=bar’ is parsed as ‘--foo’ with an argument of ‘=bar’.

When the names of two options that take no arguments overlap, the longest one wins, so that parsing for the specs ‘-foo -foobar’ (for example) is unambiguous. However, due to the aforementioned handling of option-arguments, ambiguities may arise when at least one overlapping spec takes an argument, as in ‘-foo: -foobar’. In that case, the last matching spec wins.

The options of zparseopts itself cannot be stacked because, for example, the stack ‘-DEK’ is indistinguishable from a spec for the GNU-style long option ‘--DEK’. The options of zparseopts itself are:

-a array

As described above, this names the default array in which to store the recognised options.

-A assoc

If this is given, the options and their values are also put into an associative array with the option names as keys and the arguments (if any) as the values.

-D

If this option is given, all options found are removed from the positional parameters of the calling shell or shell function, up to but not including any not described by the specs. If the first such parameter is ‘-’ or ‘--’, it is removed as well. This is similar to using the shift builtin.

-E

This changes the parsing rules to not stop at the first string that isn’t described by one of the specs. It can be used to test for or (if used together with -D) extract options and their arguments, ignoring all other options and arguments that may be in the positional parameters. As indicated above, parsing still stops at the first ‘-’ or ‘--’ not described by a spec, but it is not removed when used with -D.

-F

If this option is given, zparseopts immediately stops at the first option-like parameter not described by one of the specs, prints an error message, and returns status 1. Removal (-D) and extraction (-E) are not performed, and option arrays are not updated. This provides basic validation for the given options.

Note that the appearance in the positional parameters of an option without its required argument always aborts parsing and returns an error as described above regardless of whether this option is used.

-K

With this option, the arrays specified with the -a option and with the ‘=array’ forms are kept unchanged when none of the specs for them is used. Otherwise the entire array is replaced when any of the specs is used. Individual elements of associative arrays specified with the -A option are preserved by -K. This allows assignment of default values to arrays before calling zparseopts.

-M

This changes the assignment rules to implement a map among equivalent option names. If any spec uses the ‘=array’ form, the string array is interpreted as the name of another spec, which is used to choose where to store the values. If no other spec is found, the values are stored as usual. This changes only the way the values are stored, not the way $* is parsed, so results may be unpredictable if the ‘name+’ specifier is used inconsistently.

For example,

set -- -a -bx -c y -cz baz -cend
zparseopts a=foo b:=bar c+:=bar

will have the effect of

foo=(-a)
bar=(-b x -c y -c z)

The arguments from ‘baz’ on will not be used.

As an example for the -E option, consider:

set -- -a x -b y -c z arg1 arg2
zparseopts -E -D b:=bar

will have the effect of

bar=(-b y)
set -- -a x -c z arg1 arg2

I.e., the option -b and its arguments are taken from the positional parameters and put into the array bar.

The -M option can be used like this:

set -- -a -bx -c y -cz baz -cend
zparseopts -A bar -M a=foo b+: c:=b

to have the effect of

foo=(-a)
bar=(-a {No value for `dsq'} -b xyz)