mirrors/zsh
1
0
Fork 0
mirror of git://git.code.sf.net/p/zsh/code synced 2025-10-16 12:21:18 +02:00
Code Releases Activity

completion doc fixes and cleanup; _sort_tags updated (11047)

Browse source
This commit is contained in:
Sven Wischnowsky 2000-05-02 08:14:28 +00:00
parent 167c2881f5
commit e102702cd5
4 changed files with 222 additions and 242 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2000-05-02 Sven Wischnowsky <wischnow@informatik.hu-berlin.de>
* 11047: Completion/Core/_sort_tags, Doc/Zsh/compsys.yo,
Doc/Zsh/compwid.yo: completion doc fixes and cleanup; _sort_tags
updated
2000-05-01 Bart Schaefer <schaefer@zsh.org>
* 11043: Completion/Core/_expand, Completion/User/_nedit: Catch

29
Completion/Core/_sort_tags
View file

@ -1,28 +1,19 @@
#autoload
comptry arguments values
comptry -m '(|*-)argument-* (|*-)option-* values'
comptry options
case "$contexts" in
# Some silly examples commented out:
#
# *p[bgpn]m*) # change the order for file-completion
# comptry globbed-files directories
# comptry all-files
# ;;
# *:dvips,-o*) # automatic context set by _arguments
# comptry all-files
# return
# ;;
# *:kill,*)
# case "$curcontext" in
# *:*:*:kill:*)
# comptry processes
# return # this return ensures that we use only processes
# return 1 # this return ensures that we use only processes
# ;;
*)
comptry globbed-files
comptry directories
comptry all-files
;;
esac
# *:*:*:-command-*)
# comptry commands functions
# comptry builtins aliases
# ;; # no return, reserved-words and params after this
# esac
comptry "$@"
return 0

351
Doc/Zsh/compsys.yo
View file

