comments in completion

comments in completion

[Stefan Monnier]

A few months ago, there was a thread about programming completion for jobs.
For such a use, listing the available job numbers isn't quite what you want
because it's not very informative, so ech job number was annotated with its
corresponding command line. The annotation was originally done with '#' which
only works if you allow comments on the command line, so another suggestion was
done, using ";:", which mostly works just as well (except when you have ';' or
some such characters in the annotation, of course).
Another limitation of those two alternatives is that the annotation
terminates the command, so that it can't be used to do "kill %bla %bli".

What we really want is a way to put annotations that are understood by the
completion mechanism, so that they are printed when listing alternatives, but
they are not added to the command line.

This would come in handy for all completion of numbers like job numbers,
process ids, ...
And it would also be handy in order to provide online help for option flags,
like:

        > grep -[TAB]
        i - case insensitive
        n - print line numbers
        C - print surrounding context
        ...
        > grep -

I'm currently using 3.0.5 and there is no such thing in there, so is that
supposed to be coming up for zsh-3.2 or not yet ?


        Stefan

Re: comments in completion

[Bart Schaefer]

On Nov 16, 10:44am, Stefan Monnier wrote:
} Subject: comments in completion
}
} What we really want is a way to put annotations that are understood by the
} completion mechanism, so that they are printed when listing alternatives,
} but they are not added to the command line.

Isn't that what compctl -X is for?

compctl -P - -X 'A <num>  - show <num> lines of context after match
B <num>  - show <num> lines of context before match
<num>    - show <num> lines of context before and after match
C        - show 2 lines of context before and after match
E        - extended regular expression (egrep)
F        - fixed string expression (fgrep)
G        - basic regular expression (grep) 
L        - print only the names of files that do NOT have a match
V        - print version number
b        - prefix output with byte offset of each line
c        - print only a count of matching lines
h        - do not prefix lines with file names
i        - case insensitive match
l        - print only the names of files that have a match
n        - prefix output with line number of each line
q        - print nothing (set exit status only)
s        - do not print error messages
v        - select lines that DO NOT match the expression
w        - match expression against whole words only
x        - match expression against whole lines only
f <file> - read expressions from file <fil>
e        - expression follows' \
    -k '(A B C E F G L V b c e f h i l n q s v w x)' grep

} This would come in handy for all completion of numbers like job numbers,
} process ids, ...

The problem with job numbers and process IDs is that you have to generate
the explanation on the fly.  Maybe what we need is a way to run a function
to provide the -X output, rather than having only a fixed string.

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

Re: comments in completion

[Bruce Stephens]

schaefer@brasslantern.com said:
> The problem with job numbers and process IDs is that you have to
> generate the explanation on the fly.  Maybe what we need is a way to
> run a function to provide the -X output, rather than having only a
> fixed string. 

Yes, we definitely want this.  I've wanted for a while to get used to using 
the directory stack thingy (apart from just popd and the autopushd option), 
and having nice completion would be really useful for this.

A better way to do it might be to extend the programmable completion a bit, so 
the function could set both the list of possibilities and a list of 
descriptions of them.  That sounds a bit less hairy than yet another compctl 
flag, although I can see arguments both ways.

Re: comments in completion

[Bart Schaefer]

On Nov 17,  1:54pm, Bruce Stephens wrote:
} Subject: Re: comments in completion
}
} A better way to do it might be to extend the programmable completion a bit,
} so the function could set both the list of possibilities and a list of 
} descriptions of them.

It wouldn't have to be a list of descriptions; one string would be sufficient.
(That's the best you get now with -X anyway.)

My point was that you can't *just* extend the -K function.  You might have
perfectly good completion that doesn't use -K but that needs to compute an
explanation string.

It'd probably be sufficient to make a variant of -X that applies expansions
in the manner of -s.

BTW, compctl -s is mentioned in the summary but never explained in the text
of the zsh.texi that came with 3.0.5.

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

Re: comments in completion

[Bruce Stephens]

schaefer@brasslantern.com said:
> It wouldn't have to be a list of descriptions; one string would be
> sufficient. (That's the best you get now with -X anyway.)

> My point was that you can't *just* extend the -K function.  You might
> have perfectly good completion that doesn't use -K but that needs to
> compute an explanation string. 

Sure.  I must admit, I was thinking of the programmable ones, but you're quite 
right.

schaefer@brasslantern.com said:
> It'd probably be sufficient to make a variant of -X that applies
> expansions in the manner of -s. 

Wouldn't this be a bit clunky with programmable completion?  Surely if I'm 
using a function to generate completions (a list of jobs, or a list of 
suitable hostnames or whatever) then it would be natural to explain them 
there?  Am I misunderstanding something; I confess it feels a bit yucky to 
have two places where descriptions come from?

Re: comments in completion

[Bart Schaefer]

On Nov 17,  4:26pm, Bruce Stephens wrote:
} Subject: Re: comments in completion
}
} schaefer@brasslantern.com said:
} > It'd probably be sufficient to make a variant of -X that applies
} > expansions in the manner of -s. 
} 
} Wouldn't this be a bit clunky with programmable completion?

Depends on order of evaluation. :-)

} Surely if I'm 
} using a function to generate completions (a list of jobs, or a list of 
} suitable hostnames or whatever) then it would be natural to explain them 
} there?

Suppose I have the follwing; assume -Y is the expanding form of -X (mnemonic
is "why" :-) --

    compctl -K somefunc -Y '$somevar' somecommand

    somefunc() {
	reply=(some list of things)
	somevar="Some list of things means something"
    }

Now as long as "somefunc" runs before -Y performs its expansion, the value
of "somevar" is what "somefunc" wanted it to be.  This order of evaluation
ought to be possible, because the results of the function are needed before
zsh can even decide whether to print the explanation.

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