completion parameter suggestion

completion parameter suggestion

[Sven Wischnowsky]

(I'm asking a lot of questions lately, but I hope you agree that this
is correct behavior.)

Here is what I'm planning for the special completion parameters. Some
of this has been mentioned already, but this is more complete and
slightly different from what I said in my last mail (incorporating
suggestions from Bart and Peter):

Most of the stuff will be put in an associative array named
`compstate', but first:

- I'd like to keep `PREFIX', `SUFFIX', and `IPREFIX' (probably
  renaming the last one), since I guess that `PREFIX[...]' will be
  used quite often and is much easier to type and read than
  `compstate[prefix][...]'. Also, `PREFIX[...]=...' may occasionally
  be useful and multiple subscripts on the left hand side of an
  assignment is not supported.
- I'd also like to keep `CURRENT' to improve readibility and make it
  an index into the array `words'. Slight problem with `ksharrays'
  here, I'd like to make `CURRENT' use the range [1,n] and explicitly
  describe the problem in the manual.
- The `words' array would contain all words from the line, including
  the command. Functions like `_precommand' would only have to do
  `shift words; (( CURRENT-- ))'. No fiddling with `compstate' since
  the `comamnd' and `argument' contexts would be merged into one.
- Finally the context information, an associative array. Contrary to
  the previous parameters this one will not automatically be restored
  on exit of a function. The keys are:

  - `matcher':     the string(!) of the global matcher
  - `matcher_num': what now is `MATCHER' which will be removed
  - `num_matches': what now is `NMATCHES'
  - `context':     the former `CONTEXT'
                   - no `argument' value
		   - the `value' context could be split into `value'
		     and `array_value'
		   - a new value `parameter' for completion in `$...'
  - `parameter':   the name of the parameter for the `value' and
                   `subscript' contexts
  - `quote':       either a ` or a ", depending on the quoting the
                   code thinks we are in
  - `norestore':   this is always restored on exit of a function; if
                   it is set on exit, the parameters above will not be 
		   reset to the values they had when the function was
		   entered (with this we can finally implement helper
		   functions that do tests and modify the parameters
		   without having to make the helpers call other
		   functions that produce the matches)

  (I'm not yet too sure about the following ones, suggestions are
  especially welcome.)

  - `list':        on entry to the completion widget this is set to
                   one of `list', `autolist', `ambiguous', or it is
		   unset (or set to an empty string); this means that
		   the list will be shown always (for `list' and
		   `autolist'), probably (`ambiguous'), or not at all;
		   after the completion widget returns the completion
		   code uses the value to find out if the list should
		   be shown
  - `insert':      on entry this would be set to `menu', `automenu',
                   `unambiguous', or it is unset (or set to the empty
		   string); after executing the completion widget, the 
		   C-code will use this value to decide what should be 
		   inserted into the line: the first metach, starting
		   menucompletion (`menu' or `automenu'), the
		   unambiguous string (`...'), or nothing at all
  - `exact':       the completion code searches for exact matches on
                   the fly anyway, so we could make this information
		   available; this would be unset (or empty) if no
		   exact match was found; it will be set while
		   generating matches when an exact match is found;
		   then the value would be `insert' if one was found
		   and it should be inserted in the line (recexact)
		   and to `yes' (or something better) when one was
		   found but the user didn't set recexact

And then I'd like to make the following information available but
haven't found keys in which these could be combined (trying to avoid
too many keys and having to use too many keys for whatever purpose):

  - if there currently is an older and still valid set of matches
  - if this set is displayed on the screen
  - if this set should be kept, the set build by the completion widget 
    would be discarded (this new set will be empty in most cases)
  - if we are currently in a menucompletion, with that, probably:
    - the total number of matches in the set we are menucompleting
    - the number of the match currently on the line
    - make the code insert the n'th (or n'th next/previous) match
    - make the code accept the current match and continue
      menucompletion

