diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 87 |
1 files changed, 53 insertions, 34 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index ba49fe298..c2d20ca40 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -1609,16 +1609,12 @@ item(tt(format))( 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 following -sequences to specify output attributes -ifnzman((see noderef(Prompt Expansion)))\ -ifzman(as described in the section EXPANSION OF PROMPT SEQUENCES in -zmanref(zshmisc)): -`tt(%B)', `tt(%S)', `tt(%U)', `tt(%F)', `tt(%K)' and their lower case -counterparts, as well as `tt(%{)...tt(%})'. `tt(%F)', `tt(%K)' and -`tt(%{)...tt(%})' take arguments in the same form as prompt -expansion. Note that the sequence `tt(%G)' is not available; an argument -to `tt(%{)' should be used instead. +what these matches are. This string may also contain the output +attribute sequences understood by tt(compadd -X) +(see +ifzman(zmanref(zshcompwid))\ +ifnzman(noderef(Completion Widgets))\ +). The style is tested with each tag valid for the current completion before it is tested for the tt(descriptions) tag. Hence different format @@ -2064,6 +2060,9 @@ specification. The value should be in the form described in ifzman(the section `Completion Matching Control' in zmanref(zshcompwid))\ ifnzman(noderef(Completion Matching Control))\ . For examples of this, see the description of the tt(tag-order) style. + +For notes comparing the use of this and the tt(matcher-list) style, see +under the description of the tt(tag-order) style. ) kindex(matcher-list, completion style) item(tt(matcher-list))( @@ -2128,6 +2127,9 @@ If there is no current matcher or it is empty, and the option tt(NO_CASE_GLOB) is in effect, the matching for files is performed case-insensitively in any case. However, any matcher must explicitly specify case-insensitive matching if that is required. + +For notes comparing the use of this and the tt(matcher) style, see +under the description of the tt(tag-order) style. ) kindex(max-errors, completion style) item(tt(max-errors))( @@ -2534,20 +2536,20 @@ is started, making it easy to select either of them. ) kindex(sort, completion style) item(tt(sort))( -Many completion widgets call tt(_description) at some point which -decides whether the matches are added sorted or unsorted (often -indirectly via tt(_wanted) or tt(_requested)). This style can be set -explicitly to one of the usual `true' or `false' values as an override. -If it is not set for the context, the standard behaviour of the -calling widget is used. +This allows the standard ordering of matches to be overridden. + +If its value is `tt(true)' or `tt(false)', sorting is enabled or disabled. +Additionally the values associated with the `tt(-o)' option to tt(compadd) can +also be listed: tt(match), tt(nosort), tt(numeric), tt(reverse). If it is not +set for the context, the standard behaviour of the calling widget is used. The style is tested first against the full context including the tag, and if that fails to produce a value against the context without the tag. -If the calling widget explicitly requests unsorted matches, this is usually -honoured. However, the default (unsorted) behaviour of completion -for the command history may be overridden by setting the style to -`true'. +In many cases where a calling widget explicitly selects a particular ordering +in lieu of the default, a value of `tt(true)' is not honoured. An example of +where this is not the case is for command history where the default of sorting +matches chronologically may be overridden by setting the style to `true'. In the tt(_expand) completer, if it is set to `true', the expansions generated will always be sorted. If it is set @@ -4404,11 +4406,11 @@ 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. +tt(ignore-line), tt(ignored-patterns), tt(group-name) and tt(sort). +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 @@ -4518,9 +4520,12 @@ New plugins will be picked up and run automatically. ) findex(_files) item(tt(_files))( -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. +The function tt(_files) is a wrapper around tt(_path_files). It supports +all of the same functionality, with some enhancements DASH()- notably, it +respects the tt(list-dirs-first) style, and it allows users to override +the behaviour of the tt(-g) and tt(-/) options with the tt(file-patterns) +style. tt(_files) should therefore be preferred over tt(_path_files) in +most cases. This function accepts the full set of options allowed by tt(_path_files), described below. @@ -4585,7 +4590,9 @@ not set with the former. 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. +which already contains an expanded description. Note that this +option does not disable the `tt(%)'-sequence parsing done by +tt(compadd). The tt(-12VJ) options and the var(group) are passed to tt(compadd) and hence determine the group the message string is added to. @@ -4658,7 +4665,7 @@ fi return ret) ) findex(_normal) -item(tt(_normal))( +item(tt(_normal) [ tt(-P) | tt(-p) var(precommand) ])( This is the standard function called to handle completion outside any special tt(-)var(context)tt(-). It is called both to complete the command word and also the arguments for a command. In the second case, @@ -4668,10 +4675,22 @@ there is none it uses the completion for the tt(-default-) context. A second use is to reexamine 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 +completes after precommand specifiers such as tt(nohup), removes the first word from the tt(words) array, decrements the tt(CURRENT) parameter, -then calls tt(_normal) again. The effect is that `tt(nohup) var(cmd ...)' -is treated in the same way as `var(cmd ...)'. +then calls `tt(_normal -p $service)'. The effect is that +`tt(nohup) var(cmd ...)' is treated in the same way as `var(cmd ...)'. + +startitem() +item(tt(-P))( +Reset the list of precommands. This option should be used if completing +a command line which allows internal commands (e.g. builtins and +functions) regardless of prior precommands (e.g. `tt(zsh -c)'). +) +item(tt(-p) var(precommand))( +Append var(precommand) to the list of precommands. This option should be +used in nearly all cases in which tt(-P) is not applicable. +) +enditem() 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 @@ -5135,7 +5154,7 @@ 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 non-option argument is used as a string to print as a +The first non-option argument, var(desc), is used as a string to print as a description before listing the values. All other arguments describe the possible values and their |