Re: Reading completion manual

[Sven Wischnowsky <wischnow@xxxxxxxxxxxxxxxxxxxxxxx>]

Andrej Borsenkow wrote:

> 1. compctl -K parameter
> 
> I don't like the new convention to make underscore magic. IMHO it is the
> same hack, as before, but it can possibly cause havoc. Underscore is pretty
> well established for "private" names, and I expect, that some users really
> use it in this way (I did at least). That is, define "helper" functions as
> started with underscore as opposed to "normal" ones that are expected to be
> called directly.
> 
> I think, the possible solutions are
> 
>  - use new option character (do we have one free?)
>  - implement long options
>  - (really wild one) implement name spaces.

Free option letters: `h' and `i' (plus non-letters, of course).

I wasn't too happy with the `_' convention either, I just used Bart's
suggestion (without making the underscore otherwise special). Considering
that namespaces are a separate issue, I'd vote for using an option
(`-_' would be a bad idea, right?). When we want to implement long
options, I'd vote for trying to make this in a more general way,
integrating it into the standard builtin code so that we can easily
add them to all builtins without having to change the functions for
the builtins (I already wrote this, I think).

> It may be useful to interpret return code from such a function (a lá -t).

Agreed. I was already searching for things we could do with the return 
value, but hadn't thought about `-t'. Any suggestions how the return
value of completion widgets and zle widgets could be used (when not
called from `-K' for the former)?

> 2. PREFIX, IPREFIX, SUFFIX
> 
> I'd like to have some way to atomically modify them. What I mean is, I'd
> expect it to be a common source of errors, when somebody modifies IPREFIX
> but forgets to modify PREFIX (or does it incorrectly). So, some command,
> that could be used to remove string from PREFIX *and* add it to IPREFIX as
> atomic operation is quite usable. I understand, that one may want to modify
> them independently, but this should be really unusual cases.

Cuurently this is part of the completion testing discussion going on
(since `-iprefix' does what you want). I expect that the final
solution will solve this, too.

> How *PERFIX and SUFFIX are related to words[$CURRENT]? When I modify PREFIX,
> does it change current word? Other way round? Or are they "read-only" (with
> exception of IPREFIX<->PREFIX relation)?

They are `normal' parameters in the sense that they are initially set
to the stuff from the line and you can do with them whatever you
want. There is no connection between `PREFIX/SUFFIX' and `words'. If
you view them as being `magic' such a connection would be the right
thing, but personally I prefer them to be `normal' and just initially
set to the stuff from the line.

> Do I understand correctly, that PREFIX/SUFFIX respect COMPLETE_IN_WORD? That
> should probably be explicitly mentioned.

Dunno if `respect' is the right word. `SUFFIX' will always be empty if 
`completeinword' is not set. The effect of `completeinword' is that
the whole completion system distinguishes a prefix and a suffix, so...

> 3. compgen
> 
> I never used explanation myself, but still ... What happens, if I use
> several compgen's with different explanation strings? What happens, if I use
> several compgen's with different listings (-y parameter)? Are they merged?
> If yes, how?

After implementing the completion correcting and playing with things a 
bit, I was planning to write something about this anyway, so I can
equally well do this here:

Explanations trings are always added to the group the matches are
added to and listed just before the matches in the group. But to be
able to correctly print the `%n' sequence that may appear in them, the 
completion code has a counter for each explanation string that gets
incremented for every match that is added with the explanation string
in effect and only those explanation strings will be shown for which
matches were added. E.g. with `compgen -fX foo' and `compgen -pX bar'
the string `foo' will only be shown if there were matching
filenames. Note also, that these counters count all matches for the
same string, so if the second one would be `compgen -pX foo', the
matches would be counted together with the matches for the first
`compgen'. I think this makes sense for `compctl' and `compgen', one
problem with this is that it makes `compadd -X foo' (without giving
matches) fail if no other matches were added with the same explanation 
string. But in this case it at least looks as if the explanation
string should just be added and shown, even if there are no matches. I 
was thinking about special casing this are about adding another option 
to compadd that allows one to give an explanation string that should
always be printed.

> 4. compadd
> 
> It's impossible to understand (based on manual) how -P, -p -i actually work
> (the same for suffixes). This definitely needs not only better description,
> but some examples as well. And how it all plays together with -W?

Yes, this is hairy. And the behavior was changed by two patches I sent
Monday and yesterday. I'm quite content with the way it works now, so
I'll add a description for it.

> Do I understand correctly, that normally compadd only adds strings if they
> match command line? It is implied, but is not stated explicitly.

Yes, like all the other completion builtins (and like all the other
builtins it has the `-U' option to make it ignore `what's on the line' --
which is what the `*PREFIX/SUFFIX' are set to for `comp{add,gen}').

> 5. compcall
> 
> As I vaguelly remember, compcall now returns result codes? Is it correct?

Which I forgot to document, yes.

> Applied to all three: what about some return code to indicate, if some
> matches were added? Currently one has to save, and then compare,
> compstate[nmatches], that looks somewhat ugly. Using return code would
> provide for
> 
> compgen -k friends || compgen -u
> 
> Looks better for me. Probably, this idea could be used for all helper
> functions as well - is it useful?

I agree that it looks nice. Currently I just used the `invalid option
returns non-zero status' convention used with most builtins. I
wouldn't like to change the return value for `compcall', though, since 
this is not really intended as a match generating builtin (it
currently uses the return value to indicate if a compctl was found
which is nice to have when one wants to do new completion stuff if no
compctl could be found).

> 6. Conditions
> 
> As most of us, I don't like the idea of conditions with side effects. But I
> don't like the Sven's suggestion of replacing conditions with shell code
> either (at least, with *THIS* code :-)

Is it really that complicated? Sniff. ;-)

> Even more, as it does not solve the
> original problem - you still have to save parameters and restore them after
> that.

I didn't consider this to be the `original problem'. But by forcing
the user to explicitly use shell code to do the test and modification
I thought it would be clear to everyone that one has to restore the
parameters after one has modified them.

> I'd suggest something in between - conditions set special parameters
> (elements of hash?) that can be used to extract matched substrings/words.
> That is almost the same, as Sven's suggestion, but probably more
> user-friendly :) something like
> 
> if [[ -between string1 string2 ]]; then
>    local -a nwords
>    nwords=(words[$FIRST,$LAST])
>     ...

That's like one of the things I described in 5386. I'm still not to
sure about it since it would still be `modifying' (not the parameters
giving information, but others).

> There is no way to say "from here to eternity", you are forced to set
> ``end'' to some silly large value. What about using literal string "end" as
> possible value for ``end''?

Do you mean `-between'? There is `-after', the replacement for
`compctl -x 'r[...]' (`r[...]' without a comma).

Bye
 Sven


--
Sven Wischnowsky                         wischnow@xxxxxxxxxxxxxxxxxxxxxxx