PATCH: _expand, _expand_word, and their doc

["Bart Schaefer" <schaefer@candle.brasslantern.com>]

Way back in 11244, Sven wrote:

} However, there was a problem I didn't realise before. With completions 
} set _expand just returned with a value of one to make the following
} completers be called. But with _expand_word there aren't any following 
} completers... So the patch makes _expand call _complete when called
} from _expand_word.

This has the undesirable side-effect of failing to call any of the usual
other completers such as _match (see zsh-users/3444 and its thread).  So
I've deleted that line from _expand, and instead caused _expand_word to
fetch the `completer' style and modify the result so that _expand is the
first completer in the list.  This is imperfect, as it discards the entire
list if you haven't included the _expand completer at all, but I couldn't
think of any better way to assure that unwanted completers such as _list
and _menu are excluded.

Then, there was a completely inaccurate remark about the expansions and
all-expansions tags in the doc:  They're *not* available when using the
completions style with _expand.  If that's a bug in _expand rather than
in the doc, I can't immediately see how to fix it ... so I changed the
doc, and maybe Sven will do something to _expand when he returns.

Index: Completion/Commands/_expand_word
===================================================================
@@ -6,6 +6,7 @@
 unsetopt markdirs globsubst shwordsplit nounset ksharrays
 
 local curcontext="$curcontext"
+local -ah completers
 
 if [[ -z "$curcontext" ]]; then
   curcontext="expand-word:::"
@@ -13,4 +14,8 @@
   curcontext="expand-word:${curcontext#*:}"
 fi
 
-_main_complete _expand
+zstyle -a ":completion:${curcontext}:" completer completers
+completers[1,(i)_expand]=_expand
+(( $#completers == 1 )) && completers=(_expand _complete)
+
+_main_complete $completers
Index: Completion/Core/_expand
===================================================================
@@ -23,7 +23,6 @@
 if [[ "$force" = *c* ]] ||
    zstyle -t ":completion:${curcontext}:" completions; then
   compstate[insert]=all
-  [[ "$curcontext" = expand-word:* ]] && _complete && return 0
   return 1
 fi
 
Index: Doc/Zsh/compsys.yo
===================================================================
@@ -971,7 +971,8 @@
 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.
+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))(
@@ -2302,10 +2303,9 @@
 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 allows tt(_expand) to
-display or insert all em(completions) generated for the string.  The use of
-this is that the tags tt(expansions) and tt(all-expansions) are available,
-unlike with tt(_complete).
+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)
@@ -2485,7 +2485,11 @@
 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)'.
+calling it, the var(function) field is set to `tt(expand-word)', and the
+list of functions from the tt(completer) style in the resuting context is
+shifted to remove all those to the left of tt(_expand).  If tt(_expand)
+does not appear in the style, then only the two completers tt(_expand) and
+tt(_complete) are used (in that order).
 )
 findex(_generic)
 item(tt(_generic))(

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net