1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2025-10-27 04:40:59 +01:00

manual/8992

This commit is contained in:
Tanaka Akira 1999-12-10 14:47:55 +00:00
parent d5d015115c
commit 188e6569db
49 changed files with 1061 additions and 699 deletions

View file

@ -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)
example(zstyle ':completion:*::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.
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

View file

@ -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:

View file

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

View file

@ -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.
)

109
Doc/Zsh/mod_zutil.yo Normal file
View file

@ -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()

View file

@ -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)