how to use tags in zsh completion system

how to use tags in zsh completion system

[Ahmad Ismail]

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

The [documentation][1] says

>     zstyle ':completion:*:aliens:*' tag-order \
>       'frooble:-funny:funny\ frooble' frooble
>which is used when you're completing for the command aliens, which
presumably has completions tagged as `frooble' ...

I understand that both context and tag can be viewed using <kbd>^Xh</kbd>.
So, I tried the following command but suggestion did not show the tags.

    % zstyle ':completion:*:aliens:*' tag-order 'frooble:-funny:funny\
frooble' frooble
    % aliens <kbd>TAB</kbd>
    Completing file
    Desktop/       Documents/     dotfiles/      Downloads/
    % aliens <kbd>^Xh</kbd>
    tags in context :completion::complete:aliens::
        globbed-files  (_files _default)
    % aliens frooble <kbd>^Xh</kbd>
    tags in context :completion::complete:aliens::
        globbed-files  (_files _default)

I think I am doing something wrong with

> completions tagged as `frooble'

Please help me understand how to use tags in zsh completion system.


  [1]: http://zsh.sourceforge.net/Guide/zshguide06.html#l155

[-- Attachment #2: Type: text/html, Size: 1363 bytes --]

Re: how to use tags in zsh completion system

[Peter Stephenson]

> On 26 August 2020 at 09:59 Ahmad Ismail <ismail783@gmail.com> wrote:
> The [documentation][1] says
> 
> >     zstyle ':completion:*:aliens:*' tag-order \
> >       'frooble:-funny:funny\ frooble' frooble
> >which is used when you're completing for the command aliens, which
> presumably has completions tagged as `frooble' ...
> 
> I understand that both context and tag can be viewed using <kbd>^Xh</kbd>.
> So, I tried the following command but suggestion did not show the tags.
> 
>     % zstyle ':completion:*:aliens:*' tag-order 'frooble:-funny:funny\
> frooble' frooble
>     % aliens <kbd>TAB</kbd>
>     Completing file
>     Desktop/       Documents/     dotfiles/      Downloads/
>     % aliens <kbd>^Xh</kbd>
>     tags in context :completion::complete:aliens::
>         globbed-files  (_files _default)
>     % aliens frooble <kbd>^Xh</kbd>
>     tags in context :completion::complete:aliens::
>         globbed-files  (_files _default)
> 
> I think I am doing something wrong with
> 
> > completions tagged as `frooble'
> 
> Please help me understand how to use tags in zsh completion system.

Hi Ahmad,

That section in the guide is actually just an example of how things work
using an invented command --- your understanding is basically correct but
actually there is no "aliens" command.

Just off the top of my head (other people may have their own favourite
examples), one interesting command with a number of different tags
that apply at the start of completion is scp: ^xh for that gives me

tags in context :completion::complete:scp::
    argument-rest options  (_arguments _ssh _ssh)
tags in context :completion::complete:scp:argument-rest:
    files hosts users  (_ssh _ssh) 
    globbed-files      (_files _ssh _ssh) 
    hosts              (_hosts _combination _ssh_hosts _ssh _ssh) 
    users              (_users _combination _ssh_users _ssh _ssh)

so that might be something to play with.

(Alternatively, if I got my act together I could probably write
a fake completion for "aliens" that actually did what the guide
says...)

Cheers
pws

Re: how to use tags in zsh completion system

[Ahmad Ismail]

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

Hi Peter Stephenson,

This is the first time I am using a mailing list. So, I am not sure whether
I am doing it correctly or not.

Do I need to always refer to my previous mail or will you be able to figure
out my previous mails?
Do I need to view my email and its correspondence from
https://www.zsh.org/mla/ or everything will be in the inbox?

Being said that, I tried:

% scp
tags in context :completion::complete:scp::
    argument-rest options  (_arguments _ssh _ssh)
tags in context :completion::complete:scp:argument-rest:
    files hosts users  (_ssh _ssh)
    globbed-files      (_files _ssh _ssh)
    hosts              (_hosts _combination _ssh_hosts _ssh _ssh)
    users              (_users _combination _ssh_users _ssh _ssh)

% scp hosts
tags in context :completion::complete:scp::
    argument-rest options  (_arguments _ssh)
tags in context :completion::complete:scp:argument-rest:
    files hosts users  (_ssh)
    globbed-files      (_files _ssh)
    hosts              (_hosts _combination _ssh_hosts _ssh)
    users              (_users _combination _ssh_users _ssh)

I am sorry, I can not understand what the output means.

The documentation says:

"typically indicating a class of object that the user may need to
distinguish."

"Unlike the contexts (which tell you how completion arrived at the point it
did), the tags describe the things it can complete here."