And the we might want to add suport for as yet unheard of things:

  - list only the matches form certain groups
  - complete only matches from certain groups
  - skip over to another group
  - etc.

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

Re: completion parameter suggestion

[Peter Stephenson]

> (I'm asking a lot of questions lately, but I hope you agree that this
> is correct behavior.)

It depends what you think of the answers...

> - I'd also like to keep `CURRENT' to improve readibility and make it
>   an index into the array `words'. Slight problem with `ksharrays'
>   here, I'd like to make `CURRENT' use the range [1,n] and explicitly
>   describe the problem in the manual.

Does that mean that with ksharrays set, you would have to use
words[CURRENT-1] ?  Is it obvious this is better than subtracting 1 from
CURRENT automatically when ksharrays is set?  I suppose it is when you want
to test [[ $CURRENT -eq 1 ]] for the command.  Well, we'll just have to
make sure ksharrays is unset in all the standard functions.

>   - `matcher_num': what now is `MATCHER' which will be removed

Since `num' is not a word, I'd be quite happy with just `matcher' as
before.

>   - `num_matches': what now is `NMATCHES'

Same problem: nmatches is probably just as good here.  It looks sufficienly
like $n_\mathrm{matches}$ for anyone with a mathematical upbringing.  It
would be nice to have something neater, but the only thing I can think of
is `matchcount'.

>   - `quote':       either a ` or a ", depending on the quoting the
>                    code thinks we are in

How about 'single' or 'double', since most of the context is going to be in
words?

>   - `norestore':   this is always restored on exit of a function; if
>                    it is set on exit, the parameters above will not be 
> 		   reset to the values they had when the function was
> 		   entered (with this we can finally implement helper
> 		   functions that do tests and modify the parameters
> 		   without having to make the helpers call other
> 		   functions that produce the matches)

But num_matches will be changed anyway if new matches were added in the
function, so in most cases you won't want to restore that on exit anyway.

>   (I'm not yet too sure about the following ones, suggestions are
>   especially welcome.)

These sound pretty good.

>   - if there currently is an older and still valid set of matches
>   - if this set is displayed on the screen
>   - if this set should be kept, the set build by the completion widget 
>     would be discarded (this new set will be empty in most cases)
>   - if we are currently in a menucompletion, with that, probably:
>     - the total number of matches in the set we are menucompleting
>     - the number of the match currently on the line
>     - make the code insert the n'th (or n'th next/previous) match
>     - make the code accept the current match and continue
>       menucompletion

I'll think about these.  I can see the problem; if you just have e.g.
$context[curlist], then on entry it can be e.g. valid, displayed, none, but
on exit you would want it to be something like keep, so it looks a little
inconsistent, and other functions can't get the old value.  Maybe that's
OK, though.  If so, we could do something like
on entry
  $context[menuitem] = "11/20"   11th out of 20 shown (blank if not
                                 menu-completing)
on exit
  context[menuitem]=14           insert the fourteenth match
                                 (use existing number to determine new one)
  context[menuitem]=accept       accept the current one   ) initial letter
  context[menuitem]=continue     accept-and-menu-complete ) probably OK

On the other hand, with a special associative array polluting the name
space is not such a big worry.

My dream is of being able to highlight an item in the list and move through
it with the cursor keys to pick one.  It's not impossible --- add some
highlight information when sending to zle_refresh(), remember rows and
columns, hit return to accept, escape to cancel the selection cursor ---
but it's still a way off.

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy

Re: completion parameter suggestion

[Sven Wischnowsky]

Peter Stephenson wrote:

> > (I'm asking a lot of questions lately, but I hope you agree that this
> > is correct behavior.)
> 
> It depends what you think of the answers...

Any answer is better than no answer.

> >   - `matcher_num': what now is `MATCHER' which will be removed
> 
> Since `num' is not a word, I'd be quite happy with just `matcher' as
> before.

