RE: Passsing descriptions down in completion functions

RE: Passsing descriptions down in completion functions

[Borzenkov Andrey]

> 
> The general question - should completion functions ever accept (be used
> with) other options than compadd? If not the above is perfectly valid and
> probably more simple that modifying every single function. If yes, here is
> the list of functions that use _wanted without '-'.
> 

Well, I started to look into these functions and immediately hit some
problems:

AIX/Type/_object_classes:

_wanted objectclasses expl 'object class' \
   _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc'

Here is just no place where I could stuff the magic "-". Granted, this one
does not pass arguments it receives but in general I do not see why it
should not do it.

Base/Utility/_sub_commands

if [[ CURRENT -eq 2 ]]; then
  _wanted commands expl command compadd "$@"
else
  _message 'no more arguments'
fi

almost the same problem. In this case arguments contain both description and
matches so I have no way to stuff "-" in between.

-andrey

Re: Passsing descriptions down in completion functions

[Oliver Kiddle]

On 9 Jan, you wrote:
> 
> Well, I started to look into these functions and immediately hit some
> problems:
>
> AIX/Type/_object_classes:
> 
> _wanted objectclasses expl 'object class' \
>    _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc'
> 
> Here is just no place where I could stuff the magic "-". Granted, this one
> does not pass arguments it receives but in general I do not see why it
> should not do it.

I think you can put the "-" on the end of the line like this:
  _wanted ... \
     _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc' "$@" -

> Base/Utility/_sub_commands
> 
> if [[ CURRENT -eq 2 ]]; then
>   _wanted commands expl command compadd "$@"
> else
>   _message 'no more arguments'
> fi
> 
> almost the same problem. In this case arguments contain both description and
> matches so I have no way to stuff "-" in between.

That's a slightly unusual case because any matches passed to
_sub_commands could be thought of as not being arguments to compadd to
be passed on in the traditional sense. It is probably best handled by
passing a "-" in the calling function.

I agree that this isn't particularly ideal though. I remember Sven
saying something about rethinking the way compadd options are passed
but I was mostly thinking in terms of suffixes and not descriptions.
It'd be wise to think in terms of all the compadd options and how they
are passed around in coming up with a good solution.

A variant of your _all_labels suggestion is perhaps not a bad idea. I'd
want to be able to override any passed descriptions in some cases.

Oliver

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.

RE: Passsing descriptions down in completion functions

[Borzenkov Andrey]

> On 9 Jan, you wrote:
> >
> > Well, I started to look into these functions and immediately hit some
> > problems:
> >
> > AIX/Type/_object_classes:
> >
> > _wanted objectclasses expl 'object class' \
> >    _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc'
> >
> > Here is just no place where I could stuff the magic "-". Granted, this
> one
> > does not pass arguments it receives but in general I do not see why it
> > should not do it.
> 
> I think you can put the "-" on the end of the line like this:
>   _wanted ... \
>      _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc' "$@" -
> 

But you cannot know in advance how _arbitrary_ completion function would
react to stray "-"

> > Base/Utility/_sub_commands
> >
> > if [[ CURRENT -eq 2 ]]; then
> >   _wanted commands expl command compadd "$@"
> > else
> >   _message 'no more arguments'
> > fi
> >
> > almost the same problem. In this case arguments contain both description
> and
> > matches so I have no way to stuff "-" in between.
> 
> That's a slightly unusual case because any matches passed to
> _sub_commands could be thought of as not being arguments to compadd to
> be passed on in the traditional sense. It is probably best handled by
> passing a "-" in the calling function.
> 