If you will be kind enough to explain with the example you were talking
about then it would be very helpful for me.

If you kindly make a completion function with more than one tag (Ex.
frooble1, frooble2, frooble3) and description of how they were useful. And
how that function can be used with `zstyle ':completion:*:aliens:*'....`
then I will be very glad.


*Thanks and Best Regards,Ahmad Ismail*

On Wed, Aug 26, 2020 at 4:57 PM Peter Stephenson <
p.w.stephenson@ntlworld.com> wrote:

> > On 26 August 2020 at 09:59 Ahmad Ismail <ismail783@gmail.com> wrote:
> > The [documentation][1] says
> >
> > >     zstyle ':completion:*:aliens:*' tag-order \
> > >       'frooble:-funny:funny\ frooble' frooble
> > >which is used when you're completing for the command aliens, which
> > presumably has completions tagged as `frooble' ...
> >
> > I understand that both context and tag can be viewed using
> <kbd>^Xh</kbd>.
> > So, I tried the following command but suggestion did not show the tags.
> >
> >     % zstyle ':completion:*:aliens:*' tag-order 'frooble:-funny:funny\
> > frooble' frooble
> >     % aliens <kbd>TAB</kbd>
> >     Completing file
> >     Desktop/       Documents/     dotfiles/      Downloads/
> >     % aliens <kbd>^Xh</kbd>
> >     tags in context :completion::complete:aliens::
> >         globbed-files  (_files _default)
> >     % aliens frooble <kbd>^Xh</kbd>
> >     tags in context :completion::complete:aliens::
> >         globbed-files  (_files _default)
> >
> > I think I am doing something wrong with
> >
> > > completions tagged as `frooble'
> >
> > Please help me understand how to use tags in zsh completion system.
>
> Hi Ahmad,
>
> That section in the guide is actually just an example of how things work
> using an invented command --- your understanding is basically correct but
> actually there is no "aliens" command.
>
> Just off the top of my head (other people may have their own favourite
> examples), one interesting command with a number of different tags
> that apply at the start of completion is scp: ^xh for that gives me
>
> tags in context :completion::complete:scp::
>     argument-rest options  (_arguments _ssh _ssh)
> tags in context :completion::complete:scp:argument-rest:
>     files hosts users  (_ssh _ssh)
>     globbed-files      (_files _ssh _ssh)
>     hosts              (_hosts _combination _ssh_hosts _ssh _ssh)
>     users              (_users _combination _ssh_users _ssh _ssh)
>
> so that might be something to play with.
>
> (Alternatively, if I got my act together I could probably write
> a fake completion for "aliens" that actually did what the guide
> says...)
>
> Cheers
> pws
>

