A parsed option from the command line together with its argument if it has one. More...

#include <optionparser.h>

Public Member Functions
int	type () const
	Returns Descriptor::type of this Option's Descriptor, or 0 if this Option is invalid (unused). More...

int	index () const
	Returns Descriptor::index of this Option's Descriptor, or -1 if this Option is invalid (unused). More...

int	count () const
	Returns the number of times this Option (or others with the same Descriptor::index) occurs in the argument vector. More...

bool	isFirst () const
	Returns true iff this is the first element of the linked list. More...

bool	isLast () const
	Returns true iff this is the last element of the linked list. More...

Option *	first ()
	Returns a pointer to the first element of the linked list. More...

const Option *	first () const
	const version of Option::first(). More...

Option *	last ()
	Returns a pointer to the last element of the linked list. More...

const Option *	last () const
	const version of Option::last(). More...

Option *	prev ()
	Returns a pointer to the previous element of the linked list or NULL if called on first(). More...

Option *	prevwrap ()
	Returns a pointer to the previous element of the linked list with wrap-around from first() to last(). More...

const Option *	prevwrap () const
	const version of Option::prevwrap(). More...

Option *	next ()
	Returns a pointer to the next element of the linked list or NULL if called on last(). More...

const Option *	next () const
	const version of Option::next(). More...

Option *	nextwrap ()
	Returns a pointer to the next element of the linked list with wrap-around from last() to first(). More...

void	append (Option *new_last)
	Makes `new_last` the new last() by chaining it into the list after last(). More...

	operator const Option * () const
	Casts from Option to const Option* but only if this Option is valid. More...

	operator Option * ()
	Casts from Option to Option* but only if this Option is valid. More...

	Option ()
	Creates a new Option that is a one-element linked list and has NULL desc, name, arg and namelen. More...

	Option (const Descriptor desc_, const char name_, const char *arg_)
	Creates a new Option that is a one-element linked list and has the given values for desc, name and arg. More...

void	operator= (const Option &orig)
	Makes `*this` a copy of `orig` except for the linked list pointers. More...

	Option (const Option &orig)
	Makes `*this` a copy of `orig` except for the linked list pointers. More...

Public Attributes
const Descriptor *	desc
	Pointer to this Option's Descriptor. More...

const char *	name
	The name of the option as used on the command line. More...

const char *	arg
	Pointer to this Option's argument (if any). More...

int	namelen
	The length of the option name. More...

Private Member Functions
void	init (const Descriptor desc_, const char name_, const char *arg_)

Static Private Member Functions
static Option *	tag (Option *ptr)

static Option *	untag (Option *ptr)

static bool	isTagged (Option *ptr)

Private Attributes
Option *	next_

Option *	prev_

Detailed Description

A parsed option from the command line together with its argument if it has one.

The Parser chains all parsed options with the same Descriptor::index together to form a linked list. This allows you to easily implement all of the common ways of handling repeated options and enable/disable pairs.

Test for presence of a switch in the argument vector:
if ( options[QUIET] ) ...
Evaluate –enable-foo/–disable-foo pair where the last one used wins:
if ( options[FOO].last()->type() == DISABLE ) ...
Cumulative option (-v verbose, -vv more verbose, -vvv even more verbose):
int verbosity = options[VERBOSE].count();
Iterate over all –file=<fname> arguments:
for (Option* opt = options[FILE]; opt; opt = opt->next())

* fname = opt->arg; ...

Definition at line 442 of file optionparser.h.

Constructor & Destructor Documentation

option::Option::Option ( )

inline

Creates a new Option that is a one-element linked list and has NULL desc, name, arg and namelen.

Definition at line 787 of file optionparser.h.

References next_, prev_, and tag().

option::Option::Option	(	const Descriptor *	desc_,
		const char *	name_,
		const char *	arg_
	)

inline

Creates a new Option that is a one-element linked list and has the given values for desc, name and arg.

If name_ points at a character other than '-' it will be assumed to refer to a short option and namelen will be set to 1. Otherwise the length will extend to the first '=' character or the string's 0-terminator.

Definition at line 802 of file optionparser.h.

References init().

option::Option::Option ( const Option & orig )

inline

Makes *this a copy of orig except for the linked list pointers.

After this operation *this will be a one-element linked list.

Definition at line 822 of file optionparser.h.

References arg, desc, init(), and name.

Member Function Documentation

void option::Option::append ( Option * new_last )

inline

Makes new_last the new last() by chaining it into the list after last().

It doesn't matter which element you call append() on. The new element will always be appended to last().

Attention: new_last must not yet be part of a list, or that list will become corrupted, because this method does not unchain new_last from an existing list.

Definition at line 731 of file optionparser.h.

References first(), last(), next_, prev_, and tag().

Referenced by option::Parser::StoreOptionAction::perform().

int option::Option::count ( ) const

inline

