Re: Rough Draft of Article on Writing Completion Functions

Re: Rough Draft of Article on Writing Completion Functions

[Sven Wischnowsky]

John Beppu wrote:

> ...
> 
> The C<_arguments> function is a wrapper around the C<compadd>
> builtin like so many other auxiliary functions that come with Zsh.
> Ultimately, it is C<compadd> that takes a list of information and
> feeds it to the core of the completion system so that Zsh can
> display the results of a completion request on the terminal.  The
> other builtin to be aware of is C<compdef> which is used to bind
> completion functions to commands.  See the sidebar on C<compadd> and
> C<compdef> to see them being used in combination.

compdef is actually a function defined in compinit. And nowadays
there's not even specialised C-code behind it, just assocs and stuff.

> ...
> 
> However, on line 26, we encounter a new kind of option that takes an
> argument.  The C<-w> option tells I<figlet> how many characters wide the
> output should be, and it takes an integer as an argument.  There are
> only 2 differences here.  The first difference is that the option part
> has a + after it, so it says C<-w+>, now.  The + means that this option
> takes another argument.  The second difference is that there is an
> additional string after the description that is used as a hint when the
> user presses tab.  However, it is only visible when you've set your
> verbosity up as described in I<Preparations>.

A `+' after the option name means that the argument may come directly
after the option in the same word or in the next word. That there is
an argument to come is said by the `:descr:action' after the option
description.

And we normally suggest to not leave out the colon before the action
even if there is no action. Just to help _arguments to parse the stuff
(well, we had some problems which should be fixed, but...). Personally
I also find it a little less confusing with the trailing colon before
the empty action.

> Line 29 adds another variation.   Here we have an option, that takes an
> argument, that is easily predictable.  There are only 6 possible
> arguments that C<-I> can take, so after the hint, we list those 6
> arguments in parentheses.
> 
> Line 30 adds yet another variation.  The C<-d> option wants
> a directory as an argument, so we use the C<_path_files> function to
> build the list for us.  Like C<_arguments>, C<_path_files> is also a
> front-end to C<compadd>.

This should use _files. Everyone should use _files. Almost noone
should use _path_files. _files allows users to override glob patterns
and stuff.

> ...
> 
> However, when we use the state mechanism, we're going to fall through
> and hit line 36 to adjust the C<$fontdir> directory if necessary, and
> then on line 38, we're going to hit the case statement.  Based on the
> value of the C<$state> variable, we're either going to build a
> completion list for fonts or control files.  In both cases, we're going
> to use the C<_files> function which appropriately enough builds
> completion lists for files.  Using the C<-W> option, we root the search
> for completions in whatever C<$fontdir> is, and using the C<-g> option,
> we specify a glob pattern that limits which files are returned in the
> completion list.   In fact, the glob pattern is the only difference
> between font completion and control file completion, and even the glob
> pattern is only different by one letter.  What a waste of code.  Oh
> well.  At least it works, and it's not ugly.

An alternative to this and the stuff in sidebar 4 would be to declare
a local function, call it from the _arguments-actions and there give
it an argument of `flf' or `flc'.


Bye
  Sven

-- 
Sven Wischnowsky                          wischnow@berkom.de

Re: Rough Draft of Article on Writing Completion Functions

[John Beppu]

[  date  ] 2002/04/05 | Friday | 10:57 AM
[ author ] Peter Stephenson <pws@csr.com> 

> I deliberately didn't write a whole real-world completion function
> because there are already so many to look at, 

I think you should have done it, anyway.  I'll explain
why in a second.

> > The great tragedy of Zsh is that they actually made it very easy to
> > write completion functions, but you'd never know it by just
> > reading the documentation.
> 
> Hmm...  how much simpler than
> 
>   _foo() { compadd Yan Tan Tethera; }
>   compdef _foo foo
> 
> do I need to get?  This is the sort of hint I need from the puzzled.

Beginners don't need "simple".  They need "practical".
Would you tell some chump off the street:

    This is how to jab;
    This is a hook;
    This is an uppercut;
    Now go fight Mike Tyson.

Clearly, this guy is going to be unprepared for the task at hand.  

