CGenGetopt

Gengetopt file generation

A program interface XML definition file can be converted to a configuration file for the GNU Gengetopt tool using a XSLT stylesheet. This feature should not be used unless you are really familiar with Gengetopt and if the program options are relatively simple. In such situation, the advantage of using an XML description file rather than writing the (far less verbose) Gengetopt file is that you can build the HTML documentation, bash completion etc. with this single XML file.

• [Gengetopt file generation](#Gengetopt file generation)
  • Usage
  • Limitations
  • [Translation details](#Translation details)
    • Switches
  • Arguments
  • [Multi Arguments](#Multi Arguments)
  • Groups
  • Subcommands

Usage

Using xsltproc

#!bash
xsltproc -o output.ggo ${NSXML_PATH}/ns/xsl/program/${SCHEMA_VERSION}/c-Gengetopt.xsl program.xml 

Where program.xml is the program interface XML definition file to convert

Limitations

The following features of the program interface definition framework are not supported

• Sub command definitions
• Argument values checks (existing file, etc.)
• Nested groups
• Non-exclusive groups
• Multiple long and short option names (only one of each)
• Variable binding (the option long name is used)

The following features of Gengetopt are not supported

• Modes
• Option dependencies

Thus, the following limitations and/or changes will occur

• An exclusive group cannot contains nested groups
• The parser will not accept multiple values given to a multiargument. The option name have to be repeated before each value
• The special end-of-arguments marker '-' will not be handled

Translation details

Switches

Gengetopt has a specific keyword flag to handle option without arguments. However flag-type options cannot appear in a Gengetopt group. For this reason the default behavior of the XSLT stylesheet is to translate all switches into enum

option "switch" b "A switch"
 int argoptional values="no","yes" enum default="yes"

Which means that the option will be considered as a single argument option with only two possible values (yes == 1 and no == 0) and if the argument is not provided, the value will be yes (1) Note that a naughty user may type

program --switch=no

So, the correct C code to check if the switch was set is:

#!c++
if (args_info.switch_given && (args_info.switch_arg == 1))
{
	// switch set
} 

The prg.c.ggo.allSwitchesAsEnum parameter of the c-Gengetopt.xsl XSLT stylesheet can be set to 'no' to force switches to be translated to flags when possible. This allow a simpler test for switches

#!c++
if (args_info.switch_flag)
{
	// switch set
}

but it introduces two differents syntaxes for the same kind of option.

Arguments

Single argument options are transalted without any major issue. In most case, the argument value is declared as a string except if the <prg:number /> node is set within the <prg:type/> node. In such situation, the argument type will be

• int if no @decimal attribute is specified
• float if the @decimal attribute is specified and greater than 0.

If a <select/> node is present with the attribute @restrict, the list of accepted values will be added to the Gengetopt definition. Other types, like <prg:path/>, will only change the hint string while displaying the program help.

#!bash
	--a-file-arg=path: Some file

Multi Arguments

Multiple argument options are translated like single argument options except that the multiple attribute is added to the definition. However, getopt will not allow multiple argument at the same time

#!bash
program --multi valueA valueB

The option name have to be repeated for each value

#!bash
program --multi valueA --multi valueB

Groups

There is two major limitations on groups in the Gengetopt syntax.

• Options in a group are always mutually exclusive.
• A group cannot contains a sub group.

If a <prg:group/> is not in such case (the @type attibute is 'exclusive' and the <prg:group/> contains only one ore more <prg:switch/>, <prg:argument/> or <prg:multiargument/>), then it is translated into a Gengetopt group and all its sub options will be defined as groupoptions. In other case, the group will appear as a section in the program help string. The Non-exclusive group case is not very important since such group will never change the parser behavior. But the way nested groups in exclusive group are translated is a real problem. Such construction should be avoided if Gengetopt is the chosen parsing solution.

Subcommands

Subcommands are totally ignored and will not appear in the generated Gengetopt file.

The program interface definition framework