Re: Rough Draft of Article on Writing Completion Functions

[Sven Wischnowsky <wischnow@xxxxxxxxx>]

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@xxxxxxxxx