Re: how to use tags in zsh completion system

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

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