genparse

Langue: en

Version: 2000-10-09 (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

NAME

genparse - command line parser generator

SYNOPSIS

genparse [options] files...

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.

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.

OPTIONS

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.

INPUT FILE

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.

EXAMPLE

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!"
 

SEE ALSO

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.

AUTHOR

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