system/zsh
system/zsh
1
0
Fork 0
mirror of https://github.com/zsh-users/zsh synced 2024-11-02 20:47:49 +00:00
Code Issues Projects Releases Packages Wiki Activity

unposted: complete compsys.yo rewrite

Browse source
This commit is contained in:
Peter Stephenson 2003-04-24 17:37:05 +00:00
parent 3985ac70c3
commit d251482aac
2 changed files with 373 additions and 339 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2003-04-24 Peter Stephenson <pws@pwstephenson.fsnet.co.uk>
* unposted, c.f. 2003-04-14: Doc/Zsh/compsys.yo: finish
rewrite (from _description onwards). Suspicious-looking
_regex_arguments entry.
2003-04-24 Oliver Kiddle <opk@zsh.org>
* unposted: Completion/Unix/Type/_perl_basepods: use _message

706
Doc/Zsh/compsys.yo
View file

@ -3050,13 +3050,13 @@ tt(compadd) with additional options which will take precedence over
those generated by tt(_all_labels).
)
findex(_alternative)
item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
item(tt(_alternative) [ tt(-C) var(name) ] var(spec) ...)(
This function is useful in simple cases where multiple tags are available.
Essentially it implements a loop like the one described for the tt(_tags)
function below.
The tags to use and the action to perform if a tag is requested are
described using the var(specs) which are of the form:
described using the var(spec)s which are of the form:
`var(tag)tt(:)var(descr)tt(:)var(action)'. The var(tag)s are offered using
tt(_tags) and if the tag is requested, the var(action) is executed with the
given description var(descr). The var(action)s are those accepted
@ -3144,8 +3144,8 @@ same word. However, it depends on the action performed whether options
will really be completed at this point. For more control, use a
utility function like tt(_guard) as part of the action.
If the option takes an argument, the forms given above are to be followed
by one or more of the following var(optspec)s:
The following forms are available for the initial var(optspec), whether
or not the option has arguments.
startitem()
item(tt(*)var(optspec))(
@ -3700,40 +3700,51 @@ tt(_describe) uses the tt(_all_labels) function to generate the matches, so
it does not need to appear inside a loop over tag labels.
)
findex(_description)
item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(specs) ... ])(
This function is called before completions are added (typically by a call
to tt(compadd)); it tests various styles and arranges for any necessary
options to be passed on to tt(compadd). The styles are tested in the
current context using the given var(tag); options are put into the array
called var(name) for passing on to tt(compadd); the description for the
current set of matches is passed in var(descr). The styles tested are:
tt(format) (which is first tested for the given var(tag) and then for the
tt(descriptions) tag if that isn't defined), tt(hidden), tt(matcher),
tt(ignored-patterns) and tt(group-name) (the last are tested only for the
tag given as the first argument). This function also calls the tt(_setup)
function which tests some more styles.
item(tt(_description) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(spec) ... ])(
This function is not to be confused with the previous one; it is used as
a helper function for creating options to tt(compadd). It is buried
inside many of the higher level completion functions and so often does
not need to be called directly.
The styles listed below are tested in the current context using the
given var(tag). The resulting options for tt(compadd) are put into the
array named var(name) (this is traditionally `tt(expl)', but this
convention is not enforced). The description for the corresponding set
of matches is passed to the function in var(descr).
The styles tested are: tt(format), tt(hidden), tt(matcher),
tt(ignored-patterns) and tt(group-name). The tt(format) style is first
tested for the given var(tag) and then for the tt(descriptions) tag if
no value was found, while the remainder are only tested for the tag
given as the first argument. The function also calls tt(_setup)
which tests some more styles.
The string returned by the tt(format) style (if any) will be modified so
that the sequence `tt(%d)' is replaced by the var(descr) given as the third
argument without any leading or trailing white space. If, after
removing the white space, the var(descr) is the empty string, the format
style will not be used and the options put into the var(name) array will
not contain an explanation string to be displayed above the matches. If
tt(_description) is called with more than three arguments,
the additional var(specs) should be of the form `var(char)tt(:)var(str)'
and every appearance of `tt(%)var(char)' in the format string will be
replaced by var(string). If the tt(-x) option is given, the
description will be added using the tt(-x) option instead of the
default tt(-X), i.e. the description will even be displayed if no
matches are added for the description.
not contain an explanation string to be displayed above the matches.
The options placed in the array will also make sure that the matches
are placed in a separate group, depending on the value of the
tt(group-name) style. Normally a sorted group will be used for this
(with the `tt(-J)' option), but if an option starting with `tt(-V)',
`tt(-J)', `tt(-1)', or `tt(-2)' is given, that option will be included
in the array, so that it is possible to make the group unsorted by
giving the option `tt(-V)', `tt(-1V)', or `tt(-2V)'.
If tt(_description) is called with more than three arguments,
the additional var(spec)s should be of the form `var(char)tt(:)var(str)'.
These supply escape sequence replacements for the tt(format) style:
every appearance of `tt(%)var(char)' will be
replaced by var(string).
If the tt(-x) option is given, the description will be passed to
tt(compadd) using the tt(-x) option instead of the default tt(-X). This
means that the description will be displayed even if there are no
corresponding matches.
The options placed in the array var(name) take account of the
tt(group-name) style, so matches are placed in a separate group where
necessary. The group normally has its elements sorted (by passing the
option tt(-J) to tt(compadd)), but if an option starting with `tt(-V)',
`tt(-J)', `tt(-1)', or `tt(-2)' is passed to tt(_description), that
option will be included in the array. Hence it is possible for the
completion group to be unsorted by giving the option `tt(-V)',
`tt(-1V)', or `tt(-2V)'.
In most cases, the function will be used like this:
@ -3747,120 +3758,117 @@ a similar format; this ensures that user-specified styles are correctly
passed down to the builtins which implement the internals of completion.
)
findex(_dispatch)
item(tt(_dispatch) var(context strings ...))(
This looks up the functions defined for the var(strings) one after
another until it finds one that is defined. That function is then
called to generate the matches. Normally, the last var(string) is the
one used to look up the default completion.
item(tt(_dispatch) var(context string ...))(
This sets the current context to var(context) and looks for completion
functions to handle this context by hunting through the list of command
names or special contexts (as described above for tt(compdef))
given as var(string ...). The first completion function to be defined
for one of the contexts in the list is used to generate matches.
Typically, the last var(string) is tt(-default-) to cause the function
for default completion to be used as a fallback.
This function is the one responsible for setting the parameter
tt($service) (to the var(strings) as they are tried) and for setting
the var(context/command) field of the tt($curcontext) parameter (to
the var(context) given as the first argument).
The function sets the parameter
tt($service) to the var(string) being tried, and sets
the var(context/command) field (the fourth) of the tt($curcontext)
parameter to the var(context) given as the first argument.
)
findex(_files)
item(tt(_files))(
The function tt(_files) uses the tt(file-patterns) style and calls
tt(_path_files) with all the arguments it was passed except for tt(-g)
and tt(-/). These two options are used depending on the setting of the
tt(file-patterns) style.
The function tt(_files) calls tt(_path_files) with all the arguments it
was passed except for tt(-g) and tt(-/). The use of these two options
depends on the setting of the tt(file-patterns) style.
See tt(_path_files) below for a description of the full set of options
accepted by tt(_files).
This function accepts the full set of options allowed by
tt(_path_files), described below.
)
findex(_gnu_generic)
item(tt(_gnu_generic))(
This function is a simple wrapper around the tt(_arguments) function
described above. It can be used to automatically complete long
options for commands that understand the `tt(-)tt(-help)' option.
It is not intended to be used from completion functions but as a
top-level completion function in its own right. For example, to
enable option completion for the commands tt(foo) and tt(bar), one
would call:
described above. It can be used to determine automatically the long
options understood by commands that produce a list when passed the
option `tt(-)tt(-help)'. It is intended to be used as a top-level
completion function in its own right. For example, to enable option
completion for the commands tt(foo) and tt(bar), use
example(compdef _gnu_generic foo bar)
in one of the initialization files after the call to tt(compinit).
after the call to tt(compinit).
The default installation uses this function only to generate
completions for some GNU-commands because to complete the options, the
command has to be called and hence it shouldn't be used if one can't
be sure that the command understands the `tt(-)tt(-help)' option.
The completion system as supplied is conservative in its use of this
function, since it is important to be sure the command understands the
option `tt(-)'tt(-help)'.
)
findex(_guard)
item(tt(_guard) [ var(options) ] var(pattern descr))(
This function is intended to be used in an action of functions like
tt(_arguments). It returns immediately with a non-zero return value if
This function is intended to be used in the var(action) for
the specifications passed to tt(_arguments) and similar functions. It
returns immediately with a non-zero return value if
the string to be completed does not match the var(pattern). If the
pattern matches, the var(descr) is displayed and the function returns
zero if the word to complete is not empty and non-zero otherwise.
pattern matches, the var(descr) is displayed; the function then returns
zero if the word to complete is not empty, non-zero otherwise.
The var(pattern) may be preceded by those options understood by
The var(pattern) may be preceded by any of the options understood by
tt(compadd) that are passed down from tt(_description), namely tt(-M),
tt(-J), tt(-V), tt(-1), tt(-2), tt(-n), tt(-F) and tt(-X). All of these
options will be ignored.
options will be ignored. This fits in conveniently with the
argument-passing conventions of actions for tt(_arguments).
As an example, consider a command taking the options tt(-n) and
tt(-none), where tt(-n) has to be followed by a numeric value in the
tt(-none), where tt(-n) must be followed by a numeric value in the
same word. By using:
example(_argument '-n-: :_guard "[0-9]#" "numeric value"' '-none')
tt(_arguments) can be made to both display the message `tt(numeric
value)' and complete options after `tt(-n<TAB>)'. If the `tt(-n)' is
already followed by one or more digits (matching the pattern given to
tt(_guard)), only the message will be displayed and if the `tt(-n)' is
already followed by one or more digits (the pattern passed to
tt(_guard)) only the message will be displayed; if the `tt(-n)' is
followed by another character, only options are completed.
)
findex(_message)
xitem(tt(_message) [ tt(-r12) ] [ tt(-VJ) var(group) ] var(descr))
item(tt(_message -e) [ var(tag) ] var(descr))(
The var(descr) is used like the third
argument to the tt(_description) function. However, the resulting
The var(descr) is used in the same way as the third
argument to the tt(_description) function, except that the resulting
string will always be shown whether or not matches were
generated. This is useful to display help texts in places where no
completions can be generated automatically.
generated. This is useful for displaying a help message in places where
no completions can be generated.
This function also uses the tt(format) style for the tt(messages) tag in
preference to the tt(format) style for the tt(descriptions) tag. The
latter is used only if the former is unset.
The tt(format) style is examined with the tt(messages) tag to find a
message; the usual tag, tt(descriptions), is used only if the style is
not set with the former.
If the tt(-r) option is given, no style is used and the var(descr) is
used literally as the string to display. This is only used in cases
where that string is taken from some pre-processed argument list
containing an expanded description.
If the tt(-r) option is given, no style is used; the var(descr) is
taken literally as the string to display. This is most useful
when the var(descr) comes from a pre-processed argument list
which already contains an expanded description.
The tt(-12VJ) options and the var(group) are passed to tt(compadd) and
hence determine the group the message string is added to.
In the second form, the var(descr) is added like a description added
by tt(_description) under the given var(tag), but the var(descr) will
always be shown even if no matches are added for the var(tag). If the
var(tag) is omitted, it is taken from the tt(curtag) parameter which
is set by the functions dealing with tags so it should contain the
right one in almost all cases.
The second form gives a description for completions with the tag
var(tag) to be shown even if there are no matches for that tag. The tag
can be omitted and if so the tag is taken from the parameter
tt($curtag); this is maintained by the completion system and so is
usually correct.
)
findex(_multi_parts)
item(tt(_multi_parts) var(sep) var(array))(
This function receives two arguments: a separator character and an
array. As usual, the var(array) may be either the
The argument var(sep) is a separator character.
The var(array) may be either the
name of an array parameter or a literal array in the form
`tt(LPAR()foo bar)tt(RPAR())' (i.e. a list of words separated by white
space in parentheses). With these arguments, this function will
complete to strings from the array where the parts separated by the
separator character are completed independently. For example, the
tt(_tar) function from the distribution caches the pathnames from the
tar file in an array, and then calls this function to complete these
names in the way normal filenames are completed by the
tt(_path_files) function, by using `tt(_multi_parts) tt(/)
var(patharray)'.
`tt(LPAR()foo bar)tt(RPAR())', a parenthesised list of words separated
by whitespace. The possible completions are the
strings from the array. However, each chunk delimited by var(sep) will be
completed separately. For example, the tt(_tar) function uses
`tt(_multi_parts) tt(/) var(patharray)' to complete partial file paths
from the given array of complete file paths.
If the tt(-i) option is present, then any time there is a unique match it
will immediately be inserted even if that requires additional separators to
be inserted as well. When completing from a fixed set of possible
completions which are really words, this is often the expected behaviour;
however, if tt(_multi_parts) should behave like completing pathnames, the
tt(-i) option should not be used.
The tt(-i) option causes tt(_multi_parts) to insert a unique match even
that requires multiple separators to be inserted. This is not usually
the expected behaviour with filenames, but certain other types of
completion, for example those with a fixed set of possibilities, may be
more suited to this form.
Like other utility functions, this function accepts the `tt(-V)',
`tt(-J)', `tt(-1)', `tt(-2)', `tt(-n)', `tt(-f)', `tt(-X)', `tt(-M)',
@ -3869,27 +3877,27 @@ them to the tt(compadd) builtin.
)
findex(_next_label)
item(tt(_next_label) [ tt(-x) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) [ var(options) ... ])(
This function should be called repeatedly to generate the tag
labels. On each call it will check if another tag label is to be used
and, if there is at least one, zero is returned. If no more tag
labels are to be used, a non-zero status is returned.
This function is used to implement the loop over different tag
labels for a particular tag as describe above for the tt(tag-order)
style. On each call it checks to see if there are any more tag labels; if
there is it returns status zero, otherwise non-zero.
As this function requires a current tag to be set, it must always follow
a call to tt(_tags) or tt(_requested).
The tt(-x12VJ) options and the first three arguments are given to the
tt(_description) function using the tag label instead of the first
argument as appropriate. The var(options) given after the var(descr)
should be other options to be used for tt(compadd) or whatever
function is to be called to add the matches. tt(_next_label) will store these
var(options) in the parameter whose var(name) is given as the second
argument. This is done in such a way that the description given by the
user to the tt(tag-order) style is preferred over the one given to
The tt(-x12VJ) options and the first three arguments are passed to the
tt(_description) function. Where appropriate the var(tag) will be
replaced by a tag label in this call. Any description given in
the tt(tag-order) style is preferred to the var(descr) passed to
tt(_next_label).
Note that this function must not be called without a previous call to
tt(_tags) or tt(_requested) because it uses the tag label
for the current tag found by these functions.
The var(options) given after the var(descr)
are set in the parameter given by var(name), and hence are to be passed
to tt(compadd) or whatever function is called to add the matches.
A normal use of this function for the tag labels of the tag tt(foo)
looks like this:
Here is a typical use of this function for the tag tt(foo). The call to
tt(_requested) determines if tag tt(foo) is required at all; the loop
over tt(_next_label) handles any labels defined for the tag in the
tt(tag-order) style.
example(local expl ret=1
...
@ -3900,37 +3908,39 @@ if _requested foo; then
done
...
fi
return ret
)
return ret)
)
findex(_normal)
item(tt(_normal))(
This function is used for normal command completion. It has two tasks:
completing the first word on the command line as the name of a command, and
completing the arguments to this command. In the second case, the name of
the command is looked up to see if special completions exists, including
completions defined for patterns which match the name. If none is found,
completion is performed for the context tt(-default-).
This is the standard function called to handled completion outside
nay special var(-context-). It is called both to complete the command
word and also the arguments for a command. In the second case,
tt(_normal) looks for a special completion for that command, and if
there is none it uses the completion for the tt(-default-) context.
The function can also be called by other completion functions which need to
treat a range of words as a command line. For example, the function to
complete after the pre-command specifiers such as tt(nohup) removes the
A second use is to rexamine the command line specified by the tt($words)
array and the tt($CURRENT) parameter after those have been modified.
For example, the function tt(_precommand), which
completes after pre-command specifiers such as tt(nohup), removes the
first word from the tt(words) array, decrements the tt(CURRENT) parameter,
then calls tt(_normal) again, with the effect that `tt(nohup) var(cmd ...)'
is treated the same way as `var(cmd ...)'.
then calls tt(_normal) again. The effect is that `tt(nohup) var(cmd ...)'
is treated in the same way as `var(cmd ...)'.
If the command name matches a pattern, the parameter tt(_compskip) is
checked after the call to the corresponding completion function. This has
the same effect here as in the tt(-first-) context: if it is set, no more
completion functions are called even if there are no matches so far.
If the command name matches one of the patterns given by one of the
options tt(-p) or tt(-P) to tt(compdef), the corresponding completion
function is called and then the parameter tt(_compskip) is
checked. If it is set completion is terminated at that point even if
no matches have been found. This is the same effect as in the
tt(-first-) context.
)
findex(_options)
item(tt(_options))(
This can be used to complete option names. It uses a matching
specification that ignores a leading `tt(no)', ignores underscores and
allows the user to type upper-case letters which will match their
lower-case counterparts. All arguments passed to this function are
propagated unchanged to the tt(compadd) builtin.
This can be used to complete the names of shell options. It provides a
matcher specification that ignores a leading `tt(no)', ignores
underscores and allows upper-case letters to
match their lower-case counterparts (for example, `tt(glob)',
`tt(noglob)', `tt(NO_GLOB)' are all completed). Any arguments
are propagated to the tt(compadd) builtin.
)
findex(_options_set)
findex(_options_unset)
@ -3941,21 +3951,23 @@ matching specification used in the tt(_options) function.
Note that you need to uncomment a few lines in the tt(_main_complete)
function for these functions to work properly. The lines in question
are used to store the option settings in effect before the completion
widget locally sets the options it needs. Hence these options are not
widget locally sets the options it needs. Hence these functions are not
generally used by the completion system.
)
findex(_parameters)
item(tt(_parameters))(
This should be used to complete parameter names. tt(_parameters) can
take a tt(-g var(pattern)) option which specifies that only parameters
whose type matches the var(pattern) should be completed. Strings of
the same form as those returned by the tt(t) parameter expansion flag
are used here when matching the type. All other arguments are passed
unchanged to the tt(compadd) builtin.
This is used to complete the names of shell parameters.
The option `tt(-g var(pattern))' limits the completion to parameters
whose type matches the var(pattern). The type of a parameter is that
shown by `tt(print ${(t))var(param)tt(})', hence judicious use of
`tt(*)' in var(pattern) is probably necessary.
All other arguments are passed to the tt(compadd) builtin.
)
findex(_path_files)
item(tt(_path_files))(
The function tt(_path_files) is used throughout the completion system
This function is used throughout the completion system
to complete filenames. It allows completion of partial paths. For
example, the string `tt(/u/i/s/sig)' may be completed to
`tt(/usr/include/sys/signal.h)'.
@ -3974,57 +3986,82 @@ Specifies that only files matching the var(pattern) should be completed.
)
item(tt(-W) var(paths))(
Specifies path prefixes that are to be prepended to the string from the
line to generate the filenames but that should not be inserted in the line
or shown in a completion listing. Here, var(paths) may be the name of an
array parameter, a literal list of paths enclosed in parentheses or an
absolute pathname.
command line to generate the filenames but that should not be inserted
as completions nor shown in completion listings. Here, var(paths) may be
the name of an array parameter, a literal list of paths enclosed in
parentheses or an absolute pathname.
)
item(tt(-F))(
This option from the tt(compadd) builtin gives direct control over which
item(tt(-F) var(ignored-files))(
This behaves as for the corresponding option to the tt(compadd) builtin.
It gives direct control over which
filenames should be ignored. If the option is not present, the
tt(ignored-patterns) style is used.
)
enditem()
These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)',
`tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-q)',
`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin.
Both tt(_path_files) and tt(_files) also accept the following options
which are passed to tt(compadd): `tt(-J)', `tt(-V)',
`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
`tt(-q)', `tt(-r)', and `tt(-R)'.
Finally, the tt(_path_files) function uses the styles tt(expand),
tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort).
tt(ambiguous), tt(special-dirs), tt(list-suffixes) and tt(file-sort)
described above.
)
findex(_pick_variant)
item(tt(_pick_variant [ tt(-c) var(command) ] [ tt(-r) var(name) ] var(command)tt(=)var(pattern) ... var(command) [ var(args) ... ]))(
This function is used to resolve situations where a command has more
than one variant, each requiring different handling or where there is a
name clash between two different commands.
item(tt(_pick_variant [ tt(-c) var(command) ] [ tt(-r) var(name) ] var(label)tt(=)var(pattern) ... var(label) [ var(args) ... ]))(
This function is used to resolve situations where a single command name
requires more than one type of handling, either because it
has more than one variant because there is a name clash between two
different commands.
_pick_variant does this by running the command and comparing its output
against a series of patterns. The command to run is taken from the
first element of the var(words) array unless specified with the tt(-c)
option. Arguments to be passed on to it can be specified at the end
after all the other arguments. The patterns are specified by the series
of var(command)tt(=)var(pattern) arguments where var(command) is a
label used to describe each command. If none of the patterns match, the
final command label is taken and 1 is returned.
The command to run is taken from the first element of the array
tt(words) unless this is overridden by the option tt(-c). This command
is run and its output is compared with a series of patterns. Arguments
to be passed to the command can be specified at the end after all the
other arguments. The patterns to try in order are given by the arguments
var(label)tt(=)var(pattern); if the output of `var(command) var(args)
tt(...)' contains var(pattern), then tt(label) is selected as the label
for the command variant. If none of the patterns match, the final
command label is selected and status 1 is returned.
The results are cached in the var(_cmd_variant) associative array so
the calling function can either look up the result in there or it can
pass the name of a parameter with the tt(-r) option which will be set
to the result.
If the `tt(-r) var(name)' is given, the var(label) picked is stored in
the parameter named var(name).
The results are also cached in the var(_cmd_variant) associative array
indexed by the name of the command run.
)
findex(_regex_arguments)
item(tt(_regex_arguments) var(name) var(specs) ...)(
This function is a compiler to generate a completion function. The
first argument specifies the name of the generated function while the
remaining arguments specify a completion as a set of regular
expressions with actions. The generated function has the structure of a
finite-state machine whose states correspond to the state (i.e. the
context) of the completion. This state machine uses a command line,
which comes from the concatenation of the tt(words) array up to the
current cursor position using null characters as separators with no extra
quotation. This is analysed and at the end the appropriate action is
executed.
item(tt(_regex_arguments) var(name) var(spec) ...)(
This function generates a completion function var(name) which matches
the specifications var(spec) tt(...), a set of regular expressions as
described below. After running tt(_regex_arguments), the function
var(name) should be called at the appropriate point.
The pattern to be matched is given by the contents of
the tt(words) array up to the current cursor position joined together
with null characters; no quotation is applied.
The arguments are grouped as sets of alternatives separated by `tt(|)',
which are tried one after the other until one matches. Each alternative
consists of a one or more specifications which are tried left to right,
with each pattern matched being stripped in turn from the command line
being tested, until all of the group succeeds or until one fails; in the
latter case, the next alternative is tried. This structure can be
repeated to arbitrary depth by using parentheses; matching proceeds from
inside to outside.
COMMENT(I think I've got this wrong, but I can't think what else it
could mean. Actually, it still doesn't mean very much.)\
A special procedure is applied if no test succeeds but the remaining
command line string contains no null character (implying the remaining
word is the one for which completions are to be generated). The
completion target is restricted to the remaining word and any
var(action)s for the corresponding patterns are executed. In this case,
nothing is stripped from the command line string. The order of
evaluation of the var(action)s can be determined by the tt(tag-order)
style; the various formats supported by tt(_alternative) can be used
in var(action). The var(descr) is used for setting up the array
parameter tt(expl).
Specification arguments take one of following forms, in which
metacharacters such as `tt(LPAR())', `tt(RPAR())', `tt(#)' and `tt(|)'
@ -4032,46 +4069,35 @@ should be quoted.
startitem()
item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is a primitive element, corresponding to one
state of the compiled state machine. The state is entered if
`tt((#b)LPAR()(#B))var(pattern)tt(RPAR()(#B))var(lookahead)tt(*)' matches
the command line string. If it matches, `var(guard)' is evaluated and
its return status is examined; if this is successful, the state is entered,
otherwise the test fails and other candidates are tried. The var(pattern)
string `tt([])' is guaranteed never to match.
If the test succeeds and the state is entered, the left part of the
command line string matched as var(pattern) is removed and the
next state is tried, proceeding from inside to outside and from left to
right.
If no test succeeds and the remaining command line string contains no null
character, the completion target is restricted to the remainder of the
command line string and var(action)s for the target are executed.
In this case, nothing is actually removed from the command line string
so that any previous or neighbouring state may also have var(actions)s.
var(actions)s evaluation are ordered by the tt(tag-order) style and specified
var(tag) by tt(_alternative). So, the various formats supported by
tt(_alternative) can be used in var(action). var(descr) is used for
setting up the array parameter tt(expl).
This is a single privitive component.
The function tests whether the combined pattern
`tt((#b)LPAR()(#B))var(pattern)tt(RPAR())var(lookahead)tt(*)' matches
the command line string. If so, `var(guard)' is evaluated and
its return status is examined to determine if the test has succeeded.
The var(pattern) string `tt([])' is guaranteed never to match.
The var(lookahead) is not stripped from the command line before the next
pattern is examined.
)
item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of the
command line string is also considered as part of the completion target.
command line string (i.e. the part already matched by previous patterns)
is also considered part of the completion target.
)
item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(tag)tt(:)var(descr)tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but the var(action)s of the
current and previous states are ignored even if the following state's
`var(pattern)' matches the empty string.
current and previously matched patterns are ignored even if the
following `var(pattern)' matches the empty string.
)
item(tt(LPAR()) var(spec) tt(RPAR()))(
This groups var(spec)s.
Parentheses may be used to groups var(spec)s; note each parenthesis
is a single argument to tt(_regex_arguments).
)
item(var(spec) tt(#))(
This allows any number of repetitions of var(spec).
)
item(var(spec) var(spec))(
This represents the concatenation of two var(spec)s.
The two var(spec)s are to be matched one after the other as described
above.
)
item(var(spec) tt(|) var(spec))(
Either of the two var(spec)s can be matched.
@ -4081,10 +4107,10 @@ enditem()
findex(_requested)
item(tt(_requested) [ tt(-x) ] [ tt(-12VJ) ] var(tag) [ var(name) var(descr) [ var(command) var(args) ... ] ])(
This function is called to decide whether a tag already registered by a
call to tt(_tags) (see below) is requested and hence completion should be
performed for it; it returns status zero if the tag is requested and
non-zero otherwise. This will usually be done in a loop such as the
following:
call to tt(_tags) (see below) has been requested by the user and hence
completion should be performed for it. It returns status zero if the
tag is requested and non-zero otherwise. The function is typically used
as part of a loop over different tags as follows:
example(_tags foo bar baz
while _tags; do
@ -4096,17 +4122,18 @@ while _tags; do
done)
Note that the test for whether matches were generated is not performed
until the end of the tt(_tags) loop. This is so that the user can specify
a set of tags to be tested at the same time in the tt(tag-order)
parameter.
until the end of the tt(_tags) loop. This is so that the user can set
the tt(tag-order) style to specify a set of tags to be tested at the
same time.
If the var(name) and the var(descr) are given, tt(_requested) calls the
tt(_description) function with these arguments, including the options.
If var(name) and var(descr) are given, tt(_requested) calls the
tt(_description) function with these arguments together with the options
passed to tt(_requested).
If the var(command) is given, the tt(_all_labels) function will be called
immediately with the same arguments. This is often useful to do both the
testing of the tag, getting the description for the matches and adding the
matches at once. For example:
If var(command) is given, the tt(_all_labels) function will be called
immediately with the same arguments. In simple cases this makes it
possible to perform the test for the tag and the matching in one go.
For example:
example(local expl ret=1
_tags foo bar baz
@ -4117,14 +4144,14 @@ while _tags; do
(( ret )) || break
done)
Note that this means that the var(command) has to accept the options
that have to be passed down to tt(compadd).
If the var(command) is not tt(compadd), it must nevertheless be prepared
to handle the same options.
)
findex(_retrieve_cache)
item(tt(_retrieve_cache) var(cache_identifier))(
This function retrieves completion information from the file given by
var(cache_identifier), stored in a directory specified by the
tt(cache-path) style (defaults to tt(~/.zsh/cache)). The return value
tt(cache-path) style which defaults to tt(~/.zsh/cache). The return value
is zero if retrieval was successful. It will only attempt retrieval
if the tt(use-cache) style is set, so you can call this function
without worrying about whether the user wanted to use the caching
@ -4142,110 +4169,112 @@ a quoted list of words in parentheses. For example, with the array
complete the string `tt(f)' to `tt(foo)' and the string `tt(b@n)' to
`tt(bar@news)'.
This function passes the `tt(-V)', `tt(-J)', `tt(-1)', `tt(-2)',
`tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)', `tt(-r)', `tt(-R)',
and `tt(-q)' options and their arguments to the tt(compadd) builtin
used to add the matches.
This function accepts the tt(compadd) options `tt(-V)', `tt(-J)',
`tt(-1)', `tt(-2)', `tt(-n)', `tt(-X)', `tt(-M)', `tt(-P)', `tt(-S)',
`tt(-r)', `tt(-R)', and `tt(-q)' and passes them on to the tt(compadd)
builtin used to add the matches.
)
findex(_setup)
item(tt(_setup) var(tag) [ var(group) ])(
This function expects a tag as its argument and sets up the special
parameters used by the completion system appropriately for the tag,
using styles such as tt(list-colors) and tt(last-prompt).
This function sets up the special
parameters used by the completion system appropriately for the var(tag)
given as the first argument. It uses the styles tt(list-colors),
tt(list-packed), tt(list-rows-first), tt(last-promp), tt(accept-exact),
tt(menu) and tt(force-list).
The optional var(group) gives the name of the group in which the
matches will be placed. If it is not given, the var(tag) is used as
The optional var(group) supplies the name of the group in which the
matches will be placed. If it is not given, the var(tag) is used as
the group name.
Note that this function is called automatically from tt(_description)
so that one normally doesn't have to call it explicitly.
This function is called automatically from tt(_description)
and hence is not normally called explicitly.
)
findex(_store_cache)
item(tt(_store_cache) var(cache_identifier) var(vars) ...)(
This function, when combined with tt(_retrieve_cache) and
tt(_cache_invalid), makes it easy to implement a caching layer for
your completion functions. If a completion function needs to perform
a costly operation in order to generate data which is used to
calculate completions, you can store that data in variables, and use
this function to dump the values of those variables to a file. Then,
if they are needed in subsequent shell invocations, they can be
retrieved quickly from that file via tt(_retrieve_cache), avoiding the
need for repeating the costly operation.
item(tt(_store_cache) var(cache_identifier) var(params) ...)(
This function, together with tt(_retrieve_cache) and
tt(_cache_invalid), implements a caching layer which can be used
in any completion functions. Data obtained by
costly operations are stored in parameters;
this function then dumps the values of those parameters to a file. The
data can then be retrieved quickly from that file via tt(_retrieve_cache),
even in different instances of the shell.
The var(cache_identifier) specifies the file which the data should be
dumped to, and is stored in a directory specified by the
tt(cache-path) style (defaults to tt(~/.zsh/cache)). The remaining
var(vars) arguments are the variables to dump to the file.
dumped to. The file is stored in a directory specified by the
tt(cache-path) style which defaults to tt(~/.zsh/cache). The remaining
var(params) arguments are the parameters to dump to the file.
The return value is zero if storage was successful. The function will
only attempt storage if the tt(use-cache) style is set, so you can
call this function without worrying about whether the user wanted to
use the caching layer.
If your completion function avoids calling _retrieve_cache when it
already has the completion data in the environment, it should probably
at least call tt(_cache_invalid) to check whether this data and the
data cached on disk is still valid.
The completion function may avoid calling tt(_retrieve_cache) when it
already has the completion data available as parameters.
However, in that case it should
call tt(_cache_invalid) to check whether the data in the parameters and
in the cache are still valid.
See the _perl_modules completion function for a simple example of
usage of this caching layer.
the usage of the caching layer.
)
findex(_tags)
item(tt(_tags) [ tt(-C) var(name) [ var(tags) ... ] ])(
If called with arguments, these are taken as the names of the tags for
the types of matches the calling completion function can generate in
the current context. These tags are stored internally and sorted by
using the tt(tag-order) style. Following calls to this function
without arguments from the same function will then select the first,
second, etc. set of tags requested by the user. To test if a certain
tag should be tried, the tt(_requested) function has to be called (see
above).
item(tt(_tags) [ [ tt(-C) var(name) ] var(tags) ... ])(
If called with arguments, these are taken to be the names of tags
valid for completions in the current context. These tags are stored
internally and sorted by using the tt(tag-order) style.
The return value is zero if at least one of the tags is requested and
non-zero otherwise.
Next, tt(_tags) is called repeatedly without arguments from the same
comletion function. This successively selects the first, second,
etc. set of tags requested by the user. The return value is zero if at
least one of the tags is requested and non-zero otherwise. To test if a
particular tag is to be tried, the tt(_requested) function should be
called (see above).
This function also accepts the tt(-C) option followed by a
var(name). This name is temporarily (i.e. not visible outside
tt(_tags)) stored in the argument field of the context name in the
tt(curcontext) parameter. This allows tt(_tags) to be made to use a more
specific context name without having to change and reset the
tt(curcontext) parameter (which would otherwise have the same effect).
If `tt(-C) var(name)' is given, var(name) is temporarily stored in the
argument field (the fifth) of the context in the tt(curcontext) parameter
during the call to tt(_tags); the field is restored on exit. This
allows tt(_tags) to use a more
specific context without having to change and reset the
tt(curcontext) parameter (which has the same effect).
)
findex(_values)
item(tt(_values) var(specs) ...)(
This is used to complete values (strings) and their arguments or
lists of such values. It can be used in two ways.
item(tt(_values) [ -O var(name) ] [ -s var(sep) ] [ -S var(sep) ] [ -C ] var(desc) var(spec) ...)(
This is used to complete arbitrary keywords (values) and their arguments,
or lists of such combinations.
If the first argument is the option `tt(-O) var(name)', this will be used
in the same way as by the tt(_arguments) function, in other words the
elements of the var(name) array will be given to calls to tt(compadd)
and when executing an action.
If the first argument is the option `tt(-O) var(name)', it will be used
in the same way as by the tt(_arguments) function. In other words, the
elements of the var(name) array will be passed to tt(compadd)
when executing an action.
Otherwise, if the first argument (or the first argument after the
`tt(-O) var(name)' option if that is used) is the option `tt(-s)', the
next argument is used as the character that separates multiple values.
Thus the values completed appear in the same word on the command line,
unlike completion using tt(_arguments).
If the first argument (or the first argument after `tt(-O) var(name)')
is `tt(-s)', the next argument is used as the character that separates
multiple values. This character is automatically added after each value
in an auto-removable fashion (see below); all values completed by
`tt(_values -s)' appear in the same word on the command line, unlike
completion using tt(_arguments). If this option is not present, only a
single value will be completed per word.
Normally, tt(_values) will only use the current word to determine
which values are already present on the command line. If the tt(-w)
option is given, the other arguments are used, too.
which values are already present on the command line and hence are not
to be completed again. If the tt(-w) option is given, other arguments
are examined as well.
The first argument (after the options and separator character if they
are given) is used as a string to print as a description before
listing the values.
The first non-option argument is used as a string to print as a
description before listing the values.
All other arguments describe the possible values and their
arguments in the same format used for the description of options by
the tt(_arguments) function (see above). The only differences are that
no minus or plus sign is required at the beginning, that
values can have only one argument and that those forms of actions
no minus or plus sign is required at the beginning,
values can have only one argument, and the forms of action
beginning with an equal sign are not supported.
The character separating a value from its argument can be set using the
option tt(-S) (like tt(-s), followed by the character to use as the
separator in the next argument). If this option is not used, the equal
sign will be used as the separator.
separator in the next argument). By default the equal
sign will be used to separator values and arguments.
Example:
@ -4258,31 +4287,29 @@ This describes three possible values: `tt(foo)', `tt(one)', and
`tt(two)'. The first is described as `tt(bar)', takes no argument
and may appear more than once. The second is described as
`tt(number)', may appear more than once, and takes one mandatory
argument described as `tt(first count)' for which no action is
specified so that it will not be completed automatically. The
argument described as `tt(first count)'; no action is
specified, so it will not be completed. The
`tt((two))' at the beginning says that if the value `tt(one)' is on
the line, the value `tt(two)' will not be considered to be a possible
completion anymore. Finally, the last value (`tt(two)') is described
the line, the value `tt(two)' will no longer be considered a possible
completion. Finally, the last value (`tt(two)') is described
as `tt(another number)' and takes an optional argument described as
`tt(second count)' which will be completed from the strings `tt(1)',
`tt(2)', and `tt(3)'. The tt(_values) function will complete lists of
these values separated by commas.
`tt(second count)' for which the completions (to appear after an
`tt(=)') are `tt(1)', `tt(2)', and `tt(3)'. The tt(_values) function
will complete lists of these values separated by commas.
Like tt(_arguments) this function temporarily adds another context
name component to the current context name while executing the
var(action). Here this name is just the name of the value for which
the argument is completed.
Like tt(_arguments), this function temporarily adds another context name
component to the arguments element (the fifth) of the current context
while executing the var(action). Here this name is just the name of the
value for which the argument is completed.
To decide if the descriptions for the values (not those for the
arguments) should be printed, the style tt(verbose) is used.
The style tt(verbose) is used to decide if the descriptions for the
values (but not those for the arguments) should be printed.
One last difference from tt(_arguments) is that this function uses the
associative array
tt(val_args) to report values and their arguments, although otherwise this
is the same as the tt(opt_args) association used by
tt(_arguments). This also means that the function calling tt(_values)
should declare the tt(state), tt(line), tt(context) and tt(val_args)
parameters as in:
The associative array tt(val_args) is used to report values and their
arguments; this works similarly to the tt(opt_args) associative array
used by tt(_arguments). Hence the function calling tt(_values) should
declare the local parameters tt(state), tt(line), tt(context) and
tt(val_args):
example(local context state line
typeset -A val_args)
@ -4292,45 +4319,43 @@ function the tt(context) parameter will be set to the name of the
value whose argument is to be completed.
Note also that tt(_values) normally adds the character used as the
separator between values as an auto-removable suffix so that users don't
have to type it themselves. But when using a `tt(->)var(string)' action
tt(_values) can't do that because the matches for the argument will be
separator between values as an auto-removable suffix (similar to a
`tt(/)' after a directory). However, this is not possible for a
`tt(->)var(string)' action as the matches for the argument are
generated by the calling function. To get the usual behaviour, the
implementor of the calling function has to add the suffix directly by
passing the options `tt(-qS) var(x)' (where var(x) is the separator
character specified with the tt(-s) option of tt(_values)) to the
function generating the matches or to the tt(compadd) builtin.
the calling function can add the separator var(x) as a suffix by
passing the options `tt(-qS) var(x)' either directly or indirectly to
tt(compadd).
Like tt(_arguments), tt(_values) supports the tt(-C) option in
which case you have to make the parameter tt(curcontext) local instead
The option tt(-C) is treated in the same way as it is by tt(_arguments).
In that case the parameter tt(curcontext) should be made local instead
of tt(context) (as described above).
)
findex(_wanted)
item(tt(_wanted) [ tt(-x) ] [ tt(-C) var(name) ] [ tt(-12VJ) ] var(tag) var(name) var(descr) var(command) var(args) ...)(
In many contexts, completion will generate one particular set of
matches (usually corresponding to a single tag); however, it is
In many contexts, completion can only generate one particular set of
matches, usually corresponding to a single tag. However, it is
still necessary to decide whether the user requires matches of this type.
This function is useful in such a case.
Like tt(_requested), it should be passed arguments as for tt(_description).
It calls tt(_tags) with the given var(tag) and if that returns zero
(so that the var(tag) is requested by the user) it calls
tt(_description). Hence to offer only one tag and immediately
use the description generated:
The arguments to tt(_wanted) are the same as those to tt(_requested),
i.e. arguments to be passed to tt(_description). However, in this case
the var(command) is not optional; all the processing of tags, including
the loop over both tags and tags labels and the generation of matches,
is carried out automatically by tt(_wanted). This also means that
tt(_wanted) should not be called inside a tt(_tags) loop.
Hence to offer only one tag and immediately add the corresponding
matches with the given description:
example(_wanted tag expl 'description' \
compadd matches...)
Unlike tt(_requested), however, tt(_wanted) cannot be called without
the var(command). This is because tt(_wanted) also implements the loop
over the tags, not just the one for the labels; conversely, it should not
be called in the middle of a tt(_tags) loop.
Note that, as for tt(_requested), the var(command) has to accept the options
that have to be passed down to tt(compadd).
Note that, as for tt(_requested), the var(command) must be able to
accept options to be passed down to tt(compadd).
Like tt(_tags) this function supports the tt(-C) option to give a
different name for the argument context field. The tt(-x) option has
different name for the argument context field. The tt(-x) option has
the same meaning as for tt(_description).
)
enditem()
@ -4365,9 +4390,12 @@ some attempt is made to decide which version of a command is present. For
example, completion for the tt(mount) command tries to determine the system
it is running on, while completion for many other utilities try to decide
whether the GNU version of the command is in use, and hence whether the
tt(--help) option is supported..
tt(--help) option is supported.
)
item(tt(X), tt(AIX), tt(BSD), ...)(
Completion and utility function for commands available only on some systems.
These are not arranged hierarchically, so, for example, both the
tt(Linux) and tt(Debian) directories, as well as the tt(X) directory,
may be useful on your system.
)
enditem()