I thought of giving the match spec string as `matcher'. But we can
easily (probably better) use `matcher' for the number, and give the
string as `matcher_string'.

> >   - `num_matches': what now is `NMATCHES'
> 
> Same problem: nmatches is probably just as good here.  It looks sufficienly
> like $n_\mathrm{matches}$ for anyone with a mathematical upbringing.  It
> would be nice to have something neater, but the only thing I can think of
> is `matchcount'.

This was a last minute change as I thought I recalled some complaint
about it. Maybe I was just wrong.

> >   - `quote':       either a ` or a ", depending on the quoting the
> >                    code thinks we are in
> 
> How about 'single' or 'double', since most of the context is going to be in
> words?

That's what I suggested first, Bart suggested giving the quote
itself. Again, we could make this `quote=single/double' and
`quote_char='/"'.

> >   - `norestore':   this is always restored on exit of a function; if
> >                    it is set on exit, the parameters above will not be 
> > 		   reset to the values they had when the function was
> > 		   entered (with this we can finally implement helper
> > 		   functions that do tests and modify the parameters
> > 		   without having to make the helpers call other
> > 		   functions that produce the matches)
> 
> But num_matches will be changed anyway if new matches were added in the
> function, so in most cases you won't want to restore that on exit anyway.

I was talking about the parameters, not the keys (i.e. only `PREFIX',
`SUFFIX', `IPREFIX', `CURRENT', and `words'  would be restored).

>   $context[menuitem] = "11/20"   11th out of 20 shown (blank if not
>                                  menu-completing)
> on exit
>   context[menuitem]=14           insert the fourteenth match
>                                  (use existing number to determine new one)
>   context[menuitem]=accept       accept the current one   ) initial letter
>   context[menuitem]=continue     accept-and-menu-complete ) probably OK

One of my thoughts was to use the `insert' key for things like this,
too (and also played with `<number>' and `accept' or `next' and
`previous').

> On the other hand, with a special associative array polluting the name
> space is not such a big worry.

Right.

> My dream is of being able to highlight an item in the list and move through
> it with the cursor keys to pick one.  It's not impossible --- add some
> highlight information when sending to zle_refresh(), remember rows and
> columns, hit return to accept, escape to cancel the selection cursor ---
> but it's still a way off.

When this was added to Emacs (or, at least when I saw that this is
possible in Emacs) I had the same idea. But then, I only seldom use
menucompletion and always have problems imagining what people using it 
would like.

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de

Re: completion parameter suggestion

[Bart Schaefer]

Sven Wischnowsky writes:
 > (I'm asking a lot of questions lately, but I hope you agree that this
 > is correct behavior.)

I agree that you should be asking questions, if that's what you mean.

 > Most of the stuff will be put in an associative array named
 > `compstate', but first:
 > 
 > - I'd like to keep `PREFIX', `SUFFIX', and `IPREFIX' (probably
 >   renaming the last one), since I guess that `PREFIX[...]' will be
 >   used quite often

That's fine.

 > - I'd also like to keep `CURRENT' to improve readibility and make it
 >   an index into the array `words'. Slight problem with `ksharrays'
 >   here, I'd like to make `CURRENT' use the range [1,n] and explicitly
 >   describe the problem in the manual.

That's fine, too.

 > - The `words' array would contain all words from the line, including
 >   the command. Functions like `_precommand' would only have to do
 >   `shift words; (( CURRENT-- ))'. No fiddling with `compstate' since
 >   the `comamnd' and `argument' contexts would be merged into one.

So ... this means that changes to `words' would not cause zsh to try to
automatically update the rest of `compstate'?

 > - Finally the context information, an associative array. Contrary to
 >   the previous parameters this one will not automatically be restored
 >   on exit of a function. The keys are:
 > 
 >   - `matcher':     the string(!) of the global matcher
 >   - `matcher_num': what now is `MATCHER' which will be removed

Incidentally, I've never been clear on where the "matcher number" is
coming from in the first place, nor what one would use it for.  Maybe I
just haven't looked through the examples closely enough.

 >   - `num_matches': what now is `NMATCHES'