Returns the number of times this Option (or others with the same Descriptor::index) occurs in the argument vector.

This corresponds to the number of elements in the linked list this Option is part of. It doesn't matter on which element you call count(). The return value is always the same.

Use this to implement cumulative options, such as -v, -vv, -vvv for different verbosity levels.

Returns 0 when called for an unused/invalid option.

Definition at line 559 of file optionparser.h.

References casacore::C::c, desc, first(), isLast(), and next_.

Option* option::Option::first ( )

inline

Returns a pointer to the first element of the linked list.

Use this when you want the first occurrence of an option on the command line to take precedence. Note that this is not the way most programs handle options. You should probably be using last() instead.

Note: This method may be called on an unused/invalid option and will return a pointer to the option itself.

Definition at line 608 of file optionparser.h.

References isFirst(), and prev_.

Referenced by append(), count(), first(), and last().

const Option* option::Option::first ( ) const

inline

const version of Option::first().

Definition at line 619 of file optionparser.h.

References first().

int option::Option::index ( ) const

inline

Returns Descriptor::index of this Option's Descriptor, or -1 if this Option is invalid (unused).

Definition at line 542 of file optionparser.h.

References desc, and option::Descriptor::index.

void option::Option::init	(	const Descriptor *	desc_,
		const char *	name_,
		const char *	arg_
	)

inlineprivate

Definition at line 836 of file optionparser.h.

References arg, desc, name, namelen, next_, prev_, and tag().

Referenced by operator=(), and Option().

bool option::Option::isFirst ( ) const

inline

Returns true iff this is the first element of the linked list.

The first element in the linked list is the first option on the command line that has the respective Descriptor::index value.

Returns true for an unused/invalid option.

Definition at line 579 of file optionparser.h.

References isTagged(), and prev_.

Referenced by first(), and prev().

bool option::Option::isLast ( ) const

inline

Returns true iff this is the last element of the linked list.

The last element in the linked list is the last option on the command line that has the respective Descriptor::index value.

Returns true for an unused/invalid option.

Definition at line 592 of file optionparser.h.

References isTagged(), and next_.

Referenced by count(), and next().

static bool option::Option::isTagged ( Option * ptr )

inlinestaticprivate

Definition at line 863 of file optionparser.h.

Referenced by isFirst(), and isLast().

Option* option::Option::last ( )

inline

Returns a pointer to the last element of the linked list.

Use this when you want the last occurrence of an option on the command line to take precedence. This is the most common way of handling conflicting options.

Note: This method may be called on an unused/invalid option and will return a pointer to the option itself.

Tip:: If you have options with opposite meanings (e.g. –enable-foo and –disable-foo), you can assign them the same Descriptor::index to get them into the same list. Distinguish them by Descriptor::type and all you have to do is check last()->type() to get the state listed last on the command line.

Definition at line 640 of file optionparser.h.

References first(), and prevwrap().

Referenced by append().

const Option* option::Option::last ( ) const

inline

const version of Option::last().

Definition at line 648 of file optionparser.h.

References first(), and prevwrap().

Option* option::Option::next ( void )

inline

Returns a pointer to the next element of the linked list or NULL if called on last().

If called on last() this method returns NULL. Otherwise it will return the option with the same Descriptor::index that follows this option on the command line.

Definition at line 695 of file optionparser.h.

References isLast(), and next_.

const Option* option::Option::next ( void ) const

inline

const version of Option::next().

Definition at line 703 of file optionparser.h.

References isLast(), and next_.

Option* option::Option::nextwrap ( )

inline

Returns a pointer to the next element of the linked list with wrap-around from last() to first().

If called on last() this method returns first(). Otherwise it will return the option with the same Descriptor::index that follows this option on the command line.

Definition at line 716 of file optionparser.h.

References next_, and untag().

option::Option::operator const Option * ( ) const

inline

Casts from Option to const Option* but only if this Option is valid.

If this Option is valid (i.e. desc!=NULL), returns this. Otherwise returns NULL. This allows testing an Option directly in an if-clause to see if it is used:

* if (options[CREATE])
* {
*   ...
* }
* 

It also allows you to write loops like this:

for (Option* opt = options[FILE]; opt; opt = opt->next())

* fname = opt->arg; ...

Definition at line 757 of file optionparser.h.

References desc.

option::Option::operator Option * ( )

inline

Casts from Option to Option* but only if this Option is valid.

If this Option is valid (i.e. desc!=NULL), returns this. Otherwise returns NULL. This allows testing an Option directly in an if-clause to see if it is used:

* if (options[CREATE])
* {
*   ...
* }
* 

It also allows you to write loops like this:

for (Option* opt = options[FILE]; opt; opt = opt->next())

* fname = opt->arg; ...

Definition at line 778 of file optionparser.h.

References desc.

void option::Option::operator= ( const Option & orig )

inline

