manual/8992

6 files changed, 160 insertions, 138 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 7558e14c8..ea70421d8 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -258,37 +258,6 @@ In each of the forms supporting it the tt(-a) option makes the
 var(function) autoloadable (exactly equivalent to
 tt(autoload -U )var(function)).
 )
-findex(compstyle)
-cindex(completion system, configuring)
-xitem(tt(compstyle) var(pattern) var(style) var(strings ...))
-xitem(tt(compstyle -d) [ var(pattern) [ var(styles ...) ] ])
-item(tt(compstyle) [ tt(-L) ] )(
-Several aspects of the completion system can be configured by the
-user. This function allows to define so-called styles that are used by 
-various completion functions. These styles are associated with
-patterns that are compared to context names used by the completion
-system. The possible ways to configure the completion system are
-explained in detail in
-ifzman(the section `Completion System Configuration' below)\
-ifnzman(noderef(Completion System Configuration))\
-.
-
-In the first form a new var(style) is defined for a certain
-var(pattern), setting it to the value given by the var(strings). If there 
-was already a definition for the same var(pattern)/var(style) pair,
-only the value is changed.
-
-The second form with the tt(-d) option can be used to delete
-definitions made by previous calls with the first form. Without any
-arguments all definitions are removed. If a var(pattern) is given, all 
-styles defined for it are removed and if a var(pattern) and any number 
-of var(styles) are given, only those styles are removed for the
-pattern.
-
-In the last form (without arguments) all definitions are listed. If
-the tt(-L) option is given this is done in the form of calls to
-tt(compstyle).
-)
 enditem()
 
 texinode(Completion System Configuration)(Control Functions)(Initialization)(Completion System)
@@ -452,16 +421,17 @@ information needed to change the tt(_sort_tags) function when one
 wants to change the way matches are generated for that context.
 
 But the completion system can not only be configured by supplying a
-specialized tt(_sort_tags) function. There are also the
-`styles' defined with the tt(compstyle) function mentioned in
-ifzman(the section `Initialization' above)\
-ifnzman(noderef(Initialization))\
-.
+specialized tt(_sort_tags) function. It also uses `styles' defined
+with the tt(zstyle) builtin command (see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zutil Module))\
+) using the prefix `tt(:completion)' and the context name when testing 
+and retrieving values.
 
 For some tags the completion functions look up the definition of
 certain styles set for the current context. These styles can have any
 number of strings as their values and specify, for example, how the
-matches are generated. The tt(compstyle) function defines mappings
+matches are generated. The tt(zstyle) builtin command defines mappings
 between patterns and style names with their values. Whenever a
 completion function looks up the value of a style it uses the name of
 the current context followed by a colon and the name of a tag. This
@@ -473,11 +443,11 @@ simple and a verbose form and use the tt(verbose) style to decide
 which form should be used. To make all such functions always use the
 verbose form one can simply call
 
-example(compstyle '*' verbose yes)
+example(zstyle ':completion:*' verbose yes)
 
-in one of the startup files like tt(.zshrc) (after the call to the
-tt(compinit) function). This definition simply means that the
-tt(verbose) style has tt(yes) as its value in every context.
+in one of the startup files like tt(.zshrc). This definition simply
+means that the tt(verbose) style has tt(yes) as its value in every
+context.
 
 The completion function for the tt(kill) builtin command uses this
 style to decide if jobs and processes are listed only as job numbers
@@ -486,7 +456,7 @@ and the command lines of the processes (the latter is achieved by
 calling the tt(ps) command). To make this builtin list the matches
 only as numbers one could call:
 
-example(compstyle '*::kill:*' verbose no)
+example(zstyle ':completion:*::kill:*' verbose no)
 
 And if one wants to see the command lines for processes but not the
 job texts one could use the fact that the tag name is appended to the
@@ -494,21 +464,12 @@ context name when styles are looked up and instead of the previous
 call use (remember that the function for the tt(kill) builtin command
 uses the tags tt(jobs) and tt(processes)): 
 
-example(compstyle '*::kill:*:jobs' verbose no)
-
-As said above, the patterns given to the tt(compstyle) function are
-tested in the order in which they were given. But that isn't
-completely true. In fact, this function roughly sorts the patterns so
-that more specialized patterns are compared before more general
-patterns. Due to this, the last two examples could be defined after
-the first one because both `tt(*::kill:*)' and `tt(*::kill:*:jobs)' are
-considered to be more specific then the pattern `tt(*)' from the first
-example. To decide how specific a pattern is, the function looks at 
-the number of colons (corresponding to the number of components) used
-in the pattern, and if these components are actual patterns (like the
-`tt(*)') or simple strings (like the `tt(jobs)' in the last
-example). Patterns with fewer colons and fewer simple strings are
-considered to be less specific.
+example(zstyle ':completion:*::kill:*:jobs' verbose no)
+
+Due to the ordering tt(zstyle) does with the patterns defined, the
+last two examples could be defined after the first one because both
+`tt(*::kill:*)' and `tt(*::kill:*:jobs)' are considered to be more
+specific then the pattern `tt(*)' from the first example.
 
 As for tags, completion functions can use any number of styles, so
 there can't be a complete list. However, the following two sections
@@ -807,9 +768,9 @@ example, to use completion, approximation and correction for normal
 completion, completion and correction for incremental completion and
 only completion for prediction one could use:
 
-example(compstyle '*' completer _complete _correct _approximate
-compstyle ':incremental' completer _complete _correct
-compstyle ':predict' completer _complete)
+example(zstyle ':completion:*' completer _complete _correct _approximate
+zstyle ':completion:incremental' completer _complete _correct
+zstyle ':completion:predict' completer _complete)
 )
 item(tt(completions))(
 This style is used by the tt(_expand) completer function.
@@ -830,7 +791,7 @@ should be set to an expression usable inside a `tt($((...)))'
 arithmetical expression. In this case, delaying will be done if the
 expression evaluates to `tt(1)'. For example, with
 
-example(compstyle ':list' condition 'NUMERIC != 1')
+example(zstyle ':completion:list' condition 'NUMERIC != 1')
 
 delaying will be done only if given an explicit numeric argument
 other than `tt(1)'.