That's why a long practical example that explains the task of writing a
completion function from start to finish would have been helpful.

> I suggest you mention that you need zsh 4.0.x as a matter of priority,
> regardless of space limitations, or some people are going to get
> confused

OK.

Re: Rough Draft of Article on Writing Completion Functions

[John Beppu]

[  date  ] 2002/04/05 | Friday | 09:05 AM
[ author ] Sven Wischnowsky <wischnow@berkom.de> 

> compdef is actually a function defined in compinit. And nowadays
> there's not even specialised C-code behind it, just assocs and stuff.

fixed.
 
> A `+' after the option name means that the argument may come directly
> after the option in the same word or in the next word. That there is
> an argument to come is said by the `:descr:action' after the option
> description.

fixed.
 
> And we normally suggest to not leave out the colon before the action
> even if there is no action. Just to help _arguments to parse the stuff
> (well, we had some problems which should be fixed, but...). Personally
> I also find it a little less confusing with the trailing colon before
> the empty action.

I kinda hesitated on this one, but I did it, anyway.
fixed.
 
> This should use _files. Everyone should use _files. Almost noone
> should use _path_files. _files allows users to override glob patterns
> and stuff.

fixed.
 
> An alternative to this and the stuff in sidebar 4 would be to declare
> a local function, call it from the _arguments-actions and there give
> it an argument of `flf' or `flc'.

I was just being silly towards the end.  :-)

Re: Rough Draft of Article on Writing Completion Functions

[John Beppu]

[  date  ] 2002/04/05 | Friday | 11:15 AM
[ author ] Oliver Kiddle <okiddle@yahoo.co.uk> 

> >     If anything strikes you as being wrong, let me know.
> I couldn't see anything wrong besides what Sven has already picked up
> on. If you didn't get Sven's reply, it is because he seems to have sent
> it to zsh-workers only so check the mailing list archives.

Actually, I meant to send it to zsh-workers only, but I accidentally
sent it to zsh-users.  In mutt, I hit reply when the cursor was on that
message by that John guy who wanted a zsh equivalent of the bash
completion project.  Little did he know... haha.  But anyway, I got rid
of the In-Reply-To: header, but failed to notice the To: header said
zsh-users in it.

However, it seems as if I've helped at least one person on zsh-users who
had some nice things to say in a private email, so it was a fortunate
accident.

 
> Is there going to be any surrounding context or whatever from which
> it will be at least clear what zsh is?

I'm kinda hoping people can give it a glance, and figure out what zsh is
by using their intuition.
 

> > SUBHEAD: The Pros and Cons of the Various Sources of Information
> 
> You could also mention the mailing lists as a source of information in
> this section. Though they probably aren't so much a starting point as a
> place to go later.

I had the same feeling, but I didn't know where to put it, and by the
time I got to the end of writing, I forgot about it.  I think I'll
mention it somewhere in the concluding parts.

 
> > You don't need to know a lot more than this to effectively write
> > completion functions, so without further adieu, let's look at an
> 
> I thought that phrase was normally `further ado', or am I wrong.

I looked into that, and it turns out you're right.  There is a French
adieu that means goodbye, and it's totally unrelated to the English ado
which has the meaning that I actually wanted.  Good catch.

 
> > [ BEGIN SIDEBAR 4 - Refinements ]
> > 
> > [ JSB: this entire sidebar is optional ]
> > 
> > Oliver Kiddle from the zsh-workers mailing list suggested the following
> > improvements to I<_figlet>.
> 
> If this sidebar doesn't make it in you could mention briefly that the
> _figlet that will be distributed with the next version of zsh includes
> a few improvements.

OK.

I think how I'll do it is by putting a comment in the code listing
with a message that states that there's a new and improved one coming
up.  The only reason I didn't use your suggestions in the main listing
was that I wanted to show people how states worked.


    Peace,
    beppu


PS: I have some urgent business to take care of, and I might not have
    the time to address some of the comments I saw on zsh-workers until
    tomorrow or even Sunday.  I've read them, and I have replies to them
    stewing in my mind, but I don't have time to write them down.
    Please be patient with me.