A Completion Function for FIGlet

A Completion Function for FIGlet

[John Beppu]

[-- Attachment #1: Type: text/plain, Size: 1680 bytes --]

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)


[-- Attachment #2: _figlet --]
[-- Type: text/plain, Size: 1262 bytes --]

#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

Re: A Completion Function for FIGlet

[Oliver Kiddle]

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.

zdoc (Re: A Completion Function for FIGlet)

[Bart Schaefer]

On Mar 20,  1:19am, John Beppu wrote:
}
}     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. 

Try the commands

	info zsh expansion history modifiers
	info zsh expansion parameter
	info zsh options description
	info zsh "completion functions"

(Assuming you've installed the zsh info files, that is.  And you do need
the quotes on the last one.  Run `info standalone invoking' to find out
what is going on there.)

Also have a look at Util/helpfiles, which chops the zsh manual up into bits
and stuffs them in a directory where they can be accessed with the run-help
function (`autoload run-help'); then try using M-h in the middle of a zsh
command line.  [Util/helpfiles could stand to be updated, it doesn't know
about the completion functions and user contributions sections, among other
things.]

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

Zsh: http://www.zsh.org | PHPerl Project: http://phperl.sourceforge.net   

Re: A Completion Function for FIGlet

[John Beppu]

[  date  ] 2002/03/20 | Wednesday | 12:13 PM
[ author ] Oliver Kiddle <okiddle@yahoo.co.uk> 

> If the article is to be published on the web let me know and I'll add a
> link from the zsh web pages. 

Linux Magazine doesn't put their content on-line until a $few months
after an issue hits the shelves.  I'll get a URL for you when it
becomes available.


> Have you read Peter's user guide in
> addition to the manual? 

Yes, I've read huge chunks of the Zsh User Guide.
[[ Thanks, Peter, for writing it. ]]  
However, I have to admit that it's hard to follow at times, but with a
subject like Zsh, that might be inevitable.  I am still shocked a shell
could be so complex.
 

> I hope that helps

That helped so much.  Thank you.


-- 
package wuv'apqvjgt;($_=join('',(*PgtnHcemgt))) # print map "beppu\@$_\n", qw(
=~ s/([HaP])(?!e)/ \U>$1/g;s/^.|:| (?=A)|>//g;y # cpan.org  lbox.org  binq.org
/c-z/a-u/;print"J$_\n";#$^%$^X@.^ <!-- japh --> # oss.lineo.com codepoet.org);

Re: zdoc (Re: A Completion Function for FIGlet)

[John Beppu]

[  date  ] 2002/03/20 | Wednesday | 05:01 PM
[ author ] Bart Schaefer <schaefer@brasslantern.com> 

> Try the commands
> 
> 	info zsh expansion history modifiers
> 	info zsh expansion parameter
> 	info zsh options description
> 	info zsh "completion functions"

nice.  (i never could get the hang of info's key bindings, though.)
 
> Also have a look at Util/helpfiles, which chops the zsh manual up into bits
> and stuffs them in a directory where they can be accessed with the run-help
> function (`autoload run-help'); then try using M-h in the middle of a zsh
> command line.  [Util/helpfiles could stand to be updated, it doesn't know
> about the completion functions and user contributions sections, among other
> things.]

I have not tried this, yet, but this sounds really intereseting.

Re: A Completion Function for FIGlet

[Felix Rosencrantz]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=us-ascii, Size: 4088 bytes --]

Just a shameless plug for my xml to completion tools....
The figlet command doesn't have usage information in a format that is
usable by my tool.   There is simple usage information and there is a man
page.  Though if you created a GNU style usage/help screen like so (this
is based on the previously posted completion function and the man page).

    -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 Width     output width (in columns)
    -d dir       Font Directory 
    -f change_font   Font 
    -C change_controlfile   Control file
    -I -1       Normal operation (default)
    -I -v       Version, copyright and usage information
    -I 0        Version, copyright and usage information
    -I 1        Version in integer format
    -I 2        Default font directory.
    -I 3        Name of font figlet would use
    -I 4        Output width in number columns.

And then giving a help2simple.pl command like so:
  help2simple.pl -c figlet -S -a message  \
    -x -c,-l,-r,-x \
    -x -t,-w -x -n,-p \
    -x -D,-E -x -N,-C \
    -x -S,-s,-k,-W,-o \
    -x -L,-R,-X \
    -x -v,-I < Figlet.help >! figlet_simple.xml

The -S says that all single dash flags are single letters.  The -x flag
says that the following comma separated list of flags are mutually exclusive.
The -a says that the first argument is a message.

The processing figlet_simple.xml with the XSLT script simple2long.xsl, and
then  arg.xsl you get a version of _figlet that looks like the following.
It still needs work, but it gets you part of the way and does some of
the book keeping for exclusion lists, backslashes on the help for the
constants for the -I flag.  And building a case statements for the "$state".
And it works as is, no problems with syntax errors.

-FR.

#compdef figlet 
#Generated by
#   simple2long.xsl
#   args.xsl
#   For details see:
#       http://www.geocities.com/f_rosencrantz/xml_completion.htm

 local context state line
           typeset -A opt_args
	_arguments  \
		"(-r -l -x)-c[center justify]" \
		"(-S -s -o -W)-k[use kerning]" \
		"(-r -c -x)-l[left justify]" \
		"(-p)-n[normal mode]" \
		"(-k -S -s -W)-o[let letters overlap]" \
		"(-n)-p[paragraph mode]" \
		"(-c -l -x)-r[right justify]" \
		"(-k -S -o -W)-s[smushed spacing]" \
		"(-w)-t[use terminal width]" \
		"(-I)-v[version]" \
		"(-r -c -l)-x[use default justification of font]" \
		"(-E)-D[use Deutsch character set]" \
		"(-D)-E[use English character set]" \
		"(-X -R)-L[left-to-right]" \
		"(-C)-N[clear controlfile list]" \
		"(-L -X)-R[right-to-left]" \
		"(-k -s -o -W)-S[smush letters together or else!]" \
		"(-k -S -s -o)-W[wide spacing]" \
		"(-L -R)-X[use default writing direction of font]" \
		"(-t)-w:output width (in columns):->Width" \
		"-d:Font Directory:->dir" \
		"-f:Font:->change_font" \
		"(-N)-C:Control file:->change_controlfile" \
		"(-v)-I: :((-1\:Normal\ operation\ \(default\)\  -v\:Version,\ copyright\
and\ usage\ information\  0\:Version,\ copyright\ and\ usage\ information\ 
1\:Version\ in\ integer\ format\  2\:Default\ font\ directory.\  3\:Name\ of\
font\ figlet\ would\ use\  4\:Output\ width\ in\ number\ columns.\ ))" \
		"*:Handling Tag message:->message" \
           && return 0
            
case $state in
  "change_controlfile");;
  "change_font");;
  "dir");;
  "message");;
  "Width");;
esac



__________________________________________________
Do You Yahoo!?
Yahoo! Movies - coverage of the 74th Academy Awards®
http://movies.yahoo.com/