@@ -882,6 +843,14 @@ replaced with the message given by the completion function.
 Finally, for the tt(warnings) tag, it is printed when no matches could 
 be generated at all. In this case the `tt(%d)' is replaced with the
 descriptions for the matches that were expected.
+
+Here and in all other cases where the completion system uses `tt(%)'
+sequences, the `tt(%)' may be followed by field with specifications as 
+described for the tt(zformat) builtin command from the tt(zutil)
+module, see
+ifzman(zmanref(zshmodules))\
+ifnzman(noderef(The zutil Module))\
+.
 )
 item(tt(glob))(
 Like tt(complete), this is used by the tt(_expand) completer.
@@ -901,8 +870,8 @@ aliases and shell functions and reserved words as possible
 completions. To have the external commands and shell functions listed
 separately, one can set:
 
-example(compstyle '*:-command-:commands' group-name commands
-compstyle '*:-command-:functions' group-name functions)
+example(zstyle ':completion:*:-command-:commands' group-name commands
+zstyle ':completion:*:-command-:functions' group-name functions)
 
 This also means that if the same name is used for different types of
 matches, then those matches will be displayed together in the same
@@ -912,7 +881,7 @@ If the name given is the empty string, then the name of the tag for
 the matches will be used as the name of the group. So, to have all
 different types of matches displayed separately, one can just set:
 
-example(compstyle '*' group-name '')
+example(zstyle ':completion:*' group-name '')
 
 All matches for which no group name is defined will be put in a group
 named tt(-default-).
@@ -931,7 +900,7 @@ For example, to have names of builtin commands, shell functions and
 external commands appear in this order when completing in command
 position one would set:
 
-example(compstyle '*:-command-' group-order builtins functions commands)
+example(zstyle ':completion:*:-command-' group-order builtins functions commands)
 )
 item(tt(groups))(
 A style holding the names of the groups that should be completed. If
@@ -1046,7 +1015,7 @@ the type described by the tag.
 To be able to share the same specifications one has set up for the GNU
 version of the tt(ls) command one can use:
 
-example(compstyle '*:default' list-colors ${(s.:.)LS_COLORS})
+example(zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS})
 
 And to get the default colors (which are the same as for the GNU
 tt(ls) command) one should set the style to an empty value.
@@ -1082,7 +1051,7 @@ If the value for this style contains the string tt(numeric), the
 completer function will take any numeric argument as the
 maximum number of errors allowed. For example, with
 
-example(compstyle ':approximate' accept 2 numeric)
+example(zstyle ':completion:approximate' accept 2 numeric)
 
 two errors will be allowed if no numeric argument is given. However,
 with a numeric argument of six (as in `tt(ESC-6 TAB)'), up to six
