| GENPARSE(1) | Programmer's Manual | GENPARSE(1) |
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, C++ or Java code of the parser for you.
Genparse assumes that the GNU getopt_long(3) function is built into your C library. For Java you may have to specify an appropriate jar file to your Java compiler.
genparse accepts these options:
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_names[*|!] [/ long_name[*|!][=opt_name]] type [ options ]
A short_name is a single character (small or capital) or a single digit. long_name is a longer (more descriptive) option name. On the command line a short name will be preceded by a single dash (e.g. '-a') and a long version will be preceded by two dashes (e.g. '--all'). If a long parameter name is not necessary, you may specify only the short one (and the slash need not appear). In order to specify a parameter that only has a long name set short_names to NONE. It is possible to have multiple short options, so for example setting short_name to 'aA' and long_name to 'all' would allow one to specify the command line switch as '-a' or '-A' or '--all', all of them doing the same thing.
A * after short_name or long_name makes the argument optional. This can be specified for short and long options separately.
A ! after short_name or long_name makes the option boolean. This allows one to combine a boolean short option with a long option with an optional or mandatory argument or to combine a boolean long option with a short option with an optional or mandatory argument. A ! doesn't make sense if the option's type is flag.
type must be one of int float char string or flag. The first four should be self-explanatory. The last is a "switch" option that takes no arguments. For C output and if --gnulib is set on the command line additionally the following types are allowed: long (for long int), ulong (for unsigned long int), intmax (for intmax_t, defined in Gnulib), uintmax (for uintmax_t), double.
The following options are supported. They may appear in any order and except for descriptions only one of each field may be defined per option.
A range of values within brackets. The low and high values are specified between a range specifier (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 double quotes. It is printed by the usage() function. If one line is not enough then specify multiple descriptions, one per line and each of them in double quotes. If the description starts in the 1st column in the Genparse file then it will also be printed in the 1st column in the usage() function.
A #gp_include directive will instruct genparse to include another genparse file, e.g #gp_include another.gp. Only parameter definitions are allowed in the included file, no global directives.
An __ERR_MSG__(err_txt) directive. Specifies the error message which is printed when the argument could not be converted. Example: __ERR_MSG__("%s: invalid argument"). This message will be printed when either the conversion function failed or when the argument was out of range. Assumes to contain one %s which will be replaced with the argument which could not be converted. Only available when Genparse is invoked with --gnulib, ignored otherwise.
Optionally a conversion function can be added as a second argument, e. g. __ERR_MSG__("%s: invalid argument", quotearg). This would lead to an error message like error (EXIT_FAILURE, 0, "%s: invalid argument", quotearg (optind)).
An __ADD_FLAG__ directive. Makes sense only if the command line parameter is not already a flag, in this case an additional flag parameter is added which will be set if the command line parameter was specified on the command line. This option is automatically set if a parameter has an optional argument.
A __CODE__(statements) directive. The specified code statements are copied literally. Example: __CODE__(printf ("Parameter x was set");). The specified code can extend over more than one line. In order to give Genparse the chance to indent the code properly, do not mix space and tab indentations in one __CODE__ statement.
A __STORE_LONGINDEX__ directive. Instructs Genparse to add an interer type field to the result class which will be set to the longindex variable (last argument in the call to @code{getopt_long()}). This new field will get the same name as the result field it is related to but with an _li postfix.
The following global directives are supported. They may appear in any order.
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. Note that Genparse does not check for mandatory parameters, they are only printed in the usage () function with the __MANDATORIES__ directive. Deprecated: add mandatory parameters in the #usage section instead.
An #exit_value directive which specifies the exit value in case of an error. Default is EXIT_FAILURE.
A #break_lines directive which specifies the width to which lines shall be broken on the help screen. If no #break_lines directive is specified then lines will be printed exactly as given in the genparse file.
If #no_struct is specified then no struct will be defined which will be filled with the command line parameters in the generated parser. This may be useful if you want to add your own code with __CODE__ statements instead. Only supported for C output.
A #export_long_options directive. If #export_long_options is defined then a function #get_long_options() is added which exports the longoptions array used by #getopt_long(). This directive is only available for C output, for other languages it is ignored.
A global callback function. 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.
Genparse also generates a usage() function which prints a help text to stdout about the usage of the program for which Genparse is generating the parser. It can be customized by specifying a usage section at the bottom of the Genparse file. If no such section is specified it defaults to
#usage_begin usage: __PROGRAM_NAME__ __OPTIONS_SHORT__ __MANDATORIES__ __GLOSSARY__ #usage_end
The usage section starts with #usage_begin and ends with #usage_end. Any text between is printed verbatim except for the following keywords, which will be replaced as listed below:
__OPTIONS_SHORT__: A list of available short form options, e.g. [ -abc ].
__MANDATORIES__: A list of all mandatory parameters as defined with #mandatory commands. Deprecated: List mandatory parameters here directly.
__GLOSSARY__: A description of all command line options. This is the information given for the parameter definitons in human readable form. It includes the parameter type, default, range and any comments. A line which contains __GLOSSARY__ is replaced by the glossary of the parameters, any other text in the same line is ignored.
__GLOSSARY_GNU__: Same as __GLOSSARY__ but in GNU style. Optionally followed by an integer in brackets which specifies the indentation of the descriptive text (e.g. __GLOSSARY__(30)). Default indentation is 24.
__STRING__(s): A string constant, in C probably a string macro defined with the #define preprocessor command. This macro can be imported from another file using the include directive in the genparse file. Ignored when generating Java output.
__INT__(x): An integer constant, in C probably an integer macro defined with the #define preprocessor command. This macro can be imported from another file using the include directive in the genparse file. Ignored when generating Java output.
__CODE__(statements): Same as for the parameter options, see above.
__DO_NOT_DOCUMENT__: Any line which contains this macro will not be printed in the usage() function. Can be used for implementing command line parameters without listing them on the help screen.
__NL__: New line. Useful for breaking lines manually while automatic line breaking is on (see #break_lines). Ignored when generating Java output.
__NEW_PRINT__: Close the active print command and start a new one.
__COMMENT__(text): Comment in the code for printing the usage text.
long options can be followed by an = sign and an optional designation opt_name which can be referred to in the following description. It will be used in the usage() function only. For example the following genparse line
s / block-size=SIZE int "use SIZE-byte blocks"
will lead to the following line in the help screen
[ -s ] [ --block-size=SIZE ] (type=INTEGER)
use SIZE-byte blocks
in genparse style (__GLOSSARY__) or
-s, --block-size=SIZE use SIZE-byte blocks
in GNU style (__GLOSSARY_GNU__).
It is also possible to put square braces around the optional name in order to indicate that the argument is optional. This has no meaning for the generated parser however. Use * postfixes in order to make an argument optional.
s* / block*[=SIZE] int "use blocks."
"If SIZE is not given then they will get a size of 1kB."
will lead to the following line in the help screen
-s, --block[=SIZE] use blocks.
If SIZE is not given then they will get a size of 1kB.
Here is a sample genparse file:
#include<sys/types.h> /* 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!" #usage_begin usage: __PROGRAM_NAME__ __OPTIONS_SHORT__ filename This is only a stupid test program. __GLOSSARY__ #usage_end
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.
The latest version of genparse can always be found at http://genparse.sourceforge.net.
This manual page was written by James R. Van Zandt and Michael Geng.
| 2008-01-19 |