_arguments and state_descr (Re: Next release)

[Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>]

On Dec 9,  4:42pm, Peter Stephenson wrote:
} Subject: Re: Next release
}
} On Fri, 9 Dec 2011 08:37:14 -0800
} Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx> wrote:
} > I still have uncommitted the change to add $state_descr to _arguments
} > and _values and reference it in _zle (workers/29766).  Do we want?
} 
} Seems reasonable to include it, given that the shell probably isn't
} going to be come object-orientated any time soon.

Here's the proposed final diff, just to get it a recent zsh-workers
article number.  Note that in writing the doc I discovered that what
we've been calling the "description" is actually termed the "message"
in the existing documentation, although it is passed to _wanted in
the description position.

Does that have any influence on what the array should be named?  I've
never been entirely happy with "state_descr".


Index: Completion/Base/Core/_main_complete
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Core/_main_complete,v
retrieving revision 1.13
diff -u -r1.13 _main_complete
--- Completion/Base/Core/_main_complete	24 May 2011 01:09:46 -0000	1.13
+++ Completion/Base/Core/_main_complete	12 Dec 2011 16:25:50 -0000
@@ -23,7 +23,8 @@
 local func funcs ret=1 tmp _compskip format nm call match min max i num\
       _completers _completer _completer_num curtag _comp_force_list \
       _matchers _matcher _c_matcher _matcher_num _comp_tags _comp_mesg  \
-      mesg str context state line opt_args val_args curcontext="$curcontext" \
+      mesg str context state state_descr line opt_args val_args \
+      curcontext="$curcontext" \
       _last_nmatches=-1 _last_menu_style _def_menu_style _menu_style sel \
       _tags_level=0 \
       _saved_exact="${compstate[exact]}" \
Index: Completion/Base/Utility/_arguments
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Utility/_arguments,v
retrieving revision 1.22
diff -u -r1.22 _arguments
--- Completion/Base/Utility/_arguments	17 Nov 2008 10:37:37 -0000	1.22
+++ Completion/Base/Utility/_arguments	12 Dec 2011 16:25:50 -0000
@@ -344,6 +344,7 @@
 
   context=()
   state=()
+  state_descr=()
 
   while true; do
     while _tags; do
@@ -376,6 +377,7 @@
 	      if (( ! $state[(I)$action] )); then
                 comparguments -W line opt_args
                 state+=( "$action" )
+                state_descr+=( "$descr" )
 	        if [[ -n "$usecc" ]]; then
 	          curcontext="${oldcontext%:*}:$subc"
 	        else
Index: Completion/Base/Utility/_values
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Base/Utility/_values,v
retrieving revision 1.12
diff -u -r1.12 _values
--- Completion/Base/Utility/_values	28 Aug 2009 15:10:39 -0000	1.12
+++ Completion/Base/Utility/_values	12 Dec 2011 16:25:50 -0000
@@ -87,6 +87,7 @@
   if [[ "$action" = -\>* ]]; then
     compvalues -v val_args
     state="${${action[3,-1]##[ 	]#}%%[ 	]#}"
+    state_descr="$descr"
     if [[ -n "$usecc" ]]; then
       curcontext="${oldcontext%:*}:$subc"
     else
Index: Completion/Zsh/Command/_zle
===================================================================
RCS file: /cvsroot/zsh/zsh/Completion/Zsh/Command/_zle,v
retrieving revision 1.4
diff -u -r1.4 _zle
--- Completion/Zsh/Command/_zle	13 Sep 2010 08:49:23 -0000	1.4
+++ Completion/Zsh/Command/_zle	12 Dec 2011 16:25:51 -0000
@@ -44,7 +44,7 @@
       '(-)*:widget arguments: ' && ret=0
     ;;
   (widget*)
-    _wanted -C "$context[1]" widgets expl widget compadd -k widgets && ret=0
+    _wanted -C "$context[1]" widgets expl "${state_descr[1]:-widget}" compadd -k widgets && ret=0
     ;&
   (function)
     [[ $state[1] != *function ]] ||	# Handle fall-through
Index: Doc/Zsh/compsys.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/compsys.yo,v
retrieving revision 1.245
diff -u -r1.245 compsys.yo
--- Doc/Zsh/compsys.yo	11 Dec 2011 17:48:27 -0000	1.245
+++ Doc/Zsh/compsys.yo	12 Dec 2011 16:25:56 -0000
@@ -3687,10 +3687,12 @@
 for generating completions.  For example, functions that implement a state
 machine can use this type of action.
 
-Where tt(_arguments) encounters a `tt(->)var(string)', it will strip
-all leading and trailing whitespace from var(string) and set the array
-tt(state) to the set of all var(strings)s for which an action is to be
-performed.
+Where tt(_arguments) encounters var(action) in the `tt(->)var(string)'
+format, it will strip all leading and trailing whitespace from var(string)
+and set the array tt(state) to the set of all var(string)s for which an
+action is to be performed.  The elements of the array tt(state_descr) are
+assigned the corresponding var(message) field from each var(optarg)
+containing such an var(action).
 
 By default and in common with all other well behaved completion
 functions, _arguments returns status zero if it was able to add matches and
@@ -3698,7 +3700,8 @@
 tt(_arguments) will instead return a status of 300 to indicate that
 tt($state) is to be handled.
 
-In addition to tt($state), tt(_arguments) also sets the global
+In addition to tt($state) and tt($state_descr), tt(_arguments) also
+sets the global
 parameters `tt(context)', `tt(line)' and `tt(opt_args)' as described
 below, and does not reset any changes made to the special parameters
 such as tt(PREFIX) and tt(words).  This gives the calling function the
@@ -3708,7 +3711,7 @@
 one action containing a `tt(->)var(string)' must therefore declare
 appropriate local parameters:
 
-example(local context state line
+example(local context state state_descr line
 typeset -A opt_args)
 
 to prevent tt(_arguments) from altering the global environment.
@@ -4794,15 +4797,17 @@
 The associative array tt(val_args) is used to report values and their
 arguments; this works similarly to the tt(opt_args) associative array
 used by tt(_arguments).  Hence the function calling tt(_values) should
-declare the local parameters tt(state), tt(line), tt(context) and
-tt(val_args):
+declare the local parameters tt(state), tt(state_descr), tt(line),
+tt(context) and tt(val_args):
 
-example(local context state line
+example(local context state state_descr line
 typeset -A val_args)
 
 when using an action of the form `tt(->)var(string)'.  With this
 function the tt(context) parameter will be set to the name of the
-value whose argument is to be completed.
+value whose argument is to be completed.  Note that for tt(_values),
+the tt(state) and tt(state_descr) are scalars rather than arrays.
+Only a single matching state is returned.
 
 Note also that tt(_values) normally adds the character used as the
 separator between values as an auto-removable suffix (similar to a