Provided by: genparse_0.8.7-4_amd64 bug

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  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  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 agrument 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

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.

       The latest version of genparse can always be found at http://genparse.sourceforge.net.

AUTHOR

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

                                            2008-01-19                                GENPARSE(1)