Ubuntu Manpage: genparse - command line parser generator

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

OPTIONS

       genparse accepts these options:

       -c, --cppext extension
              C++ file extension. (default = cc)

       -d     Turn on logging.

       -f, --logfile name
              Log file name. (default = genparse.log)

       -h, --help
              Display help information.

       -g, --gnulib
              Use  GNU  Compatibility Library (Gnulib, see http://www.gnu.org/software/gnulib/).  Only available
              for C output.  Allows some more types (unsigned long, intmax_t etc.)  for  which  Gnulib  provides
              conversion functions.

       -i, --internationalize
              Put  internationalization  macro  _()  around  text  output  so  that the generated program can be
              internationalized using the GNU gettext command.  Presently only implemented for C output.

       -l, --language lang
              Output language.  Only C, C++ and Java are supported.  Any of the following indicate  C++:  "c++",
              "cpp", "cc", and "cxx".  For Java use: "java" or "Java".  (default = c)

       -o, --outfile name
              Output file name. (default = parse_cl)

       -m, --longmembers
              Use  long  options  for the members of the parser class (struct).  The default is to use the short
              representation except if there is only a long representation defined in  the  genparse  file.   If
              this  option is set then the behavior is reverted.  The long representation is used then except if
              there is only a short representation defined.

       -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++ and  Java)  that  does  the  actual  command  line  parsing  (default  =
              "Cmdline").

       -P, --manyprints
              Output help text for every command line parameter in a separate print command.

       -q, --quiet
              Quiet mode - no on screen output.

       -s, --static-headers
              Keep  the  descriptive  header on top of the generated files static.  Without this option genparse
              prints creation date and time, Linux kernel version,  kernel  build  time,  computer  architecture
              name, host name and user name.

       -v, --version
              Output version.

       -D, --directory
              Directory for storing results.

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_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 specifying 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 default value for the parameter. For 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"}. For a char parameter it must be enclosed in single quotes,
e.g. 'a' or '\n'.

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.

An #include directive will instruct genparse to copy the said include statement into the C or 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. 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:

__PROGRAM_NAME__: The program name. In C and C++ the program name is given in argv[0].

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

EXAMPLE

       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

AUTHOR

       This manual page was written by James R. Van Zandt and Michael Geng.

                                                   2008-01-19                                        GENPARSE(1)