How to change description for _user_expand completions?

How to change description for _user_expand completions?

[Pax Unix]

Many times the completion function I write works, but I've always got
the uneasy feeling that it works because of a certain amount of
coincidence instead of intent.

I feel like I only know just enough completion-system magic to be
dangerous, so I'd appreciate any guidance.  It would be handy if there
were a zsh completion/expansion system cookbook.  zshcompsys(1) and
zshcompwid(1) explain what's available, but I've found it difficult to
figure out the "correct" way to accomplish something and support all of
the other features (like configurable styles, etc.) for my functions.

My current problem:  I've got a function called by _user_expand so I can
generate context-independent completions based on a particular prefix.

It works perfectly well, but the only description that ever appears is
either "all expansions" or "expansions" (or "original").  I want to
specify the description string from within my expander function,
tailored to the results I'm returning, rather than have to accept the
default.

I thought I could call _describe, but I can't seem to find the correct
parameters to make it work.

Is this possible?  Or since there could be any number of expansion
functions called, do the results have to all be lumped into the same
group because there's no tag information specific to each expander?

-- 
Shawn

Re: How to change description for _user_expand completions?

[Peter Stephenson]

On Sun, 26 Aug 2012 11:28:31 -0700
Pax Unix <paxunix@gmail.com> wrote:
> My current problem:  I've got a function called by _user_expand so I can
> generate context-independent completions based on a particular prefix.
> 
> It works perfectly well, but the only description that ever appears is
> either "all expansions" or "expansions" (or "original").  I want to
> specify the description string from within my expander function,
> tailored to the results I'm returning, rather than have to accept the
> default.

I don't think that's currently handled.  All _user_expand does with your
function is run it to assemble a list of possible completions from an
array.  This is then passed into the completion system by _user_expand,
so anything else your function does is ignored (unless it's directly
adding completions itself, which would make _user_expand a bit
pointless).

We could come up with a convention for this.  It looks to me like
_user_expand only ever picks the first non-zero set of expansions (when
it's found some expansions it assigns, rather than appends, to the array
exp that contains the expansions) --- this doesn't appear to be
documented --- so passing back an additional reply from the function ought
to be good enough.  So we could use REPLY and do something like the
following.

Index: Completion/Base/Completer/_user_expand
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Completer/_user_expand,v
retrieving revision 1.1
diff -p -u -r1.1 _user_expand
--- Completion/Base/Completer/_user_expand	25 Mar 2009 13:29:30 -0000	1.1
+++ Completion/Base/Completer/_user_expand	28 Aug 2012 12:56:03 -0000
@@ -12,7 +12,7 @@ setopt localoptions nonomatch
 
 [[ _matcher_num -gt 1 ]] && return 1
 
-local exp word sort expr expl subd suf=" " asp tmp spec
+local exp word sort expr expl subd suf=" " asp tmp spec REPLY
 local -a specs reply
 
 if [[ "$funcstack[2]" = _prefix ]]; then
@@ -30,6 +30,7 @@ exp=("$word")
 zstyle -a ":completion:${curcontext}" user-expand specs || return 1
 
 for spec in $specs; do
+  REPLY=
   case $spec in
     ('$'[[:IDENT:]]##)
     # Spec is an associative array with explicit keys.
@@ -85,9 +86,9 @@ fi
 
 if [[ -z "$compstate[insert]" ]] ;then
   if [[ "$sort" = menu ]]; then
-    _description expansions expl expansions "o:$word"
+    _description expansions expl "expansions${REPLY:+: $REPLY}" "o:$word"
   else
-    _description -V expansions expl expansions "o:$word"
+    _description -V expansions expl "expansions${REPLY:+: $REPLY}" "o:$word"
   fi
 
   compadd "$expl[@]" -UQ -qS "$suf" -a exp
@@ -98,9 +99,9 @@ else
     local i j normal space dir
 
     if [[ "$sort" = menu ]]; then
-      _description expansions expl expansions "o:$word"
+      _description expansions expl "expansions${REPLY:+: $REPLY}" "o:$word"
     else
-      _description -V expansions expl expansions "o:$word"
+      _description -V expansions expl "expansions${REPLY:+: $REPLY}" "o:$word"
     fi
     normal=()
     space=()
@@ -120,7 +121,7 @@ else
     (( $#space ))  && compadd "$expl[@]" -UQ -qS " " -a space
     (( $#normal )) && compadd "$expl[@]" -UQ -qS "" -a normal
   fi
-  if _requested all-expansions expl 'all expansions'; then
+  if _requested all-expansions expl "all expansions${REPLY:+: $REPLY}"; then
     local disp dstr
 
     if [[ "${#${exp}}" -ge COLUMNS ]]; then
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.248
diff -p -u -r1.248 compsys.yo
--- Doc/Zsh/compsys.yo	21 Aug 2012 18:45:31 -0000	1.248
+++ Doc/Zsh/compsys.yo	28 Aug 2012 12:56:04 -0000
@@ -3180,7 +3180,9 @@ var(_func) is the name of a shell functi
 tt(_) but is not otherwise special to the completion system.  The function
 is called with the trial word as an argument.  If the word is to be
 expanded, the function should set the array tt(reply) to a list of
-expansions.  The return status of the function is irrelevant.
+expansions.  Optionally, it can set tt(REPLY) to a word that will
+be used as a description for the set of expansions.
+The return status of the function is irrelevant.
 )
 endsitem()
 )

-- 
Peter Stephenson <pws@csr.com>            Software Engineer
Tel: +44 (0)1223 692070                   Cambridge Silicon Radio Limited
Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, UK


Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog