add _all_matcher completer and supporting C-code for adding a special match representing all other matches; remove completions style from _expand(|_word) (12960)

1 files changed, 52 insertions, 22 deletions

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 11837cb49..0b1e9fda3 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -901,6 +901,18 @@ the description for this argument.  Depending on personal preferences,
 it may be useful to set this style to something like `tt(specify: %d)'. 
 Note that this may not work for some commands.
 )
+kindex(avoid-completer, completion style)
+item(tt(avoid-completer))(
+This is used by the tt(_all_matches) completer to decide if the string 
+consisting of all matches should be added to the list currently being
+generated.  Its value is a list of names of completers.  If any of
+these is the name of the completer that generated the matches in this
+completion, the string will not be added.
+
+The default value for this style is `tt(_expand _old_list _correct
+_approximate)', i.e. it contains the completers for which a string
+with all matches will almost never be wanted.
+)
 kindex(cache-path, completion style)
 item(tt(cache-path))(
 This style defines the path where any cache files containing dumped
@@ -966,14 +978,6 @@ 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.
 )
-kindex(completions, completion style)
-item(tt(completions))(
-This style is used by the tt(_expand) completer function. If it is set 
-to `true', the completer will not generate expansions, but instead the
-completions will be generated as normal and all of them will be
-inserted into the command line.  This style is most useful when set
-only for very specific completion contexts.
-)
 kindex(condition, completion style)
 item(tt(condition))(
 This style is used by the tt(_list) completer function to decide if
@@ -1159,7 +1163,7 @@ ifnzman(noderef(The zsh/zutil Module))\
 )
 kindex(glob, completion style)
 item(tt(glob))(
-Like tt(completions), this is used by the tt(_expand) completer.  If
+This is used by the tt(_expand) completer.  If
 it is set to `true' (the default), globbing will be attempted on the
 words resulting from substitution (see the tt(substitute) style) or
 the original string from the line.
@@ -1650,6 +1654,15 @@ first attempt.  By using the tt(_oldlist) completer and setting this style
 to tt(_match), the list of matches generated on the first attempt will be
 used again.
 )
+kindex(old-matches, completion style)
+item(tt(old-matches))(
+This is used by the tt(_all_matches) completer to decide if an old
+list of matches should be used if one exists.  It may be set to one of 
+the `true' values or to the string `tt(only)' to use such a list.  If
+it is set to `tt(only)', tt(_all_matches) will only use an old list
+and won't have any effect on the list of matches currently being
+generated.
+)
 kindex(old-menu, completion style)
 item(tt(old-menu))(
 This is used by the tt(_oldlist) completer.  It controls how menu
@@ -2109,6 +2122,34 @@ may write their own):
 
 cindex(completion system, completers)
 startitem()
+findex(_all_matches)
+item(tt(_all_matches))(
+This completer can be used to add a string consisting of all other
+matches.  To ensure, that this string is always added, this completer
+has to be used as the first completer in the list.  The
+tt(avoid-completer) style is used to decide if the string should be
+added.  This will only be done if the matches were generated by a
+completer not named by one of the values of the style.
+
+This function also uses the style tt(old-matches).  If it is set to
+`true' or to the string `tt(only)' and there is a list of matches from 
+a previous completion, those matches will be inserted in the command
+line.  If it is set to the the string `tt(only)', it will only insert
+an old list and won't add the string for all matches of the list
+currently being generated.
+
+With the tt(old-matches) style set, this completer should probably not 
+be called unconditionally.  Instead one could use the tt(-e) option of 
+the tt(zstyle) builtin command to add a condition to the tt(completer) 
+or to the tt(old-matches) style.  Alternatively, one could use the
+tt(_generic) function to bind tt(_all_matches) to a separate key
+binding, for example:
+
+example(zle -C all-matches complete-word _generic
+bindkey '^Xa' all-matches
+zstyle ':completion:all-matches:*' old-matches only
+zstyle ':completion:all-matches:*' completer _all_matches)
+)
 findex(_approximate)
 item(tt(_approximate))(
 This completer function uses the tt(_complete) completer to generate
@@ -2312,14 +2353,9 @@ string from the line.
 Which kind of expansion is tried is controlled by the tt(substitute),
 tt(glob) and tt(subst-globs-only) styles.
 
-There is another style, tt(completions), which causes tt(_expand) to
-unconditionally insert all em(completions) generated for the current
-word (even if the word is empty).
-
 When tt(_expand) is called as a function, the different modes may be
-selected with options.  The tt(-c) corresponds to the tt(completions)
-style, tt(-s) to tt(substitute), tt(-g) to tt(glob) and tt(-o) to
-tt(subst-globs-only).
+selected with options.  The tt(-s) to tt(substitute), tt(-g) to
+tt(glob) and tt(-o) to tt(subst-globs-only).
 )
 findex(_history)
 item(tt(_history))(
@@ -2495,12 +2531,6 @@ item(tt(_expand_word (^Xe)))(
 Performs expansion on the current word:  equivalent to the standard
 tt(expand-word) command, but using the tt(_expand) completer.  Before
 calling it, the var(function) field is set to `tt(expand-word)'.
-
-The tt(completions) style is also tested in the resulting context.  When
-it is true, the list of functions from the tt(completer) style is shifted
-to remove any that would be called ahead of tt(_expand).  If tt(_expand)
-does not appear in the tt(completer) style, then only the two completers
-tt(_expand) and tt(_complete) are used (in that order).
 )
 findex(_generic)
 item(tt(_generic))(