@ -155,7 +155,7 @@ var(style), which must be one of those that perform completion, namely
tt(complete-word), tt(delete-char-or-list), tt(expand-or-complete),
tt(expand-or-complete-prefix), tt(list-choices), tt(menu-complete),
tt(menu-expand-or-complete), or tt(reverse-menu-complete). If the
tt(complist) module is loaded (see
tt(zsh/complist) module is loaded (see
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/complist Module))\
), the tt(menu-select) widget can be used, too. Note that the
@ -170,7 +170,7 @@ as usual.
)
item(tt(#compdef -K) var(widget-name) var(style) var(key-sequences) ...)(
This is similar to tt(-k), with the same var(style) and var(key-sequences)
arguments arguments, preceeded by a string giving the name of a widget.
arguments, preceeded by a string giving the name of a widget.
In this case only one var(key-sequences) argument may be given, but the
entire set of three arguments may be repeated with a different set of
arguments. In particular, the var(widget-name) must be distinct in each
@ -185,7 +185,7 @@ example(#compdef -K _foo_complete complete-word "^X^C" \
to `tt(^X^C)', and a widget tt(_foo_list) for listing, bound to `tt(^X^D)'.
)
item(tt(#autoload) [ var(options) ])(
This is used for files defining utility function that are not to be
This is used for files defining utility functions that are not to be
called directly as completion functions but should be loaded automatically
when invoked. Typically they are to be called from within one of the
completion functions.
@ -193,7 +193,7 @@ completion functions.
The var(options) will be given to the tt(autoload) builtin command
when making the function autoloaded. Note that the tt(-U) flag is
always used. Most often, this will be tt(+X) to force the function
being loaded immediately.
to be loaded immediately.
)
enditem()
@ -287,7 +287,7 @@ the name of an option when completing an argument to that option.
For the context a name consisting of multiple fields is built. This
name is then used to look up styles that can be used to configure the
completion system. Since it is not possible to build the whole context
name in advance, completion function may modify some of the fields and
name in advance, completion functions may modify some of the fields and
hence the context name used for lookup may vary during the same call
to the completion system.
@ -331,7 +331,7 @@ itemiz(\
The var(argument), describing which argument we are
completing. Normally this is either a string of the form
tt(argument-)var(n), where var(n) is the number of the argument or it
is a string of the form tt(-)var(opt)tt(-)var(n) when completing the
is a string of the form tt(option-)var(opt)tt(-)var(n) when completing the
var(n)'th argument of the option var(opt).
)
itemiz(\
@ -416,8 +416,8 @@ example(zstyle ':completion:*:*:kill:*:jobs' verbose no)
Note that the order in which styles are em(defined) does not matter; the
style mechanism uses the most specific possible match for a particular
style to determine the set of values. More precisely, strings are
preferred over patterns (for example, `tt(:completion:complete:foo)' is
more specific than `tt(:completion:complete:*')), and longer patterns are
preferred over patterns (for example, `tt(:completion::complete:foo)' is
more specific than `tt(:completion::complete:*')), and longer patterns are
preferred over shorter patterns.
As for tags, completion functions can use any number of styles, so
@ -731,7 +731,7 @@ values)
kindex(version, completion tag)
item(tt(version))(
used by tt(_call) to look up the command to run to determine the installed
version of various other commands (currently tt(diff) and tt(make)).
version of various other commands (such as tt(diff) and tt(make)).
)
kindex(warnings, completion tag)
item(tt(warnings))(
@ -773,11 +773,11 @@ accepted.
)
kindex(add-space, completion style)
item(tt(add-space))(
This style is used by the tt(_expand) completer. If it `true' (the
default), a space will be inserted after all words resulting forom the
This style is used by the tt(_expand) completer. If it is `true' (the
default), a space will be inserted after all words resulting from the
expansion (except for directory names which get a slash).
It is also used by tt(_prefix) completers to decide if a space should
It is also used by the tt(_prefix) completer to decide if a space should
be inserted before the suffix.
)
kindex(ambiguous, completion style)
@ -830,7 +830,7 @@ called, but for completion purposes one needs to ensure that the real
command is called.
For example, the function generating process IDs as matches uses this
style with the tt(processes) tag to generate the IDs to complete and iwhen
style with the tt(processes) tag to generate the IDs to complete and when
the tt(verbose) style is `true', it uses this style with the
tt(processes-list) tag to generate the strings to display. When using
different values for these two tags one should ensure that the process
@ -854,7 +854,7 @@ var(function) is the name of the completer to call, but the context
will contain the var(name) in the var(completer) field of the
context. If the var(name) starts with a hyphen, the string for the
context will be build from the name of the completer function as in
the first case with the var(name) will be appended to it. For example:
the first case with the var(name) appended to it. For example:
example(zstyle ':completion:*' completer _complete _complete:-foo)
@ -864,7 +864,7 @@ var(completer) field of the context. Normally, using the same
completer more than once makes only sense when used with the
`var(functions)tt(:)var(name)' form, because otherwise the context
name will be the same in all calls to the completer (possible
exception to this rule are the tt(_ignored) and tt(_prefix)
exceptions to this rule are the tt(_ignored) and tt(_prefix)
completers).
Note that the widget functions from the distribution that call the
@ -883,7 +883,7 @@ zstyle ':completion:predict:*' completer _complete)
The default value for this style is tt(_complete _ignored),
i.e. normally only completion will be done, first using the
tt(ignored-patterns) style and the tt($fignore) array and then without
ignoring matches because of these.
ignoring matches.
)
kindex(completions, completion style)
item(tt(completions))(
@ -906,7 +906,7 @@ should be 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(zstyle ':completion:*:list:::' condition 'NUMERIC != 1')
example(zstyle ':completion:*:list:::' condition '${NUMERIC:-1} != 1')
delaying will be done only if given an explicit numeric argument
other than `tt(1)'.
@ -938,7 +938,7 @@ position where the completion code left it.
)
kindex(disable-stat, completion style)
item(tt(disable-stat))(
This is used with the an empty tag by the function completing for the
This is used with an empty tag by the function completing for the
tt(cvs) command to decide if the tt(zsh/stat) module should be used to
generate only names of modified files in the appropriate places.
)
@ -1007,9 +1007,9 @@ example(zstyle ':completion:*:*:rm:*' file-patterns \
Another interesting example is to change the default behaviour that
makes completion first offer files matching the patterns given by the
calling function, then the directories and then all files. Many people
calling function, then directories and then all files. Many people
prefer to get both the files matching the given patterns and the
directories in the first try and all files as the second try. To
directories in the first try and all files at the second try. To
achieve this, one could do:
example(zstyle ':completion:*' file-patterns \
@ -1025,7 +1025,7 @@ The completion function that generates filenames as possible matches
uses this style with the tt(files) tag to determine in which order the
names should be listed and completed when using menucompletion. The
value may be one of `tt(size)' to sort them by the size of the file,
tt(links) to sort them by the number of links to the file,
`tt(links)' to sort them by the number of links to the file,
`tt(modification)' (or `tt(time)' or `tt(date)') to sort them by the last
modification time, `tt(access)' to sort them by the last access time, or
`tt(inode)' (or `tt(change)') to sort them by the last inode change
@ -1039,7 +1039,8 @@ If this is set for the tt(descriptions) tag, its value is used as a
string to display above matches in completion lists. The sequence
`tt(%d)' in this string will be replaced with a short description of
what these matches are. This string may also contain the sequences to
specify output attributes, such as `tt(%b)' and `tt(%s)'.
specify output attributes, such as `tt(%B)', `tt(%S)' and
`tt(%{)...tt(%})'.
For the same purpose, this style is also tested with the tags used
when matches are generated before it is tested for the
@ -1063,10 +1064,10 @@ tt(format) style laid out in columns. The descriptions are added as if
for the tag tt(warnings) so that you can use the tt(list-colors) style
for that tag to highlight them.
Here and in all other cases where the completion system uses `tt(%)'
sequences, the `tt(%)' may be followed by field width specifications as
described for the tt(zformat) builtin command from the tt(zutil)
module, see
The `tt(%)' for the sequences that are replaced by strings provided by
the completion functions like the `tt(%d)' may be followed by field
width specifications as described for the tt(zformat) builtin command
from the tt(zutil) module, see
ifzman(zmanref(zshmodules))\
ifnzman(noderef(The zsh/zutil Module))\
.
@ -1084,10 +1085,10 @@ kindex(group-name, completion style)
item(tt(group-name))(
The completion system can put different types of matches in different
groups which are then displayed separately in the list of possible
completions. This style can be use to give the names for these groups
completions. This style can be used to give the names for these groups
for particular tags. For example, in command position the completion
system generates names of builtin and external commands, names of
aliases and shell functions and reserved words as possible
aliases, shell functions and parameters and reserved words as possible
completions. To have the external commands and shell functions listed
separately, one can set:
@ -1232,9 +1233,10 @@ tt(ALWAYS_LAST_PROMPT) option.
)
kindex(list, completion style)
item(tt(list))(
This is used by the tt(_history_complete_word) bindable command
(context `tt(:completion:history-words)') and by the
tt(incremental-complete-word) widget (context `tt(:completion:incremental)).
This style is used by the tt(_history_complete_word) bindable command
(using the context prefix `tt(:completion:history-words)') and by the
tt(incremental-complete-word) widget (using the context prefix
`tt(:completion:incremental)).
The tt(_history_complete_word) bindable command uses this style to
decide if the available matches should be shown.
@ -1298,7 +1300,7 @@ of lines. A `tt(%m)' or `tt(%M)' will be replaced by the number of the
last match shown and the total number of matches and `tt(%p)' and
`tt(%P)' will be replaced by `tt(Top)' when at the beginning of the
list, `tt(Bottom)' when at the end and the position shown in percent
of the total length. In each of these cases the form with the
of the total length otherwise. In each of these cases the form with the
uppercase letter is replaced by a string of fixed width, padded to the
right with spaces. As
usual, the `tt(%S)', `tt(%s)', `tt(%B)', `tt(%b)', `tt(%U)', `tt(%u)',
@ -1330,7 +1332,8 @@ tt(only), tt(_match) will try to generate matches without inserting a
`tt(*)' at the cursor position. If set to any other non-empty value,
it will first try to generate matches without inserting the `tt(*)'
and if that yields no matches, it will try again with the `tt(*)'
inserted.
inserted. If it is unset or set to the empty string, matching will
only be done with the `tt(*)' inserted.
)
kindex(matcher, completion style)
item(tt(matcher))(
@ -1360,7 +1363,8 @@ case-insensitive completion only when using the tt(_complete)
completer, one would do:
example(zstyle ':completion:*' completer _complete _prefix
zstyle ':completion:*:complete:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}')
zstyle ':completion:*:complete:*' matcher-list \
'' 'm:{a-zA-Z}={A-Za-z}')
Note that the tt(completer) style allows to give user-defined names to
use in the context instead of the name of the completer.
@ -1483,7 +1487,7 @@ matches generated on the first attempt will be used again.
)
kindex(old-menu, completion style)
item(tt(old-menu))(
This is used by the tt(_oldlist) completer. Here it controls how menu
This is used by the tt(_oldlist) completer. It controls how menu
completion behaves when a completion has already been inserted and the
user types a standard completion key type such as tt(TAB). The default
behaviour of tt(_oldlist) is that menu completion always continues
@ -1496,7 +1500,7 @@ For example, suppose you type tt(^Xc) to generate a list of corrections,
and menu completion is started in one of the usual ways. Usually, typing
tt(TAB) at this point would start trying to complete the line as it now
appears. With tt(_oldlist), it instead continues to cycle through the
list of completions.
list of corrections.
)
kindex(original, completion style)
item(tt(original))(
@ -1515,7 +1519,8 @@ This style is used when completing arguments of the Debian `tt(dpkg)'
program. It contains an override for the default package set
for a given context. For example,
example(zstyle ':completion:*:complete:dpkg:option--status-1:' packageset avail)
example(zstyle ':completion:*:complete:dpkg:option--status-1:*' \
packageset avail)
causes available packages, rather than only installed packages,
to be completed for `dpkg --status'.
@ -1596,9 +1601,9 @@ enditem()
)
kindex(remove-all-dups, completion style)
item(tt(remove-all-dups))(
The tt(_history_complete_word) bindable command uses this to decide if
all duplicate matches should be removed, rather than just consecutive
duplicates.
The tt(_history_complete_word) bindable command and the tt(_history)
completer use this to decide if all duplicate matches should be
removed, rather than just consecutive duplicates.
)
kindex(select-prompt, completion style)
item(tt(select-prompt))(
@ -1681,12 +1686,12 @@ tt(_expand) completer will do nothing.
)
kindex(substitute, completion style)
item(tt(substitute))(
If this is unset or set to the empty string, the tt(_expand) completer
will first try to expand all substitutions in the string (such as
`tt($LPAR()...RPAR())' and `tt(${...})'). If this is set to an
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
This style controls if the tt(_expand) completer will first try to
expand all substitutions in the string (such as `tt($LPAR()...RPAR())'
and `tt(${...})'). It should be set to an non-empty string which is
an expression usable inside a `tt($((...)))' arithmetical
expression. Expansion of substitutions will be done if the expression
evaluates to `tt(1)'. For example, with
example(zstyle ':completion:*:expand:::' substitute '${NUMERIC:-1} != 1')
@ -1705,12 +1710,12 @@ an exception to this behavior.)
For example:
example(zstyle ':completion:*:complete:gunzip:*' tag-order \
arguments options)
example(zstyle ':completion:*:complete:-command-:*' tag-order \
'commands functions')
specifies that completion after tt(gunzip) should offer completions for
both arguments and options immediately, instead of offering first
arguments and then option as usual.
specifies that completion in command position after tt(gunzip) should
offer only completions for external commands and shell functions
immediately.
In addition to tag names, each string in the value may take one of the
following forms:
@ -1778,7 +1783,7 @@ Makes completion in command position happen only if the string on the
line is not empty (this is tested using the tt(PREFIX)
parameter which is special in completion widgets, see
ifzman(zshcompwid)\
ifnzman(the section noderef(Completion System))
ifnzman(noderef(Completion Widgets))
for a description of these special parameters).
)
enditem()
@ -1805,14 +1810,14 @@ is set to exclude functions starting with an underscore from the set
of possible matches. If none of the generated matches match the string
on the line, the completion system will use the second value of the
tt(tag-order) style and complete functions names again, but this time
using so name tt(functions) to look up styles, so that the
using the name tt(functions) to look up styles, so that the
tt(ignored-patterns) style is not used and all function names
are considered.
Of course, this can also be used to split the matches for one tag into
different groups. For example:
example(zstyle ':completion:*' tag-order \
example(zstyle ':completion:*' tag-order \
'options:-long:long\ options
options:-short:short\ options
options:-single-letter:single\ letter\ options'
@ -1832,7 +1837,7 @@ tt(matcher-list) style offers something similar, but it is tested very
early in the completion system and hence can't be set for single
commands nor for more specific contexts. So, to make completion for
the arguments of the command tt(foo), and only for this command, first
try normal completion with out any match specification and, if that
try normal completion without any match specification and, if that
generates no matches, try again with case-insensitive matching, one
could do:
example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case'
@ -1847,9 +1852,12 @@ styles. I.e. in this second attempt, the value for the tt(matcher)
style from the second call to tt(zstyle) in the example is used
to make completion case-insensitive.
If no style has been defined for a context, the strings `tt(arguments
values)' and `tt(options)' plus all tags offered by the completion
function will be used to provide a sensible default behavior.
If no style has been defined for a context, the strings
`tt((|*-)argument-* (|*-)option-* values)' and `tt(options)' plus all
tags offered by the completion function will be used to provide a
sensible default behavior that makes arguments (normal ones or
arguments to options) for most commands be completed before option
names.
)
kindex(use-compctl, completion style)
item(tt(use-compctl))(
@ -1933,8 +1941,9 @@ correction if that doesn't generate any matches:
example(zstyle ':completion:*' completer _complete _correct)
after calling tt(compinit). The default value for this style
is `tt(_complete)', i.e. normally only ordinary
completion is tried. The tt(_main_complete) function uses the return
is `tt(_complete _ignored)', i.e. normally only ordinary
completion is tried, first using the tt(ignored-patterns) style and
then without using it. The tt(_main_complete) function uses the return
value of the completer functions to decide if other completers should be
called. If the return value is zero, no other completers are tried and the
tt(_main_complete) function returns.
@ -1959,8 +1968,7 @@ handled specially. These are:
startitem()
kindex(-equal-, completion context)
item(tt(-equal-))(
for completion after an equal sign, other than one occurring in a
shell-variable assignment.
for completion of words beginning with an equal sign
)
kindex(-tilde-, completion context)
item(tt(-tilde-))(
@ -2057,7 +2065,7 @@ corrected completions are found, the completer will normally start
menucompletion allowing you to cycle through these strings.
This completer uses the tags tt(corrections) and tt(original) when
generating the possible coprrections and the original string. The
generating the possible corrections and the original string. The
tt(format) style for the former may contain the additional sequences
`tt(%e)' and `tt(%o)' which will be replaced by the number of errors
accepted to generate the corrections and the original string,
@ -2142,10 +2150,10 @@ The format string for tt(all-expansions) and for tt(expansions) may
contain the sequence `tt(%o)' which will be replaced by the original
string from the line.
Which kind of expansion is tried is controlled by the tt(substitute)
and tt(glob) styles. Note that neither of these has a default value so
that they have to be set to make tt(_expand) generate any expansions
at all.
Which kind of expansion is tried is controlled by the tt(substitute),
tt(glob) and tt(subts-globs-only) styles. Note that neither of these
has a default value so that they have to be set to make tt(_expand)
generate any expansions at all.
In a different mode selected by the tt(completions) style, all
em(completions) generated for the string on the line are inserted.
@ -2193,7 +2201,7 @@ called.
For example, consider this global tt(completer) style:
example(zstyle ':completion:*' completer \
example(zstyle ':completion:*' completer \
_complete _prefix _correct _prefix:foo)
This makes the tt(_prefix) completer try normal completion with the
@ -2201,7 +2209,7 @@ suffix ignored. If that doesn't generate any matches and neither does
the call to the tt(_correct) completer after it, then tt(_prefix) will
be called a second time and will now only try correction with the
suffix ignored. If you want to use tt(_prefix) as the last resort and
want it to try only normal completion, you need to call:
want it to try only normal completion, you can use:
example(zstyle ':completion:*' completer _complete ... _prefix
zstyle ':completion::prefix:*' completer _complete)
@ -2352,7 +2360,7 @@ Note that, depending on the control flow in the completion functions
called, the information about the styles may be
incomplete. I.e. depending on the settings for some styles other
styles may be used, and, depending on the user's settings, only the
first sort of styles may be detected by tt(_complete_help).
first sort of styles may be found by tt(_complete_help).
)
findex(_complete_debug (^X?))
item(tt(_complete_debug (^X?)))(
@ -2369,7 +2377,7 @@ cindex(completion system, utility functions)
Descriptions follow for utility functions that may be
useful when writing completion functions. Most of these reside in the
tt(Core) subdirectory except where noted. Like the example
tt(Core) subdirectory. Like the example
functions for commands in the distribution, the utility functions
generating matches all follow the convention of returning zero if they
generated completions and non-zero if no matching completions could be
@ -2381,7 +2389,7 @@ offered by the tt(_main_complete) function. The arrays
tt(compprefuncs) and tt(comppostfuncs) may be set to contain names of
functions that are to be called immediately before or after completion
has been tried. The functions will only be called once, unless they
put themselves into the array again.
put themselves into the arrays again.
startitem()
findex(_funcall)
@ -2442,9 +2450,10 @@ options usable for tt(compadd) in the array with the given var(name)
which guarantee that the matches are generated as requested by the
user. The styles tested are: tt(format) (which is first tested for the
given tag and then for the tt(descriptions) tag if that isn't
defined), tt(hidden) and tt(group-name) (the last two are tested only
for the tag given as the first argument). This function also calls the
tt(_setup) function which tests some more styles.
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.
The format string from the style (if any) will be modified so that the
sequence `tt(%d)' is replaced by the var(descr) given as the third
@ -2523,7 +2532,7 @@ labels are to be used, a non-zero status is returned.
The tt(-12JV) options and the first three arguments are given to the
tt(_desciption) function using the tag label instead of the first
argument is appropriate. The var(options) given after the var(descr)
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
@ -2535,7 +2544,7 @@ 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.
A normal use of this function for the tag labels for the tag tt(foo)
A normal use of this function for the tag labels of the tag tt(foo)
looks like this:
example(local expl ret=1
@ -2642,7 +2651,7 @@ findex(_alternative)
item(tt(_alternative) [ tt(-C) var(name) ] var(specs) ...)(
This function is useful if you offer multiple tags and building the
matches for them is easy enough. It basically implements a loop like
the one described for the tt(_tags) function above above.
the one described for the tt(_tags) function above.
The tags to use and what to do if the tags are requested are described
using the var(specs) which are of the form:
@ -2671,7 +2680,7 @@ Like tt(_tags) this function supports the tt(-C) option to give a
different name for the argument context field.
)
findex(_describe)
item(tt(_describe) var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
item(tt(_describe) [ tt(-o) ] var(descr) var(name1) [ var(name2) ] var(opts) ... tt(-)tt(-) ...)(
This function can be used to add options or values with descriptions
as matches. The var(descr) is taken as a string to display above
the matches if the tt(format) style for the tt(descriptions) tag is set.
@ -2682,7 +2691,7 @@ completions with their descriptions (with the description separated
by a colon from the completion string). If the second array is given,
it should have the same number of elements as the first one and these
elements are added as possible completions instead of the strings from
the first array. In any case, however, the completion list will show
the first array. In any case, however, the completion list will contain
the strings from the first array.
Any number of array/option sequences may be given separated by
@ -2775,7 +2784,7 @@ absolute pathname.
item(tt(-F))(
This option from the tt(compadd) builtin gives direct control over which
filenames should be ignored. If no such option is given, the
tt(ignored-suffixes) style is used.
tt(ignored-patterns) style is used.
)
enditem()
@ -2784,7 +2793,7 @@ These functions also accept the `tt(-J)', `tt(-V)', `tt(-1)',
`tt(-r)', and `tt(-R)' options from the tt(compadd) builtin.
Finally, the tt(_path_files) function uses the styles tt(expand),
tt(ambiguous) and tt(special-dirs) with the tt(paths) tag.
tt(ambiguous) and tt(special-dirs) and tt(file-sort).
)
findex(_parameters)
item(tt(_parameters))(
@ -2812,9 +2821,6 @@ widget locally sets the options it needs.
)
findex(_arguments)
item(tt(_arguments) var(specs) ...)(
This function resides in the tt(Base) subdirectory of the example
completion system because it is not used by the core system.
This function can be used to complete words on the line by simply
describing the arguments the command on the line gets. The description
is given as arguments to this function, with each var(spec) describing
@ -2862,8 +2868,8 @@ multiple arguments. In the first form all following words on the line
are to be completed as described by the var(action), in the second
form all words up to a word matching the given var(pattern) are to be
completed using the var(action). The `tt(*)' or the var(pattern) may
also be separated from the var(message) by two or three colons. With
two colons the tt(words) special array and the tt(CURRENT) special
also be separated from the var(message) by two or three colons. In
this case, the tt(words) special array and the tt(CURRENT) special
parameter are modified to refer only to the words after the option
(with two colons) or to the words covered by this description (with
three colons) during the execution or evaluation of the
@ -2874,14 +2880,17 @@ In the simplest form the var(opt-spec) is just the option name
beginning with a minus or a plus sign, such as `tt(-foo)'. If the
command accepts the option both with a leading minus and a plus sign,
one can use either tt(-+foo) or tt(+-foo) to define both options at
once. In this
case, the first argument for the option (if any) has to come as a
once.
In these
cases, the first argument for the option (if any) has to come as a
separate word directly after the option and the option may appear only
once on the line (and if it is already on the line, the option name
once on the line (and if it is already on the line and to the left of
the cursor, the option name
will not be offered as a possible completion again). If the first
argument for the option has to come directly after the option name
em(in the same word), a minus sign should be added to the end of the
var(opt-spec), as in `tt(-foo-)'. If the first argument may be given
var(opt-spec), as in `tt(-foo-:)var(...)'. If the first argument may be given
in one string with the option name, but may also be given as a
separate argument after the option, a plus sign should be used
instead. If the argument may be given as the next string or in same
@ -2961,7 +2970,7 @@ are taken from the array parameter tt(expl) which will be set up
before executing the var(action) and hence may be used in it (normally
in an expansion like `tt($expl[@])').
If the var(action) starts with `tt(= )' (an equals sign followed by a
If the var(action) starts with `tt(= )' (an equal sign followed by a
space), tt(_arguments) will insert the contents of the var(argument)
field of the current context as the new first element in the tt(words)
special array and increments the value of the tt(CURRENT) special
@ -3002,14 +3011,14 @@ the values. For options that have more than one argument these are
given as one string, separated by colons. All colons in the original
arguments are preceded with backslashes.
The parameter `tt(context)'
will be set to the automatically created context names. This are either
strings of the form `tt(option)var(-opt)tt(-)var(n)' for the var(n)'th argument
of the option var(-opt), or a string of the form `tt(argument-)var(n)'
for the var(n)'th argument (for rest arguments the var(n) is the
string `tt(rest)'). For example, when completing the argument of the tt(-o)
option, the name is `tt(option-o-1)' and for the second normal (non-option-)
argument it is `tt(argument-2)'.
The parameter `tt(context)' will be set to the automatically created
context names. These are either strings of the form
`tt(option)var(-opt)tt(-)var(n)' for the var(n)'th argument of the
option var(-opt), or strings of the form `tt(argument-)var(n)' for
the var(n)'th argument (for rest arguments the var(n) is the string
`tt(rest)'). For example, when completing the argument of the tt(-o)
option, the name is `tt(option-o-1)' and for the second normal
(non-option-) argument it is `tt(argument-2)'.
Also, during the evaluation of the var(action), the context name in
the tt(curcontext) parameter will be changed by appending the same
@ -3105,7 +3114,7 @@ Example:
example(_arguments '-l+:left border:' \
'-format:paper size:(letter A4)' \
'*-copy:output file:_files::resolution:(300 600)' \
':postscript file:_files -g *.(ps|eps)' \
':postscript file:_files -g \*.\(ps\|eps\)' \
'*:page number:')
This describes three options: `tt(-l)', `tt(-format)', and
@ -3136,17 +3145,17 @@ tt(_arguments) separated by single hyphens. The specifications before
the first hyphen are shared by all sets given after the first
hyphen. The first word in every other set gives the name of the
set. This name may appear in exclusion lists in the specifications,
either alone or before (with a `tt(-)' between the name and the rest)
one of the possible values described for tt(_arguments) above.
either alone or before one of the possible values described for
tt(_arguments) above (with a `tt(-)' between the name and the rest).
For example:
example(_argument_sets \
-a \
- set1 \
-c \
- set2 \
-d \
example(_argument_sets \
-a \
- set1 \
-c \
- set2 \
-d \
':arg:(x2 y2)')
This defines two sets. When the command line contains the option
@ -3238,13 +3247,13 @@ of tt(context) (as described above).
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 a generated function while 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 state corresponds to the state (i.e. the
finite-state machine whose states corresponds to the state (i.e. the
context) of the completion. This state machine uses a command line,
which comes from concatentating the tt(words) array up to the current
cursor position using null characters as a separator with no extra
cursor position using null characters as separators with no extra
quotation. This is analysed and at the end the appropriate action is
executed.
@ -3255,7 +3264,7 @@ should be quoted.
startitem()
item(tt(/)var(pattern)tt(/) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
This is a primitive element, corresponding to one
state of the compiled state machine. The state is entered if the pattern
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 is matched, `var(guard)' is evaluated and
its return status is examined; if this is successful, the state is entered,
@ -3263,36 +3272,36 @@ else 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
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 evaluated.
command line string and var(action)s for the target are evaluated.
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.
so that any previous or neighbouring state may also have var(actions)s.
)
item(tt(/)var(pattern)tt(/+) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but the left part of
command line string is also considered as part of the completion target.
)
item(tt(/)var(pattern)tt(/-) [tt(%)var(lookahead)tt(%)] [tt(-)var(guard)] [tt(:)var(action)])(
This is similar to `tt(/)var(pattern)tt(/) ...' but `var(action)'s of the
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.
)
item(tt(LPAR()) var(spec) tt(RPAR()))(
This groups `var(spec)'.
This groups var(spec)s.
)
item(var(spec) tt(#))(
This allows any number of repetitions of `var(spec)'.
This allows any number of repetitions of var(spec).
)
item(var(spec) var(spec))(
This represents the concatenation of two `var(spec)'s.
This represents the concatenation of two var(spec)s.
)
item(var(spec) tt(|) var(spec))(
Either of two `var(spec)'s can be matched.
Either of the two var(spec)s can be matched.
)
enditem()
)
@ -3343,56 +3352,54 @@ to show how functions that sort tags can be implemented.
Inside such functions the name of the current context can
be accessed using the tt(curcontext) parameter. For example, the
function generating file names (called tt(_files)) in the completion
system is often called to generate only filenames matching a given
glob pattern, in which case it uses the tags tt(globbed-files),
tt(directories), and tt(all-files). This means that the function
offers to generate filenames matching the pattern, names of
directories or all filenames as possible matches. Example:
function used in command position (called tt(_command_names)) in the
completion can generate names of external and builtin commands, names
of shell functions, aliases and parameters and reserved words.
Example:
example(_sort_tags() {
case $curcontext in
(*::dvips:*)
comptry globbed-files directories
comptry all-files
(*:-command-:*)
comptry commands functions
comptry builtins aliases
;;
(*)
comptry globbed-files
comptry directories
comptry all-files
.comptry "$@"
;;
esac
return 1
})
Every call to the tt(comptry) function (actually a builtin
command defined by the tt(zsh/computil) module) gives a
set of tags to use; as soon as one of the completion system produces
some matches for one set,
subsequent sets have no effect. Hence in the example
this means that for the tt(dvips) command on the first attempt the
names of DVI files and directories will be generated (first call to
tt(comptry)). If none of those names match the string from the command
line the completion function will generate all filenames as
possible matches (second call to tt(comptry)).
Every call to the tt(comptry) builtin command gives a
set of tags to use; as soon as completion system produces
some matches for one set, subsequent sets have no effect. Hence in
the example this means that in command position on the first attempt
only names of external commands and shell functions will be generated
(first call to tt(comptry)). If none of those names match the string
from the command line the completion function will generate names of
builtin commands and aliases as possible matches (second call to
tt(comptry)).
For all other context names the second case-pattern matches, so that
normally the completion functions will only try the filenames matching
the glob pattern (if any glob pattern is used). If that doesn't yield
any matches, names of directories are generated, and if that doesn't
yield any matching names either, all filenames will be generated.
normally the completion functions will try all tags offered. The
return value means that the calling function, tt(_tags), will not use
all offered tags as a default, so in the first case names or
parameters and reserved words will never be completed.
In every context the function may call tt(comptry) as
often as it wants. Also, every string may be given as argument, even
if no tag with such a name was offered by the completion
function. This allows one to give a preferred ordering for some common
tag sets without having to worry about sensible patterns for context
names. For example, many completion functions can generate both
arguments and option names for commands. These functions normally use
the tags tt(arguments) and tt(options). Depending on your preference
you may write in your sorting function:
In every context the function may call tt(comptry) as often as it
wants. Also, every string may be given as argument, even if no tag
with such a name was offered by the completion function. This allows
one to give a preferred ordering for some common tag sets without
having to worry about sensible patterns for context names. For
example, many completion functions can generate both arguments and
option names for commands. These functions normally use the tags
like tt(argument-)var(num), tt(option-)var(name)tt(-)var(num) and
tt(options). Depending on your preference you may write in your
sorting function:
example(_sort_tags() {
comptry arguments options
comptry -m '(|*-)argument-* (|*-)option-* options'
case $curcontext in
...
esac
@ -3401,7 +3408,7 @@ example(_sort_tags() {
or
example(_sort_tags() {
comptry arguments
comptry -m '(|*-)argument-* (|*-)option-*'
comptry options
case $curcontext in
...
@ -3416,34 +3423,6 @@ for the argument, which normally means that you have to type the
hyphen the option names start with yourself to see the list of option
names that can be completed.
Since the completion functions are free to choose the tag names they
use, there can't be a complete list. So to make sure that all types of
matches are eventually tried as completions, one should use a call to
tt(comptry) with all arguments at the end of the sorting function. For
those contexts where one really wants to make sure that certain tags are
never used one can then use a call to tt(return) to circumvent that
last tt(comptry). For example:
example(_sort_tags() {
...
case $curcontext in
(*::kill:*)
comptry processes
return
;;
esac
comptry "$@"
})
The completion function for the tt(kill) builtin command offers the
tags tt(jobs) and tt(processes) which represent job references
(e.g. `tt(%1)') and process identifiers respectively. The function
above makes sure that for this builtin command only process
identifiers are generated as possible matches by using only the
tt(processes) tag in a call to tt(comptry). The immediate call to
tt(return) then makes sure that the default tt(comptry) at the end is
not executed.
With the tt(-s) option, each tag given to tt(comptry) will be put in a
separate set. With the tt(-m) option, the arguments are treated in the
same way as the the values for the tt(tag-order) style (except for the

78
Doc/Zsh/compwid.yo
View file

@ -255,7 +255,7 @@ item(tt(list_lines))(
This gives the number of lines that are needed to display the full
list of completions. Note that to calculate the total number of lines
to display you need to add the number of lines needed for the command
line to this value, this is available as the value of the tt(BLINES)
line to this value, this is available as the value of the tt(BUFFERLINES)
special parameter.
)
vindex(last_prompt, compstate)
@ -272,9 +272,9 @@ line. On entry to the widget function, if it is unset the command line is
not to be changed; if set to tt(unambiguous), any prefix common to all
matches is to be inserted; if set to tt(automenu-unambiguous), the
common prefix is to be inserted and the next invocation of the
completion code may start menu-completion (due to the tt(AUTO_MENU)
option being set); if set to tt(menu) or tt(automenu) menu-completion
will be started for the matches currently generated due to (in the
completion code may start menucompletion (due to the tt(AUTO_MENU)
option being set); if set to tt(menu) or tt(automenu) menucompletion
will be started for the matches currently generated (in the
latter case this will happen because the tt(AUTO_MENU) is set).
On exit it may be set to any of the values above (where setting it to
@ -282,14 +282,14 @@ the empty string is the same as unsetting it), or to a number, in which
case the match whose number is given will be inserted into the command line.
Negative numbers count backward from the last match (with `tt(-1)'
selecting the last match) and out-of-range values are wrapped
around, so that a value of zero selects the last match group and a value
around, so that a value of zero selects the last match and a value
one more than the maximum selects the first. Unless the value of this
key ends in a space, the match is inserted as in a menu-completion,
key ends in a space, the match is inserted as in a menucompletion,
i.e. without automatically appending a space.
Both tt(menu) and tt(automenu) may also specify the the number of the
match to insert, given after a colon. For example, `tt(menu:2)' says
to start menu-completion, beginning with the second match.
to start menucompletion, beginning with the second match.
Finally, it may also be set to tt(all), which makes all matches
generated be inserted into the line.
@ -339,6 +339,9 @@ item(tt(exact))(
Controls the behaviour when the tt(REC_EXACT) option is set. It will be
set to tt(accept) if an exact match would be accepted, and will be unset
otherwise.
If it was set when at least one match equal to the string on the line
was generated, the match is accepted.
)
vindex(exact_string, compstate)
item(tt(exact_string))(
@ -348,21 +351,21 @@ vindex(pattern_match, compstate)
item(tt(pattern_match))(
Locally controls the behaviour given by the tt(GLOB_COMPLETE) option.
Initially it is set to `tt(*)' if and only if the option is set.
The completion widget may set it to either of these two values, or to any
The completion widget may set it to this value, to an empty string
(which has the same effect as unsetting it), or to any
other non-empty string. If it is non-empty, unquoted metacharacters on the
command line will be treated as patterns; if it is `tt(*)', then
additionally a wildcard `tt(*)' is assumed at the cursor position; if
it is empty or unset, metacharacters will be treated literally.
Note that the matcher specifications given globally or to one of the
builtin commands adding matches are not used if this is set to a
non-empty string.
Note that the matcher specifications given to the tt(compadd) builtin
command are not used if this is set to a non-empty string.
)
vindex(pattern_insert, compstate)
item(tt(pattern_insert))(
Normally this is set to tt(menu), which specifies that menu-completion will
Normally this is set to tt(menu), which specifies that menucompletion will
be used whenever the matches were generated using pattern matching. If it
is set to any other non-empty string by the user and menu-completion is
is set to any other non-empty string by the user and menucompletion is
not selected by other option settings, the code will insert an
unambiguous string for the generated matches as with normal completion.
)
@ -394,8 +397,8 @@ xitem([ tt(-i) var(ignored-prefix) ] [ tt(-I) var(ignored-suffix) ])
xitem([ tt(-W) var(file-prefix) ] [ tt(-d) var(array) ])
xitem([ tt(-J) var(name) ] [ tt(-V) var(name) ] [ tt(-X) var(explanation) ])
xitem([ tt(-r) var(remove-chars) ] [ tt(-R) var(remove-func) ])
xitem([ tt(-M) var(match-spec) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
item([ tt(-D) var(array) ] [ tt(--) ] [ var(words) ... ])(
xitem([ tt(-D) var(array) ] [ tt(-O) var(array) ] [ tt(-A) var(array) ])
item([ tt(-M) var(match-spec) ] [ tt(--) ] [ var(words) ... ])(
This builtin command can be used to add matches directly and control
all the information the completion code stores with each possible
@ -417,7 +420,7 @@ that is considered part of the match but that should not be shown when
listing completions, given with the tt(-p) option; for example,
functions that do filename generation might specify
a common path prefix this way. var(<word>) is the part of the match that
should appear in the list of completions, one of the tt(words) given at the
should appear in the list of completions, one of the var(words) given at the
end. The suffixes var(<hsuf>), var(<asuf>) and var(<isuf>) correspond to
the prefixes var(<hpre>), var(<apre>) and var(<ipre>) and are given by the
options tt(-s), tt(-S) and tt(-I), respectively.
@ -431,7 +434,7 @@ string given is not considered as part of the match and any shell
metacharacters in it will not be quoted when the string is inserted.
)
item(tt(-S) var(suffix))(
Like tt(-P) but gives a string to be inserted after the match.
Like tt(-P), but gives a string to be inserted after the match.
)
item(tt(-p) var(hidden-prefix))(
This gives a string that should be inserted into the command line before the
@ -744,9 +747,11 @@ characters in the string to be completed (referred to here as the
command line) map onto the characters in the list of matches produced by
the completion code (referred to here as the trial completions). Note
that this is not used if the command line contains a glob pattern and
the tt(GLOB_COMPLETE) option is set.
the tt(GLOB_COMPLETE) option is set or the tt(pattern_match) of the
tt(compstate) special association is set to a non-empty string.
The var(spec) consists of one or more matching descriptions separated by
The var(spec) given as argument to the tt(-m) option consists of one
or more matching descriptions separated by
whitespace. Each description consists of a letter followed by a colon,
then the patterns describing which character sequences on the line match
which character sequences in the trial completion. Any sequence of characters not
@ -777,7 +782,7 @@ anchor can occur anywhere, but must match in both the command line and
trial completion strings.
If no var(lpat) is given, but a var(ranchor), this matches the gap
between substrings matched by var(lanchor) an var(ranchor). Unlike
between substrings matched by var(lanchor) and var(ranchor). Unlike
var(lanchor), the var(ranchor) only needs to match the trial
completion string.
)
@ -862,25 +867,25 @@ To make uppercase letters match the lowercase forms as well:
example(compadd -M 'm:{a-zA-Z}={A-Za-z}' ... )
A nice example for the use of tt(*) patterns is partial word
completion. Sometimes you would like to make strings like tt(c.s.u)
complete to strings like tt(comp.source.unix), i.e. the word on the
completion. Sometimes you would like to make strings like `tt(c.s.u)'
complete to strings like `tt(comp.source.unix)', i.e. the word on the
command line consists of multiple parts, separated by a dot in this
example, where each part should be completed separately --- note,
however, that the case where each part of the word, i.e. tt(comp),
tt(source) and tt(unix) in this example, is to be completed separately
is a different problem to be solved by extended completion. The
example can be handled by:
however, that the case where each part of the word, i.e. `tt(comp)',
`tt(source)' and `tt(unix)' in this example, is to be completed separately
is a different problem to be solved by the implementation of the
completion widget. The example can be handled by:
example(compadd -M 'r:|.=* r:|=*' \
- comp.sources.unix comp.sources.misc ...)
The first specification says that tt(lpat) is the empty string, while
tt(anchor) is a dot; tt(tpat) is tt(*), so this can match anything
The first specification says that var(lpat) is the empty string, while
var(anchor) is a dot; var(tpat) is tt(*), so this can match anything
except for the `tt(.)' from the anchor in
the trial completion word. So in tt(c.s.u), the matcher sees tt(c),
the trial completion word. So in `tt(c.s.u)', the matcher sees `tt(c)',
followed by the empty string, followed by the anchor `tt(.)', and
likewise for the second dot, and replaces the empty strings before the
anchors, giving tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)], where
anchors, giving `tt(c)[tt(omp)]tt(.s)[tt(ources)]tt(.u)[tt(nix)]', where
the last part of the completion is just as normal.
With the pattern shown above, the string `tt(c.u)' could not be
@ -898,7 +903,7 @@ normally try to match trial completions that end with the string as
typed so far, i.e. it will only insert new characters at the cursor
position rather then at the end. However in our example we would like
the code to recognise matches which contain extra characters after the
string on the line (the tt(nix) in the example). Hence we say that the
string on the line (the `tt(nix)' in the example). Hence we say that the
empty string at the end of the string on the line matches any characters
at the end of the trial completion.
@ -913,7 +918,7 @@ with the above in effect, you can just type tt(very.c) before attempting
completion.
The specifications with both a left and a right anchor are useful to
complete partial words whose parts are not really separated by some
complete partial words whose parts are not separated by some
special character. For example, in some places strings have to be
completed that are formed `tt(LikeThis)' (i.e. the separate parts are
determined by a leading uppercase letter) or maybe one has to
@ -923,11 +928,11 @@ form with only one anchor as in:
example(compadd -M 'r:|[A-Z0-9]=* r:|=*' LikeTHIS FooHoo foo123 bar234)
But with this, the string `tt(H)' would be completed to `tt(FooHoo)'
em(and) tt(LikeTHIS) and `tt(2)' would be completed to the other two
em(and) `tt(LikeTHIS)' and `tt(2)' would be completed to the other two
strings because characters can be inserted before every uppercase
letter and digit. To avoid this one would use:
example(compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=* r:|=*' \
example(compadd -M 'r:[^A-Z0-9]||[A-Z0-9]=* r:|=*' \
LikeTHIS FooHoo foo123 bar234)
By using these two anchors, a `tt(H)' matches only uppercase `H's that
@ -939,9 +944,8 @@ When using the completion system (see
ifzman(zmanref(zshcompsys))\
ifnzman(noderef(Completion System))\
), users can define match specifications that are to be used for
specific contexts by using the tt(matcher) style and match
specifications that are to be used everywhere can be defined by the
use of the tt(_matcher) completer.
specific contexts by using the tt(matcher) and tt(matcher-list)
styles. The values for the latter will be used everywhere.
texinode(Examples)()(Matching Control)(Completion Widgets)
sect(Examples)