GNU Info
(zsh.info)The zsh/zutil Module
The zsh/zutil Module
====================
The zsh/zutil module only adds some builtins:
zstyle [ -L ]
zstyle [ -e | - | -- ] PATTERN STYLE STRINGS ...
zstyle -d [ PATTERN [ STYLES ... ] ]
zstyle -g NAME [ PATTERN [ STYLE ] ]
zstyle -abs CONTEXT STYLE NAME [ SEP ]
zstyle -Tt CONTEXT STYLE [ STRINGS ...]
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
compared to the patterns. The definition stored for the first
matching pattern will be returned.
For ordering of comparisons, patterns are searched from most
specific to least specific, and patterns that are equally specific
keep the order in which they were defined. 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 `*'.
The first form (without arguments) lists the definitions in the
order zstyle will test them. If the -L option is given, listing is
done in the form of calls to zstyle. Forms with arguments:
zstyle [ - | -- | -e ] PATTERN STYLE STRINGS ...
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 [ STYLES ... ] ]
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 patterns.
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.
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'.
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.
zstyle -t CONTEXT STYLE [ STRINGS ...]
zstyle -T CONTEXT STYLE [ STRINGS ...]
Test the value of a style, i.e. the -t option only returns a
status (sets $?). Without any STRINGS 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 not defined, the status is 2.
The -T option tests the values of the style like -t, but it
returns 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 SPECS ...
zformat -a ARRAY SEP SPECS ...
This builtin provides two 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 second 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. The resulting strings are stored in
the ARRAY.
zregexparse
This implements some internals of the _regex_arguments function.
zparseopts [ -D ] [ -K ] [ -E ] [ -a ARRAY ] [ -A ASSOC ] SPECS
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.
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 `--'.
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.
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. This is similar to using the shift builtin.
-K
With this option, the arrays specified with the -a and -A
options and with the `=ARRAY' forms are kept unchanged when
none of the SPECS for them is used. This allows assignment
of default values to them before calling zparseopts.
-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.
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.
automatically generated by info2www version 1.2.2.9