diff options
Diffstat (limited to 'Doc/Zsh/compsys.yo')
| -rw-r--r-- | Doc/Zsh/compsys.yo | 146 |
1 files changed, 44 insertions, 102 deletions
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index 0c46badc3..2c7d813d6 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -979,9 +979,8 @@ if the value contains the string tt(directory), then the tests will only be performed if only names of directories are completed. Note that names of directories ignored because of one of the tests -will be ignored in the same way as the matches ignored because of the -tt(ignored-patterns) style. I.e. by using the tt(_ignored) completer -it is possible to complete these directories nonetheless. +will be placed in the alternate set of completions so that they will +be completed if there are no other possible completions. ) item(tt(ignored-patterns))( This style is used with the tags used when adding matches and defines a @@ -1284,6 +1283,26 @@ A style holding the service names of ports to complete. If this is not set by the user, the service names from `tt(/etc/services)' will be used. ) +item(tt(prefer-ignored))( +This style is tested by the main completion function before calling a +completer. The context name is formed in the same way as for the +tt(matcher-list) style, i.e. it contains the name of the completer +that will be called plus a hyphen and the number of the call to that +completer. + +If the style is set to true and completion did not generate any normal +matches yet, but there are matches that were ignored because they +matched one of the patterns given with the tt(fignore) array or the +tt(ignored-patterns) style, these ignored matches are used immediatly +and no other completer will be called. + +It is sometimes useful to set this style for the tt(correct) or +tt(approximate) completer so that ignored matches are prefered over +corrections. + +example(zstyle ':completion:*:complete-2:*' prefer-ignored yes +zstyle ':completion:*:(correct|approximate)-1:*' prefer-ignored yes) +) item(tt(prefix-hidden))( This is used when matches with a common prefix are added (e.g. option names). If it is `true', this prefix will not be shown in the list of @@ -1311,8 +1330,11 @@ matches have no common prefix different from the word on the line or if there is such a common prefix, respectively. The sequence `tt(%c)' is replaced by the name of the completer function that generated the matches (without the leading underscore). Finally, `tt(%n)' is -replaced by the number of matches generated -and if the tt(list) style is set, `tt(%l)' is +replaced by the number of matches generated, `tt(%a)' is replaced by +an empty string if the matches are in the normal set (i.e. the one +without file names with one of the suffixes from the +tt(ignored-suffixes) style) and with `tt( -alt-)' if the matches are +in the alternate set, and if the tt(list) style is set, `tt(%l)' is replaced by `tt(...)' if the list of matches is too long to fit on the screen and with an empty string otherwise. If the tt(list) style is `false', `tt(%l)' will always be removed. @@ -1323,9 +1345,12 @@ all duplicate matches should be removed, rather than just consecutive duplicates. ) item(tt(single-ignored))( -This is used by the tt(_ignored) completer. It allows to specify what -should be done if it can generate only one match, which is often a -special case. If its value is tt(show), the single match will only be shown, +Using styles like tt(ignored-patterns) allows one to put some matches +in the alternate set of matches which is only used if there are no +`normal' matches. Having only one such normally ignored match is often +a special case because one probably doesn't want that match to be +inserted immediatly. This style allows to configure what to do in such +a case. If its value is tt(show), the single match will only be shown, not inserted. If the value is tt(menu), then the single match and the original string are both added as matches and menucompletion is started so that one can easily select either of them. @@ -1388,34 +1413,6 @@ example(zstyle ':completion:*:expand:::' substitute '${NUMERIC:-1} != 1') substitution will be performed only if given an explicit numeric argument other than `tt(1)', as by typing `tt(ESC 2 TAB)'. ) -item(tt(tag-aliases))( -This allows to give aliases for tags that are to be used whenever the -tag this style is set for is used (see the tt(tag-order) style below -for a description of tag aliases). - -The value is a list of strings of the same form used by the -tt(tag-order) style: `var(tag)tt(:)var(alias)', optionally followed by -a second colon and a description. - -The effect of using this style is that the var(tag) is offered more -than once, once for each alias. For example, together with the -tt(ignored-patterns) style this allows to split the matches for the -tag into different groups, as in: - -example(zstyle ':completion:*:options' tag-aliases \ - 'options:-long:long options' \ - 'options:-short:short options' \ - 'options:-single-letter:single letter options' - -zstyle ':completion:*:options-long' ignored-patterns '[-+](|-|[^-]*)' -zstyle ':completion:*:options-short' ignored-patterns '--*' '[-+]?' -zstyle ':completion:*:options-single-letter' ignored-patterns '???*') - -With the tt(group-names) style set, this makes options beginning with -`tt(-)tt(-)', options beginning with a single `tt(-)' or `tt(+)' but -containing multiple characters and single-letter options be displayed -in separate groups with different descriptions. -) item(tt(tag-order))( This provides a mechanism for sorting how the tags available in a particular context will be used. @@ -1448,20 +1445,22 @@ to specify tag aliases instead of only tags. These are of the form by the completion function for the current context and var(alias) is a name. For this, the completion function will generate matches in the same way as for the var(tag) but it will use the var(alias) in place -of the tag in the context names used to look up styles. If the -var(alias) starts with a hyphen, the var(tag) is prepended to the -var(alias) to form the name used for lookup. This can be +of the tag in the context names used to look up styles. This can be used to make the completion system try a certain tag more than once, supplying different style settings for each attempt. For example, example(zstyle ':completion:*:*:-command-:*' tag-order 'functions:-non-comp' -zstyle ':completion:*:functions-non-comp' ignored-patterns '_*') +zstyle '*:-non-comp' ignored-patterns '_*') Makes completion in command position first try only names of shell functions that don't match the pattern `tt(_*)'. If that generates no matches, the default of trying all the other things that can be completed in command position is used, including the names of all -shell functions. +shell functions. Note that the var(alias) used in this example +`tt(-non-comp)' with the hyphen at the bginning is not in any way +special to the completion system. But since no other tag starts with a +hyphen, using such a name allows to use a context pattern as short as +the one in the second line without making it ambiguous. The var(alias) may optionally be followed by a second colon and a description. This description will then be used for the `tt(%d)' in @@ -1471,53 +1470,6 @@ be quoted by preceding them with a backslash and a `tt(%d)' appearing in the description is replaced with the description given by the completion function. -In each of the cases above, the tag may also be a pattern. In this -case all of the offered tags matching this pattern will be used except -for those that are given explicitly in the same string. There are -probably two main uses of this. One is the case where one wants to try -one of the tags more than once, setting other styles differently for -each try, but still wants to use all the other tags without having to -bother to repeat them all. For example, to make completion of function -names in command position first ignore all the completion functions -starting with an underscore one could do: - -example(zstyle ':completion:*:*:-command-:*' tag-order \ - 'functions:-non-comp *' functions -zstyle ':completion:*:functions-non-comp' ignored-patterns '_*') - -Here, the completion system will first try all tags offered, but will -use the tag alias tt(functions-non-comp) when looking up styles for -the function names completed. For this, the tt(ignored-patterns) style -is set to make functions starting with an underscore be not considered -as 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 -tt(ignored-patterns) style will not be used and all function names -will be considered. - -The second interesting use of patterns is the case where one wants to -try multiple match specifications one after another. The -tt(atcher-list) style offers something similar, but it is tested very -early in the completion system and hence can't be set for single -commands or even 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 -generates no matches, try again with case-insensitive matching, one -could do: - -example(zstyle ':completion:*:*:foo:*' tag-order '*' '*:-case' -zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}') - -This will make the completion system first try all the tags offered -when completing after tt(foo) and use the tags to do the lookup. If -that generates no matches, the second value of tt(tag-order) is -used. This will make all tags be tried again, but this time using the -names of the tags with the tt(-case) appended to them for lookup of -styles. I.e. in this second attempt, the value for the tt(matcher) -style from the second call to tt(zstyle) in the example will be used -to make completion case-insensitive. - Strings in the value may also be of the form `var(func)tt(())'. In this case the function var(func) will be called which can then define in which order tags are to be used based on additional context @@ -1589,6 +1541,10 @@ item(tt(users-hosts-ports))( Like tt(users-hosts) but used for commands like tt(telnet) and containing strings of the form `var(user)tt(@)var(host)tt(:)var(port)'. ) +item(tt(users-hosts-ports))( +Like tt(users-hosts) but used for commands like tt(telnet) and +containing strings of the form `var(user)tt(@)var(host)tt(:)var(port)'. +) item(tt(verbose))( This is used in several contexts to decide if only a simple or a verbose list of matches should be generated. For example some commands @@ -1885,20 +1841,6 @@ tt(COMPLETE_IN_WORD) option is set. Because otherwise the cursor will be set after the word before the completion code is called and hence there will be no suffix. ) -findex(_ignored) -item(tt(_ignored))( -Using the tt(ignored-patterns) style it is possible to make some -matches be ignored. This completer allows to complete these matches as -if no tt(ignored-patterns) style were set. Which completers are called -for this is determined in the same way as for the tt(_prefix) -completer. - -Finally, tt(_ignored) uses the tt(single-ignored) style if only one -match could be generated. It can be set to tt(show) to make that match -be only displayed, not inserted into the line or it can be set to -tt(menu) to make the single match and the original string from the -line be offered in a menucompletion. -) findex(_menu) item(tt(_menu))( This completer is a simple example function implemented to show how |