Re: A Completion Function for FIGlet

[Oliver Kiddle <okiddle@xxxxxxxxxxx>]

John Beppu wrote:

> The attached file contains a completion function for figlet[1] that I just
> finished writing, and I would like to donate it to the zsh distribution.

Great. Thanks.

> I don't think I've done anything terrible, but then again, this is 
> my first completion function, so it wouldn't be surprising if I made
> a few mistakes.  If there's anything wrong w/ it, please let me know.

It looks good. I can't see much which is as such wrong.

> I also have a few questions:
> 
>   regarding $opt_args
>     Is it only set when you use the '->state' mechanism?
>     It seems to be empty, otherwise.

No. It is set by the call to _arguments which is probably later than
you wanted. In this case, you can do the following though:

  '-f+[font]:font:_files -W ${~opt_args[-d]\:-$fontdir} -g \*flf\*' \
  '-C+[control file]:control file:_files -W ${~opt_args[-d]\:-$fontdir} -g \*flc\*' \

_arguments will evaluate the reference to opt_args before calling
_files so it works.

>   arguments to _arguments
>     The following is a line from the completion function:
> 
>         "-d+[directory]:directory:_path_files -/" \
>                         ^^^^^^^^^
> 
>     What is the purpose of the underlined string?
>     When might this string be useful to someone who is
>     writing completion functions?  Is their a proper name
>     for the strings that go there?

It is a description which is displayed as a heading above those
matches. _path_files will set a default heading which this one
overrides. The heading is only displayed if you have a format style
with the descriptions tag (see below).

> PS: I'm going to use this as the basis for a little article on writing
>     completion functions.  I still need to improve my understanding of
>     how this all works, though.  Zsh is so complicated...  My head
>     hurts from RTFM.

If the article is to be published on the web let me know and I'll add a
link from the zsh web pages. Have you read Peter's user guide in
addition to the manual? 

>     Many times, I've wished for a tool like perldoc.  It could be called
>     zdoc, and you'd be able to do things like:

Because zsh displays quite a lot of descriptions with completions, I
quite often press tab for just such information. Have you set up your
styles to display all the information. I use:
  zstyle ':completion:*' verbose yes
  zstyle ':completion:*:descriptions' format '%B%d%b'
  zstyle ':completion:*:messages' format '%d'
  zstyle ':completion:*:warnings' format 'No matches for: %d'
  zstyle ':completion:*' group-name ''

The zdoc you describe would probably need to be integrated with the
documentation so if we ever reorganise that (such as because of Yodl
now seemingly being unmaintained) it'll be worth considering.

> _figlet() {

You don't need to write the function bit with zsh's autoloaded functions.

>  fontdir=$(figlet -I2)

I suppose this should be
   fontdir=$(_call_program path figlet -I2 2>/dev/null)
which allows a style to override the command which is called and
doesn't print an error if figlet isn't installed.

>   local context state line

>   _arguments -C -s \

If you use -C, you should use curcontext="$curcontext" in the local
line. context is an array and it is used in cases such as where more
than one state can be entered, each with a different context. In
practise such situations are fairly rare.

For _figlet, once the states are removed the -C option won't be needed.

>     "-c[center justify]" \
>     "-k[use kerning]" \
>     "-l[left justify]" \

where you have options which are mutually exlusive, you can prevent the second
from being completed after the first.
e.g.
    "(-c -r)-l[left justify]" \
prevents the -r and -c options being completed once -l has already been
specified on the line.

>     "-C+[control file]:->change_controlfile" \

You're missing the description in the spec. I've fixed it in the
replacement above.

>     "-I+[info]:info:compadd 0 1 2 3 4" \

This can be:
  "-I+[info]:info:(0 1 2 3 4)" \
  
You can also give descriptions for each of the possible values so we
can even do:
  "-I+[display info]:info:((0\:version\ and\ copyright 1\:version\ \(integer\) 2\:default\ font\ directory 3\:font 4\:output\ width))" \

I hope that helps

Oliver
-- 

This e-mail and any attachment is for authorised use by the intended recipient(s) only.  It may contain proprietary material, confidential information and/or be subject to legal privilege.  It should not be copied, disclosed to, retained or used by, any other party.  If you are not an intended recipient then please promptly delete this e-mail and any attachment and all copies and inform the sender.  Thank you.