--- name: "genparse" section: "1" platform: "linux" package: "genparse" version: "0.9.3-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/genparse" --- # genparse(1) 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)](/getopt_long/3.md) 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 /* 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.