zsh-3.1.6-dev-20 zsh-3.1.6-dev-20

2 files changed, 68 insertions, 109 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
diff --git a/Doc/Zsh/compwid.yo b/Doc/Zsh/compwid.yo
index 86b7d6e31..f535b14dd 100644
--- a/Doc/Zsh/compwid.yo
+++ b/Doc/Zsh/compwid.yo
@@ -197,13 +197,16 @@ level.
 )
 item(tt(nmatches))(
 The number of matches generated and accepted by the completion code so
-far.
-)
-item(tt(ignored))(
-The number of words that were ignored because they matched one of the
-patterns given with the tt(-F) option to the tt(compadd) builtin
+far, excluding those matches that are only accepted by ignoring the
+tt(fignore) parameter and the tt(-a) option of the tt(compadd) builtin 
 command.
 )
+item(tt(alternate_nmatches))(
+Like tt(nmatches), but counts only matches in the alternate set. I.e. file
+names with one of the suffixes from the tt(fignore) array and matches
+put into the alternate set using the tt(-a) option of the tt(compadd)
+builtin command (see below) are not counted.
+)
 item(tt(restore))(
 This is set to tt(auto) before a function is entered, which forces the
 special parameters mentioned above (tt(words), tt(CURRENT), tt(PREFIX),
@@ -515,9 +518,23 @@ with any prefix specified by the tt(-p) option to form a complete filename
 for testing.  Hence it is only useful if combined with the tt(-f) flag, as
 the tests will not otherwise be performed.
 )
+item(tt(-a))(
+The completion code may build two sets of matches: the normal and the
+alternate set. Normally only the matches in the first set are used,
+but if this set is empty, the words from the alternate set are
+used. The completion code uses this mechanism, for example, to make
+filenames without one of the suffixes defined with the tt(fignore)
+shell parameter be preferred over filenames with one of these
+suffixes.
+
+With the tt(-a)-flag given, the var(words) are stored in the alternate
+set unless this flag is overridden by the tt(-F) option.
+)
 item(tt(-F) var(array))(
-Specifies an array containing patterns. Words matching one of these
-patterns are ignored, i.e. not considered to be possible matches.
+Specifies an array containing patterns.
+Words matching one of these patterns are stored in
+the alternate set of matches and words that match none of the patterns
+are stored in the normal set.
 
 The var(array) may be the name of an array parameter or a list of
 literal patterns enclosed in parentheses and quoted, as in `tt(-F "(*?.o