[-- Attachment #2: Type: text/html, Size: 6135 bytes --]

Re: how to use tags in zsh completion system

[Peter Stephenson]

> On 26 August 2020 at 12:28 Ahmad Ismail <ismail783@gmail.com> wrote:
> 
> Hi Peter Stephenson,
> 
> This is the first time I am using a mailing list. So, I am not sure whether
> I am doing it correctly or not.
> 
> Do I need to always refer to my previous mail or will you be able to figure
> out my previous mails?

Usually people quote the most relevant sections, but people won't
expect to be able to reconstruct the entire thread from a single email

> Do I need to view my email and its correspondence from
> https://www.zsh.org/mla/ or everything will be in the inbox?

If you're not on the list, people should copy you so you will see
everything (it's useful to mention if you're not on the list).

If you are on the list, you'll get everything anyway.

> Being said that, I tried:
>
> % scp hosts

You're missing the point here.  A tag is entirely an idea within the
completion system itself.  Most commands you can just type <TAB>
and it will complete for you.  Only very occasionally do you
need to configure it do something else.  When you do,
then you put commands involving tags in your intialisation file.
You never need to type them on the command line.

So at this point, the completion system already knows various things
are possible --- a host name, a file, a username --- depending how
you're going to build the command line.  The tags are just logical
names for these things.  (The completion system does a bit
of guesswork about where to find things that are specific to
the scp command, so occasionally it needs a bit of help there.)

If you're just starting from scratch with the completion system, i
suggest you just ignore tags for now.  The system is designed so
most of the time it should "just work".

If you find a case where you actually need to tell it to be cleverer,
that's the time to start thinking about tags.  That would be a
case where multiple completions are possible, but you decide you
need to complete only one type of thing.  That's a rather
advanced use.

Until then, I should just try using the system "out of the box"
and see how that works for you.

Cheers
pws

Re: how to use tags in zsh completion system

[Ahmad Ismail]

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

Hi Peter Stephenson,

Thank you very much for the guideline. I was hung up with the tags. I
better ignore it for now.


*Best Regards,Ahmad Ismail*

On Wed, Aug 26, 2020 at 6:01 PM Peter Stephenson <
p.w.stephenson@ntlworld.com> wrote:

> > On 26 August 2020 at 12:28 Ahmad Ismail <ismail783@gmail.com> wrote:
> >
> > Hi Peter Stephenson,
> >
> > This is the first time I am using a mailing list. So, I am not sure
> whether
> > I am doing it correctly or not.
> >
> > Do I need to always refer to my previous mail or will you be able to
> figure
> > out my previous mails?
>
> Usually people quote the most relevant sections, but people won't
> expect to be able to reconstruct the entire thread from a single email
>
> > Do I need to view my email and its correspondence from
> > https://www.zsh.org/mla/ or everything will be in the inbox?
>
> If you're not on the list, people should copy you so you will see
> everything (it's useful to mention if you're not on the list).
>
> If you are on the list, you'll get everything anyway.
>
> > Being said that, I tried:
> >
> > % scp hosts
>
> You're missing the point here.  A tag is entirely an idea within the
> completion system itself.  Most commands you can just type <TAB>
> and it will complete for you.  Only very occasionally do you
> need to configure it do something else.  When you do,
> then you put commands involving tags in your intialisation file.
> You never need to type them on the command line.
>
> So at this point, the completion system already knows various things
> are possible --- a host name, a file, a username --- depending how
> you're going to build the command line.  The tags are just logical
> names for these things.  (The completion system does a bit
> of guesswork about where to find things that are specific to
> the scp command, so occasionally it needs a bit of help there.)
>
> If you're just starting from scratch with the completion system, i
> suggest you just ignore tags for now.  The system is designed so
> most of the time it should "just work".
>
> If you find a case where you actually need to tell it to be cleverer,
> that's the time to start thinking about tags.  That would be a
> case where multiple completions are possible, but you decide you
> need to complete only one type of thing.  That's a rather
> advanced use.
>
> Until then, I should just try using the system "out of the box"
> and see how that works for you.
>
> Cheers
> pws
>

[-- Attachment #2: Type: text/html, Size: 4075 bytes --]

Re: how to use tags in zsh completion system

[Daniel Shahaf]

Elaborating per the request in users/26049.

Peter Stephenson wrote on Wed, 26 Aug 2020 11:57 +0100:
> > Please help me understand how to use tags in zsh completion system.  
> 
> Just off the top of my head (other people may have their own favourite
> examples), one interesting command with a number of different tags
> that apply at the start of completion is scp: ^xh for that gives me
> 
> tags in context :completion::complete:scp::
>     argument-rest options  (_arguments _ssh _ssh)
> tags in context :completion::complete:scp:argument-rest:
>     files hosts users  (_ssh _ssh) 
>     globbed-files      (_files _ssh _ssh) 
>     hosts              (_hosts _combination _ssh_hosts _ssh _ssh) 
>     users              (_users _combination _ssh_users _ssh _ssh)
> 
> so that might be something to play with.

The scp(1) command can be invoked in several different ways:
.
    scp $localfile ${remotehost}:
    scp $remoteuser@$remotehost: $localfile
    scp ${remotehost}: $localfile
.
Thus, «scp <TAB>» completes three kinds of things: local files,
usernames for remote login, and hostnames for remote login.  

The completion system knows what type of thing each possible
completion is.  Each tag — in this example, "files", "hosts",
"users", and "globbed-files" — corresponds to a single "type of thing"
that can be completed at that point.  (I'm not sure how "globbed-files"
gets there, but you needn't worry about that right now.)

You can see completions grouped by tag by setting the group-name style:

    $ zsh -f
    % autoload compinit
    % compinit
    % zstyle :completion:\* group-name '' 
    % zstyle :completion:\*:descriptions format '→ %d' 
    % scp <TAB>
    → file
    bar.txt foo.txt
    → remote host name
    hermes.example.org localhost
    → user
    danielsh root

You can reorder the three groups of candidate completions by setting the
tag-order style appropriately.  For example, «zstyle \* tag-order users
hosts files» will show the groups in a different order than above.

Tag names are also part of the zstyle context string (the thing context
patterns are matched against), so styles can be set for some tags but
not others.  For example, «zstyle ':completion:*:options' prefix-hidden true»
will set the prefix-hidden style whilst listing candidate completions
that are options, but not whilst listing other candidate completions.

As Peter said elsethread, you can generally forget about tags unless
you're either configuring completion system or writing your own
completion function (which you wouldn't generally need to do, unless
you wrote a custom command as well).

Cheers,

Daniel

Re: how to use tags in zsh completion system

[Ahmad Ismail]

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

Hi Daniel Shahaf,

Thank you very much for explaining tags. I am grateful to you.

*Thanks and Best Regards,Ahmad Ismail*


On Sat, Sep 5, 2020 at 1:23 AM Daniel Shahaf <d.s@daniel.shahaf.name> wrote:

> Elaborating per the request in users/26049.
>
> Peter Stephenson wrote on Wed, 26 Aug 2020 11:57 +0100:
> > > Please help me understand how to use tags in zsh completion system.
> >
> > Just off the top of my head (other people may have their own favourite
> > examples), one interesting command with a number of different tags
> > that apply at the start of completion is scp: ^xh for that gives me
> >
> > tags in context :completion::complete:scp::
> >     argument-rest options  (_arguments _ssh _ssh)
> > tags in context :completion::complete:scp:argument-rest:
> >     files hosts users  (_ssh _ssh)
> >     globbed-files      (_files _ssh _ssh)
> >     hosts              (_hosts _combination _ssh_hosts _ssh _ssh)
> >     users              (_users _combination _ssh_users _ssh _ssh)
> >
> > so that might be something to play with.
>
> The scp(1) command can be invoked in several different ways:
> .
>     scp $localfile ${remotehost}:
>     scp $remoteuser@$remotehost: $localfile
>     scp ${remotehost}: $localfile
> .
> Thus, «scp <TAB>» completes three kinds of things: local files,
> usernames for remote login, and hostnames for remote login.
>
> The completion system knows what type of thing each possible
> completion is.  Each tag — in this example, "files", "hosts",
> "users", and "globbed-files" — corresponds to a single "type of thing"
> that can be completed at that point.  (I'm not sure how "globbed-files"
> gets there, but you needn't worry about that right now.)
>
> You can see completions grouped by tag by setting the group-name style:
>
>     $ zsh -f
>     % autoload compinit
>     % compinit
>     % zstyle :completion:\* group-name ''
>     % zstyle :completion:\*:descriptions format '→ %d'
>     % scp <TAB>
>     → file
>     bar.txt foo.txt
>     → remote host name
>     hermes.example.org localhost
>     → user
>     danielsh root
>
> You can reorder the three groups of candidate completions by setting the
> tag-order style appropriately.  For example, «zstyle \* tag-order users
> hosts files» will show the groups in a different order than above.
>
> Tag names are also part of the zstyle context string (the thing context
> patterns are matched against), so styles can be set for some tags but
> not others.  For example, «zstyle ':completion:*:options' prefix-hidden
> true»
> will set the prefix-hidden style whilst listing candidate completions
> that are options, but not whilst listing other candidate completions.
>
> As Peter said elsethread, you can generally forget about tags unless
> you're either configuring completion system or writing your own
> completion function (which you wouldn't generally need to do, unless
> you wrote a custom command as well).
>
> Cheers,
>
> Daniel
>

[-- Attachment #2: Type: text/html, Size: 4560 bytes --]