A Completion Function for FIGlet

[John Beppu <beppu@xxxxxxx>]

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.
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.


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.

  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?


[1] a program for rendering text using ascii art fonts
    http://ianchai.50megs.com/figlet.html


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.

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

    Reading about modifiers
        zdoc -m :q
        zdoc -m :r

    Reading about flags
        zdoc -F @
        zdoc -F U

    Reading about options
        zdoc -o promptsubst

    Reading about functions that come w/ the distribution
        zdoc -f _arguments
        zdoc -f _tags

    etc. 

    just another perl hacker (spoiled by perldoc)

#compdef figlet

_figlet() {
  local context state line
  local fontdir
  typeset -A opt_args

  fontdir=$(figlet -I2)

  _arguments -C -s \
    "-c[center justify]" \
    "-k[use kerning]" \
    "-l[left justify]" \
    "-n[normal mode]" \
    "-o[let letters overlap]" \
    "-p[paragraph mode]" \
    "-r[right justify]" \
    "-s[smushed spacing]" \
    "-t[use terminal width]" \
    "-v[version]" \
    "-x[use default justification of font]" \
    "-D[use Deutsch character set]" \
    "-E[use English character set]" \
    "-L[left-to-right]" \
    "-N[clear controlfile list]" \
    "-R[right-to-left]" \
    "-S[smush letters together or else!]" \
    "-W[wide spacing]" \
    "-X[use default writing direction of font]" \
    "-w+[output width]" \
    "-d+[directory]:directory:_path_files -/" \
    "-f+[font]:font:->change_font" \
    "-C+[control file]:->change_controlfile" \
    "-I+[info]:info:compadd 0 1 2 3 4" \
    && return 0


  (( $+opt_args[-d] )) && fontdir=$opt_args[-d]

  case $state in
  (change_font)
    _files -W $fontdir -g '*flf*' && return 0
    ;;
  (change_controlfile)
    _files -W $fontdir -g '*flc*' && return 0
    ;;
  esac

  return 1
}

# this is going to be what I use as the basis for my article.
# vim:sw=2 sts=2