4.2 Parameter Definitions

Each command line parameter must be defined in the form

short_names[*|!] [/ long_name[*|!][=opt_name]] type [ options ]

A short_name is a single letter (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. long options can be followed by a descriptive designation (See opt_name.).

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. Examples:

o* / oparam*	string		"Both short and long option have an optional"
				"argument"
p* / pparam	string		"Short option has an optional argument,"
				"long option requires an argument."
q / qparam*	string		"Short option reqires an argument,"
				"long option has an optional argument."
P* / Pparam!	string		"Short option has an optional argument,"
				"long option none."
Q!/ Qparam*	string		"Short option has no argument, long option has an"
				"optional argument."

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 (See 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 four 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 Genparse include file. Includes another Genparse (.gp) 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 (See 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 (See 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 getopt_long ()). This new field will get the same name as the result field it is related to but with an _li postfix.