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)