Makes *this a copy of orig except for the linked list pointers.

After this operation *this will be a one-element linked list.

Definition at line 812 of file optionparser.h.

References arg, desc, init(), and name.

Option* option::Option::prev ( )

inline

Returns a pointer to the previous element of the linked list or NULL if called on first().

If called on first() this method returns NULL. Otherwise it will return the option with the same Descriptor::index that precedes this option on the command line.

Definition at line 661 of file optionparser.h.

References isFirst(), and prev_.

Option* option::Option::prevwrap ( )

inline

Returns a pointer to the previous element of the linked list with wrap-around from first() to last().

If called on first() this method returns last(). Otherwise it will return the option with the same Descriptor::index that precedes this option on the command line.

Definition at line 674 of file optionparser.h.

References prev_, and untag().

Referenced by last().

const Option* option::Option::prevwrap ( ) const

inline

const version of Option::prevwrap().

Definition at line 682 of file optionparser.h.

References prev_, and untag().

static Option* option::Option::tag ( Option * ptr )

inlinestaticprivate

Definition at line 853 of file optionparser.h.

Referenced by append(), init(), and Option().

int option::Option::type ( ) const

inline

Returns Descriptor::type of this Option's Descriptor, or 0 if this Option is invalid (unused).

Because this method (and last(), too) can be used even on unused Options with desc==0, you can (provided you arrange your types properly) switch on type() without testing validity first.

* enum OptionType { UNUSED=0, DISABLED=0, ENABLED=1 };
* enum OptionIndex { FOO };
* const Descriptor usage[] = {
*   { FOO, ENABLED,  "", "enable-foo",  Arg::None, 0 },
*   { FOO, DISABLED, "", "disable-foo", Arg::None, 0 },
*   { 0, 0, 0, 0, 0, 0 } };
* ...
* switch(options[FOO].last()->type()) // no validity check required!
* {
*   case ENABLED: ...
*   case DISABLED: ...  // UNUSED==DISABLED !
* }
* 

Definition at line 533 of file optionparser.h.

References desc, and option::Descriptor::type.

static Option* option::Option::untag ( Option * ptr )

inlinestaticprivate

Definition at line 858 of file optionparser.h.

Referenced by nextwrap(), and prevwrap().

Member Data Documentation

const char* option::Option::arg

Pointer to this Option's argument (if any).

NULL if this option has no argument. Do not confuse this with the empty string which is a valid argument.

Definition at line 489 of file optionparser.h.

Referenced by alma::AlmaArg::Bool(), alma::AlmaArg::Float(), init(), alma::AlmaArg::Long(), operator=(), Option(), option::Arg::Optional(), alma::AlmaArg::Required(), alma::AlmaArg::uInt(), and option::Parser::workhorse().

const Descriptor* option::Option::desc

Pointer to this Option's Descriptor.

Remember that the first dummy descriptor (see Descriptor::longopt) is used for unknown options.

Attention: desc==NULL signals that this Option is unused. This is the default state of elements in the result array. You don't need to test desc explicitly. You can simply write something like this:
* if (options[CREATE])

* {

* ...

* }

*

This works because of operator const Option*() .

Definition at line 465 of file optionparser.h.

Referenced by count(), index(), init(), operator const Option *(), operator Option *(), operator=(), Option(), option::Parser::StoreOptionAction::perform(), and type().

const char* option::Option::name

The name of the option as used on the command line.

The main purpose of this string is to be presented to the user in messages.

In the case of a long option, this is the actual argv pointer, i.e. the first character is a '-'. In the case of a short option this points to the option character within the argv string.

Note that in the case of a short option group or an attached option argument, this string will contain additional characters following the actual name. Use namelen to filter out the actual option name only.

Definition at line 481 of file optionparser.h.

Referenced by init(), operator=(), Option(), option::Arg::Optional(), and alma::AlmaArg::printError().

int option::Option::namelen

The length of the option name.

Because name points into the actual argv string, the option name may be followed by more characters (e.g. other short options in the same short option group). This value is the number of bytes (not characters!) that are part of the actual name.

For a short option, this length is always 1. For a long option this length is always at least 2 if single minus long options are permitted and at least 3 if they are disabled.

Note: In the pathological case of a minus within a short option group (e.g. -xf-z), this length is incorrect, because this case will be misinterpreted as a long option and the name will therefore extend to the string's 0-terminator or a following '=" character if there is one. This is irrelevant for most uses of name and namelen. If you really need to distinguish the case of a long and a short option, compare name to the argv pointers. A long option's name is always identical to one of them, whereas a short option's is never.

Definition at line 510 of file optionparser.h.

Referenced by init(), option::Arg::Optional(), and alma::AlmaArg::printError().

Option* option::Option::next_

private

Definition at line 444 of file optionparser.h.

Referenced by append(), count(), init(), isLast(), next(), nextwrap(), and Option().