Snowball effect :(

> I agree that this isn't particularly ideal though. I remember Sven
> saying something about rethinking the way compadd options are passed
> but I was mostly thinking in terms of suffixes and not descriptions.
> It'd be wise to think in terms of all the compadd options and how they
> are passed around in coming up with a good solution.
> 

Yep. I was thinking mostly not about special way to pass arguments (unless
absolutely needed) but rather about documented discipline. Approximately

- every completion function (i.e. function that generates matches, directly
or indirectly) must accept all compadd options, must not change their
semantic and must pass them down to any other function it calls (except as
noted below). It limits options, available for private use, but in general I
hope usage of special options should not be widespread. Or we can reserve a
special option for quoting, like gcc does it

_foo ...-normal compadd options... -X -my-option -X my-option-argument
...-normal compadd options...

(-X is taken, I know). This is relatively easy to do assuming all functions
are using zparseopts

- low level completion utilities _never_ modify passed options, it is simply
not their business.

> A variant of your _all_labels suggestion is perhaps not a bad idea. I'd
> want to be able to override any passed descriptions in some cases.
>

then do it in completion function that actually needs it (I presume it is
actually a minority). Replace passed arguments with your own. This needs
some utility, we just need to think about the best way to do it. Probably as
an option to zparseopts or something like

zmergeopts [options] current new

where options would be "override", "preserve" and probably more.

This allows such functions as _wanted (or _all_labels) to extract options
from passed command and possibly merge them with generated description if
needed. Extracting options may need some extra utility as well.

Any comments?

-andrey

Re: Passsing descriptions down in completion functions

[Oliver Kiddle]

On 10 Jan, Andrey wrote:
>
> > On 9 Jan, you wrote:
> > > Here is just no place where I could stuff the magic "-". Granted, this
> > one
> > > does not pass arguments it receives but in general I do not see why it
> > > should not do it.
> > 
> > I think you can put the "-" on the end of the line like this:
> >   _wanted ... \
> >      _files -W ${ODMDIR:-/etc/objrepos} -g '^*.vc' "$@" -
> > 
> 
> But you cannot know in advance how _arbitrary_ completion function would
> react to stray "-"

Quoting from Etc/completion-style-guide:

      _all_labels foo expl 'descr...' _combination ... -

    And the `-' will be replaced by the options that are to be given to
    `compadd'.

So if there is one `-' argument and it is the last on the line, it is
removed by _all_labels.

> > > Base/Utility/_sub_commands
> > >
> > > if [[ CURRENT -eq 2 ]]; then
> > >   _wanted commands expl command compadd "$@"
> > > else
> > >   _message 'no more arguments'
> > > fi
> > >
> > > almost the same problem. In this case arguments contain both description
> > and
> > > matches so I have no way to stuff "-" in between.
> > 
> > That's a slightly unusual case because any matches passed to
> > _sub_commands could be thought of as not being arguments to compadd to
> > be passed on in the traditional sense. It is probably best handled by
> > passing a "-" in the calling function.
> 
> Snowball effect :(

Okay, perhaps _sub_commands should split its options and insert the `-'
itself. It is a sufficiently special case not to worry me.

> Yep. I was thinking mostly not about special way to pass arguments (unless
> absolutely needed) but rather about documented discipline. Approximately

There is an extent to which there is existing documented discipline if
you take Etc/completion-style-guide together with the documentation.
The fact that it was only loosely adhered to being another matter.

> Or we can reserve a
> special option for quoting, like gcc does it
> 
> _foo ...-normal compadd options... -X -my-option -X my-option-argument
> ...-normal compadd options...
> 
> (-X is taken, I know). This is relatively easy to do assuming all functions
> are using zparseopts

That's a bit like the opposite of the -O option to _arguments for
passing compadd options. I fear it could make the functions less easy
to read relative to just taking care to choose option letters that
aren't compadd options.

> - low level completion utilities _never_ modify passed options, it is simply
> not their business.

Depends what you define as "low level". That is easy for something like
_hosts that just completes something. What do you do with a suffix (-S
option) if you're completing the user part in  _user_at_host?

As an aside, I don't like the _files behaviour of appending passed
suffixes to directories instead of a slash.

> > A variant of your _all_labels suggestion is perhaps not a bad idea. I'd
> > want to be able to override any passed descriptions in some cases.

> then do it in completion function that actually needs it (I presume it is
> actually a minority). Replace passed arguments with your own. This needs
> some utility, we just need to think about the best way to do it. Probably as
> an option to zparseopts or something like

Thinking about "the best way to do it" is the hard part and I've yet to
think of anything which seems better than the current system.

Oliver

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.

Re: Passsing descriptions down in completion functions

[Oliver Kiddle]

On 9 Jan, you wrote:
> 
> Sure, I understand that. We already discussed it and I still think that
> instead of modifying every completion function _all_labels should just check
> for existing options and not add them (are there more than just -X? As I

-J and perhaps also -V, -E, -1 and -2. It'd be hard to know which to
check for.

> understand the only options that can be modified by _all_labels are those
> used for explanations. It does not look all that simple after reviewing
> _all_labels but it should be doable).

There are cases where you do want to override any passed descriptions
such as where a function completes something in parts (e.g. in _urls)
but you might want to pass on other options. I'm not too sure about
your suggested change to _all_labels because the result would be less
flexible. If you wanted a solution like that, it might be better to
always add explanations to the end of the options unless some option
was passed to _all_labels. I think the current system is simpler but
will concede that modifying all the functions will be a bore. I'll
volunteer for the job if we agree on doing that though.

> The general question - should completion functions ever accept (be used
> with) other options than compadd? If not the above is perfectly valid and
> probably more simple that modifying every single function. If yes, here is
> the list of functions that use _wanted without '-'.

Quite a few functions accept non compadd options though zparseopts can
easily strip them before they get passed to compadd. Provided they
don't conflict, I don't see a problem with this.

Oliver

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.

RE: Passsing descriptions down in completion functions

[Borzenkov Andrey]

> 
> compadd takes the first description on the line so a function like
> _hosts needs to add any explanations after those that have been passed
> as arguments.
> 
> _hosts does roughly:
>   _wanted hosts expl host compadd "$@" -a hosts
> 
> which is turned into the compadd line you quoted above. The explanation
> arguments added by _wanted are inserted before a `-' argument so if you
> rewrite the last line of _hosts as:
>   _wanted hosts expl host compadd "$@" - $hosts
> It will work.
> 
> The first bug (in my opinion) is that
>   _wanted hosts expl host compadd "$@" -a hosts -
> does not work because any explanation arguments after the -a option are
> ignored.
> 
> The second bug is that there are loads of functions like _hosts which
> don't use this `-' argument trick, mainly because the _wanted feature
> was added later and nobody ever went through adding it to all the
> existing functions.
> 

Sure, I understand that. We already discussed it and I still think that
instead of modifying every completion function _all_labels should just check
for existing options and not add them (are there more than just -X? As I
understand the only options that can be modified by _all_labels are those
used for explanations. It does not look all that simple after reviewing
_all_labels but it should be doable).

The general question - should completion functions ever accept (be used
with) other options than compadd? If not the above is perfectly valid and
probably more simple that modifying every single function. If yes, here is
the list of functions that use _wanted without '-'.


AIX/Command/_smit
AIX/Type/_object_classes
Base/Completer/_expand_alias
Base/Completer/_history
Base/Utility/_sub_commands
Debian/Command/_auto-apt
Debian/Command/_bts
Debian/Command/_debfoster
Linux/Command/_modutils
Mandrake/Command/_urpmi
Redhat/Command/_rpm
Unix/Command/_ant
Unix/Command/_archie
Unix/Command/_arp
Unix/Command/_cdcd
Unix/Command/_chkconfig
Unix/Command/_chown
Unix/Command/_cpio
Unix/Command/_cvs
Unix/Command/_gdb
Unix/Command/_gprof
Unix/Command/_iconv
Unix/Command/_imagemagick
Unix/Command/_java
Unix/Command/_make
Unix/Command/_man
Unix/Command/_mh
Unix/Command/_mtools
Unix/Command/_mysql_utils
Unix/Command/_ncftp
Unix/Command/_nslookup
Unix/Command/_pbm
Unix/Command/_rcs
Unix/Command/_rlogin
Unix/Command/_rsync
Unix/Command/_ruby
Unix/Command/_samba
Unix/Command/_sccs
Unix/Command/_ssh
Unix/Command/_stty
Unix/Command/_tar
Unix/Command/_telnet
Unix/Command/_whois
Unix/Command/_yp
Unix/Command/_zip
Unix/Type/_directories
Unix/Type/_domains
Unix/Type/_file_systems
Unix/Type/_groups
Unix/Type/_hosts
Unix/Type/_java_class
Unix/Type/_locales
Unix/Type/_newsgroups
Unix/Type/_perl_basepods
Unix/Type/_perl_builtin_funcs
Unix/Type/_perl_modules
Unix/Type/_pids
Unix/Type/_ports
Unix/Type/_printers
Unix/Type/_time_zone
Unix/Type/_urls
Unix/Type/_user_at_host
Unix/Type/_users
X/Command/_mozilla
X/Command/_netscape
X/Command/_xauth
X/Type/_x_color
X/Type/_x_cursor
X/Type/_x_extension
X/Type/_x_font
X/Type/_x_keysym
Zsh/Command/_alias
Zsh/Command/_bindkey
Zsh/Command/_builtin
Zsh/Command/_cd
Zsh/Command/_command
Zsh/Command/_compdef
Zsh/Command/_echotc
Zsh/Command/_echoti
Zsh/Command/_hash
Zsh/Command/_unhash
Zsh/Command/_zcompile
Zsh/Command/_zftp
Zsh/Command/_zle
Zsh/Command/_zpty
Zsh/Command/_zstyle
Zsh/Context/_equal
Zsh/Context/_subscript
Zsh/Context/_value
Zsh/Type/_arrays
Zsh/Type/_directory_stack
Zsh/Type/_file_descriptors
Zsh/Type/_functions
Zsh/Type/_limits
Zsh/Type/_options
Zsh/Type/_options_set
Zsh/Type/_options_unset

-andrey

Re: Passsing descriptions down in completion functions

[Oliver Kiddle]

I wrote:
> The first bug (in my opinion) is that
>   _wanted hosts expl host compadd "$@" -a hosts -
> does not work because any explanation arguments after the -a option are
> ignored.

I've just realised that this is wrong because -a is just a flag, with
hosts not being an argument to -a. So _hosts should do:
  _wanted hosts expl host compadd "$@" -a - hosts

And a similar change is needed across many of the completion functions.

Oliver

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.

Passsing descriptions down in completion functions

[Borzenkov Andrey]

Either I do not understand something basic or it does not work (and probably
has never working really).

Simple example.

bor@itsrm2% functions _foo
_foo () {
        _arguments -s "-p[some option]:argument for this option:_hosts"
}
bor@itsrm2% compdef _foo foo
bor@itsrm2% foo -p TAB
bor@itsrm2% foo -p D248H032
Completing host
           ^^^^ should it not be "argument for that option"?
D248H032               GH4090Y0               anyhost
...

It is clear what happens:

+_arguments:340> _hosts -J option-p-1 -X '%BCompleting argument for this
option%b'

this sounds good, but later on ...

+_all_labels:37> compadd -J hosts -X '%BCompleting host%b' -M
'm:{a-zA-Z}={A-Za-z} r:|.=* r:|=*' -J option-p-1 -X '%BCompleting argument
for this option%b' -a hosts

Oops, description is now lost.

Quoting documentation:

                                              If the ACTION starts
     with a space, this list of words will be invoked unchanged,
     otherwise it will be invoked with some extra strings placed after
     the first word which can be given as arguments to the compadd
     builtin command and which make sure that the MESSAGE given in the
     description will be shown above the matches.

So, is it a bug or not?

-andrej