getoptions(3)

NAME

getoptions - Parse command line options like Perl's Getopt::Long

SYNOPSIS

#include <getoptions.h>

rc = getoptions( &argc, &argv,
	"v|verbose+",	&verbose,
	"d|debug!",	&debug,
	"s|sums=i@10",	vals, &num_vals,
	"h|help&",	help
);

if( rc != 0 ) { // Error handling }

DESCRIPTION

The getoptions() function parses command line arguments. Its arguments are pointers to argc and argv (which will be updated to reflect the non-option arguments remaining), and a set of option descriptor, variable tuples.

The option descriptors are very similar to those described in Getopt::Long, with some concessions made for C's lack of introspection. There are two types of options, those that take arguments and those that are booleans.

No-argument options

Boolean arguments are ones that are true (or false) simply by appearing on the command line. If your program has a runtime debugging option, you could pass in the option "--debug" to enable it. "--no-debug" would disable it if it had been specified ealier. The other type of boolean is the incrementing variable, such as a verbosity option that increases in value for each time "-v" or "--verbose" is specified on the command line. The last no-argument option is one that runs a handler if the option is specified, such as "--help".

Option descriptors for these three examples would be written as:

	int help_function( void ) { ... }

	int		debug = 0;
	int		verbose = 0;
	
	getoptions( &argc, &argv,
		"d|debug!",		&debug,
		"v|verbose+",		&verbose,
		"h|?|help&",		help_function
	);

No-argument options may be specified as many times as desired on the command line with no ill-effect. The last one is the one that actually takes effect.

One-argument options

The one argument options are those that expect an (optional) string on the command line. They can interpret this as a string, an integer, float, double or by a user specified handler.

If your program expects a string argument for the "--host" option, you would write the option descriptor like this and pass in the char ** argument place holder:

	char *		host_name = 0;
	...
	getoptions( &argc, &argv,
		"host=s",	&host_name
	);

The "host_name" pointer will be set to point to the string in argv[] if the "--host" option is specified on the command line. You do not need to allocate or free the memory associated with this string, but it is not guaranteed to be writeable by ANSI.

If the option descriptor was "host:s", then the string argument to the option would be optional. getoptions() looks at the next argument to see if it has a leading - to determine if it is a new option or an argument to this option.

The other type specifiers are i for integer, which expects an int *, f for float (float *), d for double (double *) and & for handler, which expects an int (*)( char * ) function pointer.

One-argument options may be specified as many times as desired on the command line with no ill-effect. The last one is the one that's value is actually stored. The "--foo=bar" style is not yet supported.

Array options

You can also specify that an option accepts an arbitrary number of arguments by adding "@N" to the one-argument option descriptor. This tells getoptions() that the pointer is actually an array of N elements. You must also pass in a pointer to an integer that will be returned with the number of elements used in the array. If your "--host" argument could be specified up to 10 times, you would say:

	char *		host_names[10];
	int		num_hosts = 0;
	...
	getoptions( &argc, &argv,
		"host=s@10",	host_names, &num_hosts
	);

This would allow the user to specify on the command line:

	program --host foo --host bar --host baz --host  ...

Special note about handlers

If you have a user supplied callback for either no-argument or one-argument cases, a non-zero return from the callback will abort the parsing and return the value to the caller of getoptions(). If the special value "GETOPTIONS_NOMATCH" is returned by the handler, getoptions will continue looking in the argument descriptors for a match.

Special note about arrays

If you run out of array space for a specific option, getoptions will continue looking in the list of option descriptors. This allows you to do something like:

	int host_overflow( char *hostname ) { ... }
	...
	getoptions( &argc, &argv,
		"hosts=s@10",	host_names, &num_hosts,
		"hosts=s&",	host_overflow
	);

RETURN VALUE

On success, getoptions() returns 0. For unknown options, -1 is returned. If a user handler returns anything other than 0 or GETOPTIONS_NOMATCH, that value is propagated to the caller of getoptions().

CONFORMING TO

Nothing. I just made it up myself.

BUGS

Ignores the current locale for comparisons.
Can not bundle single character options.
Can not distinguish between single and long options.
Lots of others

AUTHOR

Trammell Hudson