Q: _alternative's `(( w1:d1 w2:d2 ))' form

Q: _alternative's `(( w1:d1 w2:d2 ))' form

[Arseny Maslennikov]

[-- Attachment #1: Type: text/plain, Size: 1808 bytes --]

Hi!

The doc page for _alternative (citing `info zsh`, menu item `Completion
Functions') states:
_alternative [ -O NAME ] [ -C NAME ] SPEC ...
     <...>
     The tags to use and the action to perform if a tag is requested are
     described using the SPECs which are of the form:
     'TAG:DESCR:ACTION'.  The TAGs are offered using _tags and if the
     tag is requested, the ACTION is executed with the given description
     DESCR.  The ACTIONs are those accepted by the _arguments function
     (described below), excluding the '->STATE' and '=...' forms.
     <...>

Later on, the text for _arguments advises to escape the separating
colons between the match candidate and its description in a (( ))
action spec, due to more complex spec parsing and further optional
fields. A thorough reader of the docs might think the same is
required by _alternative as well.

I've been looking at the implementation of _alternative lately; the
function splits its specs into exactly 3 fields, delimited by `:'. The
following seems to be true:

* the first field is delimited by the first colon;
* the second field spans from after the first field's delimiter to the
  nearest colon;
* the rest of the spec is interpreted as the action field, unlike
  the specs for _arguments.

This means that the following completion function should offer either
letters from the set (a b c y z) or hexadecimal digits with their
decimal equivalents as descriptions:

  function _ooo {  
    _alternative \
      'letters:letter:(a b c y z)' \
      'digits:digit:(( 0:0 1:1 2:2 3:3 4:4 5:5 6:6 7:7 8:8 9:9 A:10 B:11 C:12 D:13 E:14 F:15 ))'
  }

It does for me in a `zsh -f` instance.

Is this intentional? If yes, should we fix the doc paragraph
on _alternative?

Thanks in advance!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Q: _alternative's `(( w1:d1 w2:d2 ))' form

[Arseny Maslennikov]

[-- Attachment #1: Type: text/plain, Size: 2254 bytes --]

On Fri, Nov 12, 2021 at 10:32:56PM +0300, Arseny Maslennikov wrote:
> Hi!
> 
> The doc page for _alternative (citing `info zsh`, menu item `Completion
> Functions') states:
> _alternative [ -O NAME ] [ -C NAME ] SPEC ...
>      <...>
>      The tags to use and the action to perform if a tag is requested are
>      described using the SPECs which are of the form:
>      'TAG:DESCR:ACTION'.  The TAGs are offered using _tags and if the
>      tag is requested, the ACTION is executed with the given description
>      DESCR.  The ACTIONs are those accepted by the _arguments function
>      (described below), excluding the '->STATE' and '=...' forms.
>      <...>
> 
> Later on, the text for _arguments advises to escape the separating
> colons between the match candidate and its description in a (( ))
> action spec, due to more complex spec parsing and further optional
> fields. A thorough reader of the docs might think the same is
> required by _alternative as well.
> 
> I've been looking at the implementation of _alternative lately; the
> function splits its specs into exactly 3 fields, delimited by `:'. The
> following seems to be true:
> 
> * the first field is delimited by the first colon;
> * the second field spans from after the first field's delimiter to the
>   nearest colon;
> * the rest of the spec is interpreted as the action field, unlike
>   the specs for _arguments.
> 
On a related note: this looks so obvious with hindsight but I've found
that the following way to avoid escaping the `:' works for _arguments too:

  function _ooo {
    local __ndescs=(
        '0:0' '1:1' '2:2' '3:3'
        '4:4' '5:5' '6:6' '7:7'
        '8:8' '9:9' 'A:10' 'B:11'
        'C:12' 'D:13' 'E:14' 'F:15'
    )
    _arguments '1:letter:(a b c y z)' '2:digit:(( "${(@)__ndescs}" ))'
  }

The expansion of `__ndescs' happens during the action eval, and the
expression does not contain any colons.
This approach is surprisingly quite unpopular, especially in third-party
completions — instead, the authors prefer to use a function as the
action, which then calls _describe by itself (here goes another while
tags; do while _next_label; do done; done loop) and does not introduce
new tags.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Q: _alternative's `(( w1:d1 w2:d2 ))' form

[Oliver Kiddle]

Arseny Maslennikov wrote:
> The doc page for _alternative (citing `info zsh`, menu item `Completion
> Functions') states:
...
> Later on, the text for _arguments advises to escape the separating
> colons between the match candidate and its description in a (( ))
> action spec, due to more complex spec parsing and further optional
> fields. A thorough reader of the docs might think the same is
> required by _alternative as well.

You're right. With _alternative, it isn't necessary to escape further
colons. If you do, it's harmless. Searching the sources _file_modes does
quote them, _diff_options and _git don't. I'd have expected to find more
uses of the feature really but I may have not used the best regex to
find them.

> Is this intentional? If yes, should we fix the doc paragraph
> on _alternative?

Yes to both of those. Patches that improve the documentation are
gratefully accepted.

Oliver

[PATCH] Doc/Zsh/compsys.yo: clarify _alternative's action syntax

[Arseny Maslennikov]

---

Recently, while writing a completion function that uses _alternative to
generate several groups of matches and description strings with
_describe, I decided to look closely at _alternative's source.
It turned out that, contrary to the documentation, I do not have to
escape the separator between a match and its description in the embedded
array representation, unlike the analogous form for an _arguments spec
action.

 Doc/Zsh/compsys.yo | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 89b918d60..b37a752be 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -3616,8 +3616,18 @@ described using the var(spec)s which are of the form:
 `var(tag)tt(:)var(descr)tt(:)var(action)'.  The var(tag)s are offered using
 tt(_tags) and if the tag is requested, the var(action) is executed with the
 given description var(descr).  The var(action)s are those accepted
-by the tt(_arguments) function (described below), excluding the
-`tt(->)var(state)' and `tt(=)var(...)' forms.
+by the tt(_arguments) function (described below), with the following
+exceptions:
+startitemize()
+itemiz(\
+The `tt(->)var(state)' and `tt(=)var(...)' forms are not supported.
+)
+itemiz(\
+The `tt(LPAR()LPAR()a\:bar b\:baz)tt(RPAR()RPAR())' form does not need
+the colon to be escaped, since the var(spec)s have no colon-separated fields
+after the var(action).
+)
+enditemize()
 
 For example, the var(action) may be a simple function call:
 
-- 
2.33.1