Next: Genparse File Grammar, Previous: Parameter Definitions, Up: Genparse File Syntax [Contents][Index]
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 is automatically executed when
This usage function 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
(See Global Definitions.). Deprecated: List mandatory
parameters here directly.
__GLOSSARY__: A description of all
command line options. This is the information given for the parameter
definitons (see See Parameter Definitions.) 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. Example:
[ -h ] [ --help ] (type=FLAG)
Display help information.
__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.
Example:
-h, --help Display help information.
__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
(See Include files.). 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
(See Include files.). Ignored when generating Java output.
__CODE__(statements): See __CODE__.
__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 in the genparse file
(See Parameter Definitions.) which can be referred to in the following
description (See parameter-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 (See __GLOSSARY__.) or
-s, --block-size=SIZE use SIZE-byte blocks
in GNU style (See __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 (See optional_arguments.).
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.
For an example of the generated default usage () function in C See Parser Files.
Next: Genparse File Grammar, Previous: Parameter Definitions, Up: Genparse File Syntax [Contents][Index]