I'm with Peter on the "num" issue.  Too bad "matcher" and "matches" are so
similar.

 >   - `context':     the former `CONTEXT'
 >                    - no `argument' value
 > 		   - the `value' context could be split into `value'
 > 		     and `array_value'
 > 		   - a new value `parameter' for completion in `$...'

Suppose I'm in the middle of ${$(...)}.  What's the context?  What's
the context inside $'...'?

 >   - `parameter':   the name of the parameter for the `value' and
 >                    `subscript' contexts
 >   - `quote':       either a ` or a ", depending on the quoting the
 >                    code thinks we are in

It'd be fine with me to have both a `quote' and a `quoting' key, where
the first is the character and the second is a word ("single" "double"
and what, "backtick"?).  I suggested using a character because then you
don't have to think of words for all three states and you can just use
the expansion of $compstate[quote] in generated matches that want to
include the matching quote character.

 >   - `norestore':   this is always restored on exit of a function; if
 >                    it is set on exit, the parameters above will not be 
 > 		   reset to the values they had when the function was
 > 		   entered

Let's try to avoid negatives, shall we?  Call it `restore' or `local' and
have it default to set, and you unset it to prevent value restoration.  Or
call it `scope' defaulting to `local' and you set it to `export' to make
the other values not be restored.  But don't use a leading `no'.

 >   - `list':        on entry to the completion widget this is set to
 >                    one of `list', `autolist', `ambiguous', or it is
 > 		   unset (or set to an empty string)

Sounds reasonable.

 >   - `insert':      on entry this would be set to `menu', `automenu',
 >                    `unambiguous'

This sounds OK too, but maybe `prefix' rather than `unambiguous'.
Maybe.

 >   - `exact':       the completion code searches for exact matches on
 >                    the fly anyway, so we could make this information
 > 		   available

Two suggestions: (1) `exact' should be a possible value of the `insert'
element mentioned above; (2) the element named `exact' should either be
unset (when there is no exact match) or set to $word[CURRENT].  (I don't
have a good argument for that setting, it just feels more useful than
`yes' or `insert'.)

 > And then I'd like to make the following information available but
 > haven't found keys in which these could be combined (trying to avoid
 > too many keys and having to use too many keys for whatever purpose):

How about another associative array called `menustate' that holds all
these things?

Peter Stephenson writes:
 > Does that mean that with ksharrays set, you would have to use
 > words[CURRENT-1] ?  Is it obvious this is better than subtracting 1 from
 > CURRENT automatically when ksharrays is set?  I suppose it is when you want
 > to test [[ $CURRENT -eq 1 ]] for the command.  Well, we'll just have to
 > make sure ksharrays is unset in all the standard functions.

The other possibility would be to automatically insert a dummy element 0
into `words' when ksharrays is set, and automatically remove it when
ksharrays changes.  That could be done without hooking into the option
code if `words' was a special array with a special get-function.

Re: completion parameter suggestion

[Bart Schaefer]

On Feb 26,  1:20pm, Sven Wischnowsky wrote:
} Subject: Re: completion parameter suggestion
}
} Bart Schaefer wrote:
} > Incidentally, I've never been clear on where the "matcher number" is
} > coming from in the first place, nor what one would use it for.  Maybe I
} > just haven't looked through the examples closely enough.
} 
} [...]  global match specs (`compctl -M 'spec1' 'spec2'...),
} these are tried by the completion code in order [...]
} `MATCHER' is the number of the one which is currently tried.

Hrm.  I should think that the string rather than the number would be
of much more use here.  The `compctl -M` command may have been changed
without changing the function, in which case the function's idea of
what pattern goes with what number would be completely wrong.

} > How about another associative array called `menustate' that holds all
} > these things?
} 
} As for the menu stuff, ok. But the list stuff isn't connected to
} (only) menucompletion.

