Checks argument vectors for validity and parses them into data structures that are easier to work with. More...

#include <optionparser.h>

Classes
struct	Action

class	StoreOptionAction

Public Member Functions
	Parser ()
	Creates a new Parser. More...

	Parser (bool gnu, const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	Creates a new Parser and immediately parses the given argument vector. More...

	Parser (bool gnu, const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

	Parser (const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

	Parser (const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

void	parse (bool gnu, const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	Parses the given argument vector. More...

void	parse (bool gnu, const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

void	parse (const Descriptor usage[], int argc, const char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

void	parse (const Descriptor usage[], int argc, char **argv, Option options[], Option buffer[], int min_abbr_len=0, bool single_minus_longopt=false, int bufmax=-1)
	! More...

int	optionsCount ()
	Returns the number of valid Option objects in `buffer`[]. More...

int	nonOptionsCount ()
	Returns the number of non-option arguments that remained at the end of the most recent parse() that actually encountered non-option arguments. More...

const char **	nonOptions ()
	Returns a pointer to an array of non-option arguments (only valid if `nonOptionsCount() >0` ). More...

const char *	nonOption (int i)
	Returns `nonOptions()[i]` (without checking if i is in range!). More...

bool	error ()
	Returns `true` if an unrecoverable error occurred while parsing options. More...

Static Private Member Functions
static bool	workhorse (bool gnu, const Descriptor usage[], int numargs, const char **args, Action &action, bool single_minus_longopt, bool print_errors, int min_abbr_len)

static bool	streq (const char st1, const char st2)

static bool	streqabbr (const char st1, const char st2, long long min)

static bool	instr (char ch, const char *st)

static void	shift (const char **args, int count)

Private Attributes
int	op_count

int	nonop_count

const char **	nonop_args

bool	err

Friends
struct	Stats

Detailed Description

Checks argument vectors for validity and parses them into data structures that are easier to work with.

Example:: * int main(int argc, char* argv[])

* {

* argc-=(argc>0); argv+=(argc>0); // skip program name argv[0] if present

* option::Stats stats(usage, argc, argv);

* option::Option options[stats.options_max], buffer[stats.buffer_max];

* option::Parser parse(usage, argc, argv, options, buffer);

*

* if (parse.error())

* return 1;

*

* if (options[HELP])

* ...

*

Definition at line 1080 of file optionparser.h.

Constructor & Destructor Documentation

option::Parser::Parser ( )

inline

Creates a new Parser.

Definition at line 1091 of file optionparser.h.

option::Parser::Parser	(	bool	gnu,
		const Descriptor	usage[],
		int	argc,
		const char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

Creates a new Parser and immediately parses the given argument vector.

Parameters

gnu	if true, parse() will not stop at the first non-option argument. Instead it will reorder arguments so that all non-options are at the end. This is the default behaviour of GNU getopt() but is not conforming to POSIX. Note, that once the argument vector has been reordered, the `gnu` flag will have no further effect on this argument vector. So it is enough to pass `gnu==true` when creating Stats.
usage	Array of Descriptor objects that describe the options to support. The last entry of this array must have 0 in all fields.
argc	The number of elements from `argv` that are to be parsed. If you pass -1, the number will be determined automatically. In that case the `argv` list must end with a NULL pointer.
argv	The arguments to be parsed. If you pass -1 as `argc` the last pointer in the `argv` list must be NULL to mark the end.
options	Each entry is the first element of a linked list of Options. Each new option that is parsed will be appended to the list specified by that Option's Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), it will be replaced rather than appended to. The minimum length of this array is the greatest Descriptor::index value that occurs in `usage` PLUS ONE.
buffer	Each argument that is successfully parsed (including unknown arguments, if they have a Descriptor whose CheckArg does not return ARG_ILLEGAL) will be stored in this array. parse() scans the array for the first invalid entry and begins writing at that index. You can pass `bufmax` to limit the number of options stored.
min_abbr_len	Passing a value `min_abbr_len > 0` enables abbreviated long options. The parser will match a prefix of a long option as if it was the full long option (e.g. `–foob=10` will be interpreted as if it was `–foobar=10` ), as long as the prefix has at least `min_abbr_len` characters (not counting the `–` ) and is unambiguous. Be careful if combining `min_abbr_len=1` with `single_minus_longopt=true` because the ambiguity check does not consider short options and abbreviated single minus long options will take precedence over short options.
single_minus_longopt	Passing `true` for this option allows long options to begin with a single minus. The double minus form will still be recognized. Note that single minus long options take precedence over short options and short option groups. E.g. `-file` would be interpreted as `–file` and not as `-f -i -l -e` (assuming a long option named `"file"` exists).
bufmax	The greatest index in the `buffer`[] array that parse() will write to is `bufmax-1`. If there are more options, they will be processed (in particular their CheckArg will be called) but not stored. If you used Stats::buffer_max to dimension this array, you can pass -1 (or not pass `bufmax` at all) which tells parse() that the buffer is "large enough".

Attention: Remember that options and buffer store Option objects, not pointers. Therefore it is not possible for the same object to be in both arrays. For those options that are found in both buffer[] and options[] the respective objects are independent copies. And only the objects in options[] are properly linked via Option::next() and Option::prev(). You can iterate over buffer[] to process all options in the order they appear in the argument vector, but if you want access to the other Options with the same Descriptor::index, then you must access the linked list via options[]. You can get the linked list in options from a buffer object via something like options[buffer[i].index()].

Definition at line 1100 of file optionparser.h.

References parse().

option::Parser::Parser	(	bool	gnu,
		const Descriptor	usage[],
		int	argc,
		char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

Parser(...) with non-const argv.

Definition at line 1108 of file optionparser.h.

References parse().

option::Parser::Parser	(	const Descriptor	usage[],
		int	argc,
		const char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

POSIX Parser(...) (gnu==false).

Definition at line 1116 of file optionparser.h.

References parse().

option::Parser::Parser	(	const Descriptor	usage[],
		int	argc,
		char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

POSIX Parser(...) (gnu==false) with non-const argv.

Definition at line 1124 of file optionparser.h.

References parse().

Member Function Documentation

bool option::Parser::error ( )

inline

Returns true if an unrecoverable error occurred while parsing options.

An illegal argument to an option (i.e. CheckArg returns ARG_ILLEGAL) is an unrecoverable error that aborts the parse. Unknown options are only an error if their CheckArg function returns ARG_ILLEGAL. Otherwise they are collected. In that case if you want to exit the program if either an illegal argument or an unknown option has been passed, use code like this

* if (parser.error() || options[UNKNOWN])
*   exit(1);
* 

Definition at line 1283 of file optionparser.h.

References err.

static bool option::Parser::instr	(	char	ch,
		const char *	st
	)

inlinestaticprivate

Definition at line 1365 of file optionparser.h.

Referenced by workhorse().

const char* option::Parser::nonOption ( int i )

inline

Returns nonOptions()[i] (without checking if i is in range!).

Definition at line 1263 of file optionparser.h.

References nonOptions().

const char** option::Parser::nonOptions ( )

inline

Returns a pointer to an array of non-option arguments (only valid if nonOptionsCount() >0 ).

Note

parse() does not copy arguments, so this pointer points into the actual argument vector as passed to parse().
As explained at nonOptionsCount() this pointer is only changed by parse() calls that actually encounter non-option arguments. A parse() call that encounters only options, will not change nonOptions().

Definition at line 1255 of file optionparser.h.

References nonop_args.

Referenced by nonOption().

int option::Parser::nonOptionsCount ( )

inline

Returns the number of non-option arguments that remained at the end of the most recent parse() that actually encountered non-option arguments.

Note: A parse() that does not encounter non-option arguments will leave this value as well as nonOptions() undisturbed. This means you can feed the Parser a default argument vector that contains non-option arguments (e.g. a default filename). Then you feed it the actual arguments from the user. If the user has supplied at least one non-option argument, all of the non-option arguments from the default disappear and are replaced by the user's non-option arguments. However, if the user does not supply any non-option arguments the defaults will still be in effect.

Definition at line 1239 of file optionparser.h.

References nonop_count.

int option::Parser::optionsCount ( )

inline

Returns the number of valid Option objects in buffer[].

Note

The returned value always reflects the number of Options in the buffer[] array used for the most recent call to parse().
The count (and the buffer[]) includes unknown options if they are collected (see Descriptor::longopt).

Definition at line 1220 of file optionparser.h.

References op_count.

void option::Parser::parse	(	bool	gnu,
		const Descriptor	usage[],
		int	argc,
		const char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

Parses the given argument vector.

Parameters

gnu	if true, parse() will not stop at the first non-option argument. Instead it will reorder arguments so that all non-options are at the end. This is the default behaviour of GNU getopt() but is not conforming to POSIX. Note, that once the argument vector has been reordered, the `gnu` flag will have no further effect on this argument vector. So it is enough to pass `gnu==true` when creating Stats.
usage	Array of Descriptor objects that describe the options to support. The last entry of this array must have 0 in all fields.
argc	The number of elements from `argv` that are to be parsed. If you pass -1, the number will be determined automatically. In that case the `argv` list must end with a NULL pointer.
argv	The arguments to be parsed. If you pass -1 as `argc` the last pointer in the `argv` list must be NULL to mark the end.
options	Each entry is the first element of a linked list of Options. Each new option that is parsed will be appended to the list specified by that Option's Descriptor::index. If an entry is not yet used (i.e. the Option is invalid), it will be replaced rather than appended to. The minimum length of this array is the greatest Descriptor::index value that occurs in `usage` PLUS ONE.
buffer	Each argument that is successfully parsed (including unknown arguments, if they have a Descriptor whose CheckArg does not return ARG_ILLEGAL) will be stored in this array. parse() scans the array for the first invalid entry and begins writing at that index. You can pass `bufmax` to limit the number of options stored.
min_abbr_len	Passing a value `min_abbr_len > 0` enables abbreviated long options. The parser will match a prefix of a long option as if it was the full long option (e.g. `–foob=10` will be interpreted as if it was `–foobar=10` ), as long as the prefix has at least `min_abbr_len` characters (not counting the `–` ) and is unambiguous. Be careful if combining `min_abbr_len=1` with `single_minus_longopt=true` because the ambiguity check does not consider short options and abbreviated single minus long options will take precedence over short options.
single_minus_longopt	Passing `true` for this option allows long options to begin with a single minus. The double minus form will still be recognized. Note that single minus long options take precedence over short options and short option groups. E.g. `-file` would be interpreted as `–file` and not as `-f -i -l -e` (assuming a long option named `"file"` exists).
bufmax	The greatest index in the `buffer`[] array that parse() will write to is `bufmax-1`. If there are more options, they will be processed (in particular their CheckArg will be called) but not stored. If you used Stats::buffer_max to dimension this array, you can pass -1 (or not pass `bufmax` at all) which tells parse() that the buffer is "large enough".

Attention: Remember that options and buffer store Option objects, not pointers. Therefore it is not possible for the same object to be in both arrays. For those options that are found in both buffer[] and options[] the respective objects are independent copies. And only the objects in options[] are properly linked via Option::next() and Option::prev(). You can iterate over buffer[] to process all options in the order they appear in the argument vector, but if you want access to the other Options with the same Descriptor::index, then you must access the linked list via options[]. You can get the linked list in options from a buffer object via something like options[buffer[i].index()].

Definition at line 1515 of file optionparser.h.

References err, and workhorse().

Referenced by parse(), and Parser().

void option::Parser::parse	(	bool	gnu,
		const Descriptor	usage[],
		int	argc,
		char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

parse() with non-const argv.

Definition at line 1191 of file optionparser.h.

References parse().

void option::Parser::parse	(	const Descriptor	usage[],
		int	argc,
		const char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

POSIX parse() (gnu==false).

Definition at line 1198 of file optionparser.h.

References parse().

void option::Parser::parse	(	const Descriptor	usage[],
		int	argc,
		char **	argv,
		Option	options[],
		Option	buffer[],
		int	min_abbr_len = `0`,
		bool	single_minus_longopt = `false`,
		int	bufmax = `-1`
	)

inline

!

POSIX parse() (gnu==false) with non-const argv.

Definition at line 1205 of file optionparser.h.

References parse().

static void option::Parser::shift	(	const char **	args,
		int	count
	)

inlinestaticprivate

Definition at line 1377 of file optionparser.h.

Referenced by workhorse().

static bool option::Parser::streq	(	const char *	st1,
		const char *	st2
	)

inlinestaticprivate

Definition at line 1315 of file optionparser.h.

Referenced by workhorse().

static bool option::Parser::streqabbr	(	const char *	st1,
		const char *	st2,
		long long	min
	)

inlinestaticprivate

Definition at line 1347 of file optionparser.h.

Referenced by workhorse().

bool option::Parser::workhorse	(	bool	gnu,
		const Descriptor	usage[],
		int	numargs,
		const char **	args,
		Action &	action,
		bool	single_minus_longopt,
		bool	print_errors,
		int	min_abbr_len
	)

inlinestaticprivate

protect against NULL pointer

in POSIX mode the first non-option argument terminates the option list a lone minus character is a non-option argument

– terminates the option list. The – itself is skipped.

if we found something, disable handle_short_options (only relevant if single_minus_longopt)

possibly detached argument

if the potential argument is attached

look for dummy entry (shortopt == "" and longopt == "") to use as Descriptor for unknown options

skip one element of the argument vector, if it's a separated argument

No further short options are possible after an argument

Definition at line 1539 of file optionparser.h.

References option::Option::arg, option::ARG_IGNORE, option::ARG_ILLEGAL, option::ARG_NONE, option::ARG_OK, option::Descriptor::check_arg, option::Parser::Action::finished(), instr(), option::Parser::Action::perform(), shift(), option::Descriptor::shortopt, streq(), and streqabbr().

Referenced by option::Stats::add(), and parse().

Friends And Related Function Documentation

friend struct Stats

friend

Definition at line 1289 of file optionparser.h.

Member Data Documentation

bool option::Parser::err

private

Definition at line 1085 of file optionparser.h.

Referenced by error(), and parse().

const char** option::Parser::nonop_args

private

Definition at line 1084 of file optionparser.h.

Referenced by option::Parser::StoreOptionAction::finished(), and nonOptions().

int option::Parser::nonop_count

private

Definition at line 1083 of file optionparser.h.

Referenced by option::Parser::StoreOptionAction::finished(), and nonOptionsCount().

int option::Parser::op_count

private

Definition at line 1082 of file optionparser.h.

Referenced by optionsCount(), option::Parser::StoreOptionAction::perform(), and option::Parser::StoreOptionAction::StoreOptionAction().

The documentation for this class was generated from the following file:

casa/code/stdcasa/optionparser.h

Classes

Public Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation