genparse - command line parser generator

genparse [options] files...

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.

Genparse assumes that the GNU getopt_long(3) function is built into your C library. If not, we compile a modified version of the function into genparse.

genparse accepts these options:

-d

Turn on logging.

-c, --cppext extension

C++ file extension. (default = cc)

-o, --outfile name

Output file name. (default = parse_cl)

-f, --logfile name

Log file name. (default = genparse.log)

-l, --language lang

Output language. Only C and C++ are supported. Any of the following indicate C++: : "c++", "cpp", "cc", and "cxx". (default = c)

-o, --outfile filename

Root name of output file. The extension will be determined by the output language and possibly by other options. For example, when the output language is C, giving this option an argument of "file" will result in output file names of "file.h", "file.c" and "file_cb.c" for the header, parser, and callback files, respectively. Default value is "parse_cl".

-p, --parsefunc func

Name of parsing function / class. This option allows the user to specify the name of the function (for C) or class (for C++) that does the actual command line parsing. (default = "Cmdline")

-h, --help

Display help information.

-q, --quiet

Quiet mode - no on screen output.

-v, --version

Output version.

A genparse specification file (usually just called a 'genparse file') consists of a number of entries, one per command line parameter, of the form: short_name / long_name type [ options ] short_name is a single character giving the command line switch. long_name is a longer (more descriptive) option name. On the command line the short name will be preceeded by a single dash and the long version will be preceeded by two dashes. If a long parameter name is not necessary, you may specify only the short one (and the slash need not appear).

type 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 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, depending on the order of the parameters on the command line.

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

Here is a sample genparse file:

#include<sys/types.h>
#mandatory filename

/* comment */ my_callback()

i / iterations int 100 [10...1000] iter_callback() "Number of iterations to run for."

/* * Comment */

n / name string {"mike"} name_cb() "User's name" s / str string "test string" f flag "a stupid flag!"

For an example input file, see /usr/share/doc/genparse/examples/test.gp.

The full documentation for genparse is maintained as a Texinfo manual. If the info and genparse programs are properly installed at your site, the command info genparse should give you access to the complete manual.

This manual page was written by James R. Van Zandt <jrv@vanzandt.mv.com>, for the Debian GNU/Linux system (but may be used by others).