path: root/Doc/Zsh/mod_zutil.yo

COMMENT(!MOD!zsh/zutil
Some utility builtins, e.g. the one for supporting configuration via 
styles.
!MOD!)
cindex(builtins, utility)
The tt(zsh/zutil) module only adds some builtins:

startitem()
findex(zstyle)
xitem(tt(zstyle) [ tt(-L) ])
xitem(tt(zstyle) [ tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(strings) ...)
xitem(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])
xitem(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ])
xitem(tt(zstyle -abhs) var(context) var(style) var(name) [ var(sep) ])
xitem(tt(zstyle -Tt) var(context) var(style) [ var(strings) ...])
item(tt(zstyle -m) var(context) var(style) var(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 this, the patterns are ordered from most specific to
less 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
`tt(*)'.

The first form (without arguments) lists the definitions in the order
tt(zstyle) will test them. If the tt(-L) option is given, listing is
done in the form of calls to tt(zstyle).  Forms with arguments:

startitem()
item(tt(zstyle) [ tt(-) | tt(-)tt(-) ] var(pattern) var(style) var(strings) ...)(
Defines the given var(style) for the var(pattern) with the var(strings) as
the value.
)
item(tt(zstyle -d) [ var(pattern) [ var(styles) ... ] ])(
Delete style definitions. Without arguments all definitions are deleted,
with a var(pattern) all definitions for that pattern are deleted and if
any var(styles) are given, then only those styles are deleted for the
var(pattern).
)
item(tt(zstyle -g) var(name) [ var(pattern) [ var(style) ] ])(
Retrieve a style definition. The var(name) is
used as the name of an array in which the results are stored. Without
any further arguments, all var(patterns) defined are returned. With a
var(pattern) the styles defined for that pattern are returned and with 
both a var(pattern) and a var(style), the value strings of that
combination is returned.
)
enditem()

The other forms can be used to look up or test patterns.

startitem()
item(tt(zstyle -s) var(context) var(style) var(name) [ var(sep) ])(
The parameter var(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 var(sep) string if that is given) between them.
)
item(tt(zstyle -b) var(context) var(style) var(name))(
The value is stored in var(name) as a boolean, i.e. as the string
`tt(yes)' if the value has only one string and that string is equal to one
of `tt(yes)', `tt(true)', `tt(on)', or `tt(1)'. If the value is any other
string or has more than one string, the parameter is set to `tt(no)'.
)
xitem(tt(zstyle -a) var(context) var(style) var(name))
item(tt(zstyle -h) var(context) var(style) var(name))(
With the tt(-a) option the value is stored in var(name) as an array and
with tt(-h) as an associative array (with the first, third, etc. string
being used as the keys and the other strings being used as the values).
)
xitem(tt(zstyle -t) var(context) var(style) [ var(strings) ...])
item(tt(zstyle -T) var(context) var(style) [ var(strings) ...])(
Test the value of a style, i.e. the tt(-t) option only returns a status
(sets tt($?)).  Without any var(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 `tt(true)', `tt(yes)', `tt(on)' or
`tt(1)'. If any var(strings) are given the status is zero if and only if
at least one of the var(strings) is equal to at least one of the strings
in the value. If the style is not defined, the status is tt(2).

The tt(-T) option is like tt(-t) but returns zero if the style is not
set for any matching pattern.
)
item(tt(zstyle -m) var(context) var(style) var(pattern))(
Match a value. Returns status zero if the 
var(pattern) matches at least one of the strings in the value.
)
enditem()
)
findex(zformat)
xitem(tt(zformat -f) var(param) var(format) var(specs) ...)
item(tt(zformat -a) var(array) var(sep) var(specs) ...)(
This builtin provides to different forms of formatting. The first form 
is selected with the tt(-f) option. If this is given, the var(format)
string will be modified by replacing sequences starting with a percent 
sign in it with strings from the var(specs). Each var(spec) has to be
of the form `var(char)tt(:)var(string)' and this will make every
appearance of the sequence `tt(%)var(char)' in var(format) be replaced 
with the var(string). The `tt(%)' sequence may also contain optional
minimum and maximum field width specifications between the `tt(%)' and 
the `var(char)' in the form `tt(%)var(min)tt(.)var(max)tt(c)',
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. Giving a minimum field
width makes the result be padded with spaces to the right if the
var(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 given, the var(string) will be truncated after that
many characters. After all `tt(%)' sequences for the given var(specs)
have been processed, the resulting string is stored in the parameter
var(param).

The second form, using the tt(-a) option, can be used to get aligned
strings. Here, the var(specs) are of the form
`var(left)tt(:)var(right)' where `var(left)' and `var(right)' are
arbitrary strings. These strings are modified by replacing the colons
with the var(sep) string and padding the var(left) strings with spaces 
to the right so that the var(sep) strings in the result (and hence the 
var(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 a empty var(right) string have the
trailing colon removed. In both cases the lengths of the strings
are not used to determine how the other strings have to be aligned.
The resulting strings are stored in the var(array).
)
findex(zregexparse)
item(tt(zregexparse))(
This implements the internals of the `tt(_regex_arguments)'.
)
findex(zparseopts)
item(tt(zparseopts) [ tt(-D) ] [ tt(-a) var(array) ] [ tt(-A) var(assoc) ] var(specs))(
This builtin simplifies the parsing of options in the positional
parameters. Each var(spec) describes one option and should be of the
form `var(name)[tt(+)][tt(:)[tt(:)][tt(-)]][tt(=)var(array)]'. The var(name)
is the name of the option (without the leading `tt(-)'). If only that
is given, the option takes no argument and if it is found in the
positional parameters it will be placed in the var(array) given with
the tt(-a) option. If the optional `tt(=)var(array)' is given, it will 
be put into that array instead. If one or two colons are given, the
option takes an argument. With one colon, this argument is mandatory
and with two colons it is optional. The argument will be inserted into 
the var(array), too. For mandatory arguments it is added as a separate 
string and for optional arguments it is put into one string together
with the option name unless the `tt(-)' option is given. In this case
the argument will be put into the same word even for mandatory
arguments (note that this makes empty strings as arguments
indistinguishable). Finally, if the `tt(+)' is given and the option
appears more than once in the positional parameters, it will be
inserted more than once in the var(array), too. Without the `tt(+)'
the option will be inserted only once in the var(array) with arguments 
of later options overwriting earlier once. If any of the special
character needs to appear in the option name it must be preceded by a
backslash.

If the tt(-A) option is given, the options and their values will also
be put into an associative array with the option names as keys and the 
arguments (if any) as the values. Note that it is an error to give
var(specs) without a `tt(=)var(array)' and not use either the tt(-a)
or tt(-A) option.

If the tt(-D) option is given, all options found are removed from the
positional parameters leaving only the strings from the first one that 
was not described by any of the var(specs) to the last (note that this 
is the usual rule used by tt(zparseopts) to find out when to stop
processing options).

For example, calling `tt(zparseopts a=foo b:=bar c+:=bar)' with the
strings `tt(-a)', `tt(-bx)', `tt(-c)', `tt(y)', `tt(-cz)', `tt(baz)'
and `tt(-cend)' as positional arguments will set the array tt(foo) to
contain the element `tt(-a)' and the array tt(bar) to the strings
`tt(-b)', `tt(x)', `tt(-c)', `tt(y)', `tt(-c)', and `tt(z)'. The
`tt(baz)' and all strings after it will not be used.
)
enditem()