ITP: genparse, another command line parser generator
I intend to package the following command line parser generator by
Mike Borella <mike@borella.net>.
There is no license in the sources. I am contacting the author, in
hopes he is willing to use the GNU GPL. Actually, I think he has to,
since the FSF getopt sources are included.
- Jim Van Zandt
------------------------------------------------------------------------------
DESCRIPTION
Genparse is a generic command line parser generator. From simple and
concise specification file, you can define the command line parameters
and switches that you would like to be able to pass to your program.
Genparse creates the C code of the parser for you, which you can then
compile as a separate file and link with your program.
A genparse specification file (usually just called a 'genparse file')
consists of a number of entries, one per command line parameter, of
the form:
parameter_names type [options]
The parameter_names and type fields must be present. The
parameter_names field specifies both short and long versions of a
command line switch. The short version is a single character and the
long version is a (more descriptive) string. On the command line the
short version will be preceeded by a line dash and the long version
will be preceeded by two dashes. These two versions must appear as
'short / long'. For example:
i / iterations
specifies that the short parameter name is 'i' and the long parameter
name is 'iterations'. If a long parameter name is not necessary, you
may specify only the short one (and the slash need not appear).
The type field must be one of the following: int float char string flag.
The first four should be self-explanatory. The last is a "switch"
option that takes no arguments.
There are four options currently supported:
- A default value for the parameter. For everything but a string this
is just the plain default value, whatever it is. For strings, a
default must be specified within braces and quotes, and may include
whitespace. E.g., {"my default value"}
- A range of values within brackets. The low and high values are specified
between a range specifier (currently either '...' or '..'). Either the
high or the low value may be omitted for a range bounded on one side
only. The parameter will be checked to make sure that it lies within
this range.
- A callback function. This function is called after any range checking
is performed. The purpose of the callback to do validity checking
that is more complicated than can be specified in the genparse file.
For example, you might write a program that requires input to be
prime numbers, strings of a certain length, etc.
- A description in quotes. This is a displayed to the user when they
enter an invalid parameter value. Ideally it is a short string that
describes the purpose of the parameter.
A global callback function can also be specified at the beginning of the
genparse file. This function is useful for checking interdependencies
between parameters. Interdependencies cannot be checked within each
individual callback function because the order in which these functions
will be called varies based on the order of the parameters on the command
line.
A #include directive will instruct genparse to copy the said include
statement into the C code generated by genparse, but not any header files
or callback files.
A #mandatory directive can be used it make usage() function calls nicer.
It allows you to specify mandatory command line parameters that might
follow switches.
If all this makes no sense, look at the genparse.gp file in the main
directory or the test/test.gp file for working examples. Feel free to
play with the example in the test directory.
Notes:
- Currently genparse will handle up to 256 command line parameters. This
should be more than enough to keep everyone happy.
- Genparse assumes that the GNU getopt_long() function is built into your
C library. If not, we compile a modified version of the function into
genparse.
- If your system does not have getopt() at all, you MUST copy our files
getopt.h, getopt.c and getopt_long.c into the appropriate directory in
your development environment. This goes for our test program as well.
- If you want to free the memory allocated by the parsing function, call
free_args(), passing your argument structure.
-------------------------------------------------------------------------------
TO DO
- Add command line options for specifying the names of the command line
parsing routine and the name of the global argument variable.
- Optional max string length after strings?
- Make help switches optional
- Clean up code and make it more modular, dammit
- Allow for a list of acceptable values as well as a range.
- I'd really like to add a tcl/tk front end GUI for easy generation of
genparse files. It won't necessarily be that useful for most developers,
but it will give me an excuse to play with tk...
-------------------------------------------------------------------------------
OPERATION
genparse [-ho] [--help] [--output output_file] genparsefile
-h | --help
Display help file.
-o | --output
Name of the output file and parsing function. Default is
parse_cl.c and parse_cl(), respectively.
-------------------------------------------------------------------------------
COMMENTS
I wrote genparse because I got tired of writing a new command line
parser for every little utility I made. Most of these parsers are
very similar, so it seemed as if a great deal of the functionality
required by most programs could be automatically generated. So far,
genparse has saved me a lot of time. In fact, I used genparse to
create the command-line parser for itself! However, I imagine that it
may not be powerful enough for large applications with complex sets of
parameters.
I'll maintain and upgrade genparse in my spare time. Drop me a line
if you would like to see any new features included. If you have any
questions about genparse files, look through the examples in the
genparse distribution itself: genparse.gp and test.gp. I have not
rigorously tested all of genparse's functionality yet, so bug
reporting is encouraged.
Genparse is not the only command line parser generator available.
Several others are:
gengetopt by Harmut Holzgraefe <URL?>
opt by James Theiler <http://nis-www.lanl.gov/~jt/Software/>
mkcmd by Kevin Braunsdorf <URL?>
Thanks to these folks for valuable feedback and suggestions:
- Harmut Holzgraefe for sharing ideas and his gengetopt program.
- Peter Teuben
- James Theiler
- Matthew Rice
...and the several others whom I've probably left out.
Reply to: