Zsh Completion function generation via XML

Zsh Completion function generation via XML

[Felix Rosencrantz]

I've progressed a little with the XML to completion function generation.
I've written a perl script that parses command help output, and converts
that to a simple XML format.  (At least simpler than I described
before.)  This simple format can then be converted to the longer XML format.
I've already posted XSLT code to convert that longer format to a completion
function.

For example, here is a reduced version of help output for GNU troff
clone, groff.

usage: groff [-abeghilpstvzCENRSUVXZ] [-Fdir] [-mname] [-Tdev] [-ffam]
       [-wname] [-Wname] [-Mdir] [-dcs] [-rcn] [-nnum] [-olist] [-Parg]
       [-Larg] [-Idir] [files...]

-h	print this message
-t	preprocess with tbl
-p	preprocess with pic
-s	preprocess with soelim
-Tdev	use device dev
-mname	read macros tmac.name
-dcs	define a string c as s
-rcn	define a number register c as n
-nnum	number first page n
-olist	output only pages in list
-ffam	use fam as the default font family
-Fdir	search dir for device directories
-Mdir	search dir for macro files
-v	print version number
-z	suppress formatted output
-Z	don't postprocess
-a	produce ASCII description of output
-wname	enable warning name
-Wname	inhibit warning name
-E	inhibit all errors
-V	print commands on stdout instead of running them
-Parg	pass arg to the postprocessor
-Larg	pass arg to the spooler
-U	enable unsafe mode
-Idir	search dir for soelim.  Implies -s


Using help2simple.pl, you get this simple XML version.  The actual command
line is part of the output, at the end.


<command command="groff">
<flag name="-h" flaghelp="print this message"/>
<flag name="-t" flaghelp="preprocess with tbl"/>
<flag name="-p" flaghelp="preprocess with pic"/>
<flag name="-s" flaghelp="preprocess with soelim"/>
<flag name="-T" argtag="dev-T" same_word="true" taghelp="use device dev"/>
<flag name="-m" argtag="name-m" same_word="true" taghelp="read macros
tmac.name"/>
<flag name="-d" argtag="cs-d" same_word="true" taghelp="define a string c as
s"/>
<flag name="-r" argtag="cn-r" same_word="true" taghelp="define a number
register c as n"/>
<flag name="-n" argtag="num-n" same_word="true" taghelp="number first page n"/>
<flag name="-o" argtag="list-o" same_word="true" taghelp="output only pages in
list"/>
<flag name="-f" argtag="fam-f" same_word="true" taghelp="use fam as the default
font family"/>
<flag name="-F" argtag="dir-F" same_word="true" taghelp="search dir for device
directories"/>
<flag name="-M" argtag="dir-M" same_word="true" taghelp="search dir for macro
files"/>
<flag name="-v" flaghelp="print version number"/>
<flag name="-z" flaghelp="suppress formatted output"/>
<flag name="-Z" flaghelp="don't postprocess"/>
<flag name="-a" flaghelp="produce ASCII description of output"/>
<flag name="-w" argtag="name-w" same_word="true" taghelp="enable warning
name"/>
<flag name="-W" argtag="name-W" same_word="true" taghelp="inhibit warning
name"/>
<flag name="-E" flaghelp="inhibit all errors"/>
<flag name="-V" flaghelp="print commands on stdout instead of running them"/>
<flag name="-P" argtag="arg-P" same_word="true" taghelp="pass arg to the
postprocessor"/>
<flag name="-L" argtag="arg-L" same_word="true" taghelp="pass arg to the
spooler"/>
<flag name="-U" flaghelp="enable unsafe mode"/>
<flag name="-I" argtag="dir-I" multiple="true" same_word="true" taghelp="search
dir for soelim.  Implies -s"/>
<arg position="any" argtag="_files"/>
<generation command="help2simple.pl -c groff -S -n -M -I -a _files"/>
</command>

(The arguments supplied to help2simple.pl
-S    -- All single dash flags are single letter flags.
-n    -- Add flag name to arg, to make argnames unique.
-M    -- Flags are allowed multiple times on the command line. (comma list)
-a    -- Says what the normal arguments are.
)