Well ... displaying a list and allowing the user to choose from it is
a "menu" even if it's not "menu completion" in the zsh sense.  "Menu
completion" is just a different way of displaying the list.  So I won't
have any problem with calling it `menustate' and putting list stuff in
there, or calling it `list_state' and putting menucomplete stuff in
there, or whatever, even if menucompletion isn't actually in use.

} > The other possibility would be to automatically insert a dummy element 0
} > into `words' when ksharrays is set, and automatically remove it when
} > ksharrays changes.  That could be done without hooking into the option
} > code if `words' was a special array with a special get-function.
} 
} Hadn't thought about that, yes maybe... (but it's the other way round, 
} isn't it?)

It is?  ksharrays means array indices start at 0, right?  So to get
words[1] to be the command in ksharrays state, you have to insert a
dummy element 0.  (In non-ksharrays state, there's already a dummy
element 0, which happens to be the same as element 1.)

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

Re: completion parameter suggestion

[Sven Wischnowsky]

Bart Schaefer wrote:

> So ... this means that changes to `words' would not cause zsh to try to
> automatically update the rest of `compstate'?

In the `compstate' I described there isn't anything that would have to 
be updated (context stays the same and so on...). That's the reason
why I didn't suggest putting `CURRENT' in `compstate' and why I want
to remove the `argument' context.

> Incidentally, I've never been clear on where the "matcher number" is
> coming from in the first place, nor what one would use it for.  Maybe I
> just haven't looked through the examples closely enough.

One can give more than one global match specs (`compctl -M 'spec1' 'spec2'...),
these are tried by the completion code in order (they are `xor'ed... ouch! ;-).
`MATCHER' is the number of the one which is currently tried.

> Suppose I'm in the middle of ${$(...)}.  What's the context?  What's
> the context inside $'...'?

In the first case: `command', as always inside `$(...)'. For $'...':
same as '...'.

>  >   - `norestore':   this is always restored on exit of a function; if
>  >                    it is set on exit, the parameters above will not be 
>  > 		   reset to the values they had when the function was
>  > 		   entered
> 
> Let's try to avoid negatives, shall we?  Call it `restore' or `local' and
> have it default to set, and you unset it to prevent value restoration.  Or
> call it `scope' defaulting to `local' and you set it to `export' to make
> the other values not be restored.  But don't use a leading `no'.

Ok.

>  >   - `insert':      on entry this would be set to `menu', `automenu',
>  >                    `unambiguous'
> 
> This sounds OK too, but maybe `prefix' rather than `unambiguous'.
> Maybe.

I thought about `prefix', but decided against it since this hasn't to
be a prefix (even in older versions it could be a prefix and a suffix, 
with the matching stuff this could be a set of prefixes and suffixes).

> Two suggestions: (1) `exact' should be a possible value of the `insert'
> element mentioned above; (2) the element named `exact' should either be
> unset (when there is no exact match) or set to $word[CURRENT].  (I don't
> have a good argument for that setting, it just feels more useful than
> `yes' or `insert'.)

Again, I thought about exacly this, too. Setting `exact' to the
string: yes, possibly, I just couldn't think of something where we
might use it, but that wouldn't be a reason not to use it. But I tried 
to make the other keys contain only values that are used on entry and
after exit (with the same strings). So if we set `exact' to the match, 
the user may think that setting it to some string may make this string 
be inserted in the line. That is also the reason why I decided against 
using `exact' as one of the values for `insert'. If recexact and
automenu is set: which value should the completion code store in
`insert' (since it doesn't know if there will be an exact match
generated).

> How about another associative array called `menustate' that holds all
> these things?

As for the menu stuff, ok. But the list stuff isn't connected to
(only) menucompletion.

> The other possibility would be to automatically insert a dummy element 0
> into `words' when ksharrays is set, and automatically remove it when
> ksharrays changes.  That could be done without hooking into the option
> code if `words' was a special array with a special get-function.

Hadn't thought about that, yes maybe... (but it's the other way round, 
isn't it?)

Bye
 Sven


--
Sven Wischnowsky                         wischnow@informatik.hu-berlin.de