@@ -1241,7 +1210,7 @@ non-empty string it should be an expression usable inside a `tt($((...)))'
 arithmetical expression. In this case, expansion of substitutions will
 be done if the expression evaluates to `tt(1)'. For example, with
 
-example(compstyle ':expand' substitute '${NUMERIC:-1} != 1')
+example(zstyle ':completion:expand' substitute '${NUMERIC:-1} != 1')
 
 substitution will be performed only if given an explicit numeric
 argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'.
@@ -1295,7 +1264,7 @@ arguments are given, the set of functions to try is taken from the
 tt(completer) style. For example, to use normal completion and
 correction if that doesn't generate any matches:
 
-example(compstyle '*' completer _complete _correct)
+example(zstyle ':completion:*' completer _complete _correct)
 
 after calling tt(compinit). The default value for this style set up
 in tt(compinit) is `tt(_complete)', i.e. normally only ordinary
@@ -1407,7 +1376,7 @@ counted. The resulting list of corrected and completed strings is then
 presented to the user. The intended use of this completer function is to
 try after the normal tt(_complete) completer by setting:
 
-example(compstyle '*' completer _complete _approximate)
+example(zstyle ':completion:*' completer _complete _approximate)
 
 This will give correcting completion if and only if
 normal completion doesn't yield any possible completions. When
@@ -1436,9 +1405,9 @@ different top-level context name.
 
 For example, with:
 
-example(compstyle '*' completer _complete _correct _approximate
-compstyle ':correct' accept 2 not-numeric
-compstyle ':approximate' accept 3 numeric)
+example(zstyle ':completion:*' completer _complete _correct _approximate
+zstyle ':completion:correct' accept 2 not-numeric
+zstyle ':completion:approximate' accept 3 numeric)
 
 correction will accept up to two errors. If a numeric argument is
 given, correction will not be performed, but correcting completion
@@ -1837,48 +1806,6 @@ generated by the tt(_users) and tt(_hosts) functions respectively).
 Like tt(_tags) this function supports the tt(-C) option to give an
 additional context name component.
 )
-findex(_style)
-item(tt(_style))(
-This function is used to look up the values of styles defined by the
-user. In its simplest form, it is called with two arguments: a tag and 
-a style-name. The tag (if non-empty) is temporarily appended to the
-current context name (preceded by a colon) and the patterns defined by 
-the user with the tt(compstyle) function will be compared to that
-combined name. If any of those patterns match the name and the given
-style is defined for it and its boolean value is `true' (i.e. its
-value is one of `tt(true)', `tt(on)', `tt(yes)', and `tt(1)'), tt(_style)
-returns zero and non-zero otherwise. If you want to test the style not 
-only for a boolean value, you can give a third argument which is then
-used as a pattern and tt(_style) returns zero if the pattern matches
-the value defined for the style.
-
-If you want to retrieve the value defined for the style, you can use
-one of the options tt(-b) (to retrieve it as a boolean value, i.e. one 
-of tt(yes) or tt(no)), tt(-s) (to get it as a scalar, i.e. a string
-concatenated from the value strings defined by the user, separated by
-spaces), tt(-a) (to get it as an array), and tt(-h) (to get it as an
-associative array; in this case the first, third, etc. strings from the 
-value are used as the keys and the others as their values). In each of
-these cases the arguments after the option are the tag, the style-name
-and the name of the parameter into which the result will be stored.
-
-For example, to test if the tt(description) style is set to `true' for 
-the current context and the tag tt(foo):
-
-example(if _style foo description; then
-  ... # style is true
-fi)
-
-And to get the value of the tt(path) style for the tag tt(foo) as an
-array into the parameter tt(tmp):
-
-example(local tmp
-_style -a foo path tmp)
-
-In any case, the return value of this function is zero if a
-definition for the style was found and non-zero if no definition was
-found.
-)
 findex(_describe)
 item(tt(_describe) var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
 This function can be used to add options or values with descriptions
diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo
index 3914fffce..996462b7b 100644
--- a/Doc/Zsh/mod_clone.yo
+++ b/Doc/Zsh/mod_clone.yo
@@ -1,4 +1,4 @@
-texinode(The clone Module)(The complete Module)(The cap Module)(Zsh Modules)
+texinode(The clone Module)(The zutil Module)(The cap Module)(Zsh Modules)
 sect(The clone Module)
 The tt(clone) module makes available one builtin command:
 
diff --git a/Doc/Zsh/mod_complete.yo b/Doc/Zsh/mod_complete.yo
index 0443fcde8..418e54d28 100644
--- a/Doc/Zsh/mod_complete.yo
+++ b/Doc/Zsh/mod_complete.yo
@@ -1,4 +1,4 @@
-texinode(The complete Module)(The compctl Module)(The clone Module)(Zsh Modules)
+texinode(The complete Module)(The compctl Module)(The zutil Module)(Zsh Modules)
 sect(The complete Module)
 The tt(complete) module makes available several builtin commands which
 can be used in user-defined completion widgets, see
diff --git a/Doc/Zsh/mod_computil.yo b/Doc/Zsh/mod_computil.yo
index 5bb045eec..51922b13f 100644
--- a/Doc/Zsh/mod_computil.yo
+++ b/Doc/Zsh/mod_computil.yo
@@ -6,8 +6,7 @@ some of the completion functions in the shell function based
 completions system (see
 ifzman(zmanref(zshcompsys))\
 ifnzman(noderef(Completion System))
-). Except for tt(compquote) and tt(compdisplay) these builtin
-commands are very
+). Except for tt(compquote) these builtin commands are very
 specialised and thus not very interesting when writing your own
 completion functions. In short, these builtin commands are:
 