And here is the function that was generated.  There is definitely
a problem with automatic generation of actions, this will require
improvement.  Currently the way these scripts work is that the flag
args are converted into tags that are found in the groff_defines.xml
file, which has to be hand-edited.  Also, the regular arguments are not
handled well.  (I didn't add the files arguments.)

#compdef groff 
#Generated by
#   help2simple.pl -c groff -S -n -M -I -a _files
#   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  \
		'-h[print this message]' \
		'-t[preprocess with tbl]' \
		'-p[preprocess with pic]' \
		'-s[preprocess with soelim]' \
		'-T-:use device dev:->dev-T' \
		'-m-:read macros tmac.name:->name-m' \
		'-d-:define a string c as s:->cs-d' \
		'-r-:define a number register c as n:->cn-r' \
		'-n-:number first page n:->num-n' \
		'-o-:output only pages in list:->list-o' \
		'-f-:use fam as the default font family:->fam-f' \
		'-F-:search dir for device directories:->dir-F' \
		'-M-:search dir for macro files:->dir-M' \
		'-v[print version number]' \
		'-z[suppress formatted output]' \
		"-Z[don't postprocess]" \
		'-a[produce ASCII description of output]' \
		'-w-:enable warning name:->name-w' \
		'-W-:inhibit warning name:->name-W' \
		'-E[inhibit all errors]' \
		'-V[print commands on stdout instead of running them]' \
		'-P-:pass arg to the postprocessor:->arg-P' \
		'-L-:pass arg to the spooler:->arg-L' \
		'-U[enable unsafe mode]' \
		'*-I-:search dir for soelim. Implies -s:->dir-I' \
		'*:Handling Tag _files:->_files'
case $state in
  "_files");;
  "arg-L");;
  "arg-P");;
  "cn-r");;
  "cs-d");;
  "dev-T");;
  "dir-F");;
  "dir-I");;
  "dir-M");;
  "fam-f");;
  "list-o");;
  "name-m");;
  "name-w");;
  "name-W");;
  "num-n");;
esac
    
I talk about the steps used to create a function on the web page.
    http://www.geocities.com/f_rosencrantz/help2simple.htm
and more general stuff
     http://www.geocities.com/f_rosencrantz/xml_completion.htm

-FR.


__________________________________________________
Do You Yahoo!?
Send your FREE holiday greetings online!
http://greetings.yahoo.com

Re: Zsh Completion function generation via XML

[Sven Wischnowsky]

Felix Rosencrantz wrote:

> ... [XML stuff]

That looks friendlier than before.  Only two remarks:

> 	_arguments  \
>               ...
> 		'*:Handling Tag _files:->_files'

There should at least be a `&& return 0' after the last spec.

But, and that's the second remark, I strongly suggest that you don't
use states for every action, or states at all.  They actually are the
worst case for _arguments, because it has to give up control. It's
also the most complicated and probably far from bug-free. Ahem.

Maybe use small sub-functions if you can't be bothered to find out if
the action can be put into the specs themselves.


Bye
  Sven

-- 
Sven Wischnowsky                           wischnow@berkom.de

Re: Zsh Completion function generation via XML

[Felix Rosencrantz]

Sven Wischnowsky wrote:
>Felix Rosencrantz wrote:
>
>> ... [XML stuff]
>
>That looks friendlier than before.  Only two remarks:
>
>>       _arguments  \
>>               ...
>>               '*:Handling Tag _files:->_files'
>
>There should at least be a `&& return 0' after the last spec.
Thanks.  I'll add that in.

>But, and that's the second remark, I strongly suggest that you don't
>use states for every action, or states at all.  They actually are the
>worst case for _arguments, because it has to give up control. It's
>also the most complicated and probably far from bug-free. Ahem.
>
>Maybe use small sub-functions if you can't be bothered to find out if
>the action can be put into the specs themselves.

Actually that something that can be configured in arg.xsl.  The arg.xsl
stylesheet has a parameter, the way you can hand an argument to an XSLT
script.  This the comment, I default to "state":  ActionTagGeneration
says how to generate an action where only an action tag is available.
Current values are:

<!--
    state     The action tag is used as a state name. (default)
    handler   The action tag is used as the argument to a function call of the
               function named '{$FunctionPrefix}_handle'
    default   Use the default action template.
    error     Fail if an action tag that is not defined is used.
    
-->
<xsl:param name="ActionTagGeneration" select="'state'"/>


When I was doing the clearcase completion, I was using something closer
to 'handler', which would generate calls to clearcase_* functions.  The
problem with that is the user had to write/stub those functions, or
there would be a lot of errors.  (Though I guess my script could stub
them....)

I guess what I'm hoping, is that I give help2simple.pl some heuristics
for picking appropriate type functions (i.e. functions under the
Completion/*/Type) for arguments.  The heuristics would be common
sense things, like if the argument name is pid, then guess _pids, or
the argument name ends in "dir" use "_files -/". So there will be less
states.  In addition to heuristics, allow the user to specify the mapping
of argtag names to functions.  (Of course, there needs to be a completion
function for help2simple.pl... :) )

-FR


__________________________________________________
Do You Yahoo!?
Send FREE video emails in Yahoo! Mail!
http://promo.yahoo.com/videomail/

Zsh Completion function generation via XML

[Felix Rosencrantz]

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

Forgot to attach the perl script. -FR

__________________________________________________
Do You Yahoo!?
Send your FREE holiday greetings online!
http://greetings.yahoo.com

[-- Attachment #2: help2simple.pl --]
[-- Type: application/x-perl, Size: 14508 bytes --]