Comfortable Command Line Parsing

Collaboration diagram for Comfortable Command Line Parsing:

Typedefs
typedef void(*	parse_cmd_fn_t) (int)
	Function type for PARSE_CMD_FN.
typedef void(*	parse_cmd_fn_arg_t) (int, const char *, int)
	Function type for PARSE_CMD_FN_ARG.

Enumerations
enum	parse_cmd_type
	Types for parsing.

Functions
int	parse_cmdline (int *argc, const char ***argv, int arg0,...)
	Parse the command-line for specified arguments and store the values into variables.

Detailed Description

Function Documentation

parse_cmdline()

int parse_cmdline	(	int *	argc,
		const char ***	argv,
		int	arg0,
			...
	)

Parse the command-line for specified arguments and store the values into variables.

This Functions gets the command-line, and a list of command-descriptors. Then, the command-line is parsed according to the given descriptors, storing strings, switches and numeric arguments at given addresses, and possibly calling specified functions. A default help descriptor is added. Its purpose is to present a short command overview in the case the given command-line does not fit to the descriptors.

Each command-descriptor has the following form:

short option char, long option name, comment, type, val, addr.

The short option char specifies the short form of the described option. The short form will be recognized after a single dash, or in a group of short options preceeded by a single dash. Specify ' ' if no short form should be used.

The long option name specifies the long form of the described option. The long form will be recognized after two dashes. Specify 0 if no long form should be used for this option.

The comment is a string that will be used when presenting the short command-line help.

The type specifies, if the option should be recognized as

• a number (PARSE_CMD_INT),
• a switch (PARSE_CMD_SWITCH),
• a string (PARSE_CMD_STRING),
• a function call (PARSE_CMD_FN, PARSE_CMD_FN_ARG),
• an increment/decrement operator (PARSE_CMD_INC, PARSE_CMD_DEC).

If type is PARSE_CMD_INT, the option requires a second argument on the command-line after the option. This argument is parsed as a number. It can be preceeded by 0x to present a hex-value or by 0 to present an octal form. addr is interpreted as an int-pointer. The scanned argument from the command-line is stored in this pointer.

If type is PARSE_CMD_SWITCH, addr must be a pointer to int, and the value from val is stored at this pointer.

With PARSE_CMD_STRING, an additional argument is expected at the cmdline. addr must be a pointer to const char*, and a pointer to the argument on the command line is stored at this pointer. The value in val is a default value, which is stored at addr if the corresponding option is not given on the command line.

With PARSE_CMD_FN_ARG, addr is interpreted as a function pointer of type parse_cmd_fn_t. It will be called with val as argument if the corresponding option is found.

If type is PARSE_CMD_FN_ARG, addr is as a function pointer of type parse_cmd_fn_arg_t, and handled similar to PARSE_CMD_FN. An additional argument is expected at the command line, however. It is given to the called function as 2nd argument, and parsed as an integer as with PARSE_CMD_INT as a third argument.

If type is PARSE_CMD_INC or PARSE_CMD_DEC, addr is interpreted as an int-pointer. The value of val is stored to this pointer first. For every occurence of the option in the command line, the integer referenced by addr is incremented or decremented, respectively.

The list of command-descriptors is terminated by specifying a binary 0 for the short option char.

Note: The short option char 'h' and the long option name "help" must not be specified. They are used for the default help descriptor and produce a short command-options help when specified on the command-line.

Parameters

argc	pointer to number of command line parameters as passed to main
argv	pointer to array of command line parameters as passed to main
arg0	format list describing the command line options to parse for

Returns

0 if the command-line was successfully parsed, otherwise:

• -1 if the given descriptors are somehow wrong.
• -2 if not enough memory was available to hold temporary structs.
• -3 if the given command-line args did not meet the specified set.
• -4 if the help-option was given.

Upon return, argc and argv point to a list of arguments that were not scanned as arguments. See getoptlong for details on scanning.