@@ -24,22 +23,6 @@ innermost quoting level.
 
 The return value is non-zero in case of an error and zero otherwise.
 )
-item(tt(compfmt) var(name) var(string) var(defs) ...)(
-The var(defs) ar of the form `var(char)tt(;)var(string)' and
-tt(compfmt) will replace every occurance of the sequence
-`tt(%)var(char)' for each of the var(char)s with the corresponding
-var(string). The resulting string will be placed in the parameter
-var(name).
-)
-item(tt(compdisplay) var(name) var(string) var(defs) ...)(
-The var(defs) are strings which should be of the form
-`var(str)tt(:)var(descr)' (the intended use is that the var(descr)
-describes the var(str)) and tt(compdisplay) will convert them to
-strings in which the colon is replaced by the var(string) given as the 
-second argument and spaces are inserted before that so that they are
-aligned over all strings. These resultings strings are then assigned
-to an array with the var(name) given as the first argument.
-)
 item(tt(compdescribe))(
 This is used by the tt(_describe) function to build the displays for
 the matches and to get the strings to add as matches with their
@@ -68,9 +51,6 @@ to access the state information to decide what should be completed.
 item(tt(compvalues))(
 Like tt(comparguments), but for the tt(_values) function.
 )
-item(tt(compstyle))(
-This builtin implements the internals of the style mechanism.
-)
 item(tt(comptags), tt(comptry))(
 This implements the internals of the tags mechanism.
 )
diff --git a/Doc/Zsh/mod_zutil.yo b/Doc/Zsh/mod_zutil.yo
new file mode 100644
index 000000000..477f955eb
--- /dev/null
+++ b/Doc/Zsh/mod_zutil.yo
@@ -0,0 +1,109 @@
+texinode(The zutil Module)(The complete Module)(The clone Module)(Zsh Modules)
+sect(The zutil Module)
+cindex(builtins, utility)
+The tt(zutil) module only adds some builtins:
+
+startitem()
+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 -s) var(context) var(style) var(name) [ var(sep) ])
+xitem(tt(zstyle -b) var(context) var(style) var(name))
+xitem(tt(zstyle -a) var(context) var(style) var(name))
+xitem(tt(zstyle -h) var(context) var(style) var(name))
+xitem(tt(zstyle -t) 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).
+
+In the second form this defines the given var(style) for the
+var(pattern) with the var(strings) as the value.
+
+The third form can be used to delete such 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).
+
+The fourth form allows to retrieve definitions. The var(name) will be
+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.
+
+The other forms can be used to look up or test patterns. With the
+tt(-s) option, the value of the style is returned as a string in the
+parameter var(name). For this, the strings from the value are
+concatenated with spaces (or the var(sep) string if that is given)
+between them. The tt(-b) option makes the value be returned as a
+boolean, i.e. as the string tt(yes) if the value has only one string
+and that is equal to one of tt(yes), tt(true), tt(on), or tt(1). If
+the value has more than one string or only one but that is different
+from the strings mentioned, the parameter will be set to tt(no). The
+tt(-a) option makes the value be returned as an array and the tt(-h)
+makes it be returned as an associative array (with the first, third,
+etc. string being used as the keys and the other strings being used as 
+the values).
+
+The tt(-t) option can be used to test the value of a style, i.e. it
+only sets the return value. Without any var(strings) arguments it 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 return
+zero if and only if at least one of the var(strings) is equal to at
+least one of the strings in the value.
+
+The tt(-m) option can be used to match a value. It returns zero if the 
+var(pattern) matches at least one of the strings in the value.
+)
+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
+appearence 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).
+)
+enditem()
diff --git a/Doc/Zsh/modules.yo b/Doc/Zsh/modules.yo
index 827f68b4c..89c1f7246 100644
--- a/Doc/Zsh/modules.yo
+++ b/Doc/Zsh/modules.yo
@@ -15,6 +15,10 @@ Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege) sets.
 item(tt(clone))(
 A builtin that can clone a running shell onto another terminal.
 )
+item(tt(zutil))(
+Some utility builtins, e.g. the one for supporting configuration via 
+styles.
+)
 item(tt(complete))(
 The basic completion code.
 )
@@ -66,6 +70,7 @@ enditem()
 startmenu()
 menu(The cap Module)
 menu(The clone Module)
+menu(The zutil Module)
 menu(The complete Module)
 menu(The compctl Module)
 menu(The complist Module)
@@ -84,6 +89,7 @@ menu(The zleparameter Module)
 endmenu()
 includefile(Zsh/mod_cap.yo)

 includefile(Zsh/mod_clone.yo)

+includefile(Zsh/mod_zutil.yo)

 includefile(Zsh/mod_complete.yo)

 includefile(Zsh/mod_compctl.yo)

 includefile(Zsh/mod_complist.yo)