Detailed Description

Class for command-line argument parsing.

A typical setup looks as follows:

int main( int argc, char** argv )
{
    std::string name("G+SMO");
    gsCmdLine cmd("This is my hello world example."); // Constructor
    cmd.addString("n", "name", "Your name", name);
    // Here more of the addXxxx member functions might follow...
    // AFTER all options have been registered with the addXxxx functions,
    // we parse the command line. If the return value is false, we exit.
    // At this point, the variable "name" is updated to the value given
    // by the user.
    try { cmd.getValues(argc, argv); } catch(int rv) { return rv; }
    // Here, no more of the addXxxx function are allowed to follow.
    // If everything was fine, we proceed:
    gsInfo << "Hello " << name << "!\n";
    return 0;
}

Inheritance diagram for gsCmdLine:

Collaboration diagram for gsCmdLine:

Public Types
enum	updateType
	Options for gsOptionList::update.

Public Member Functions
void	addInt (const std::string &flag, const std::string &name, const std::string &desc, intVal_t &value)
	Register an int option for the command line. More...

void	addInt (const std::string &label, const std::string &desc, const index_t &value)
	Adds a option named label, with description desc and value value. More...

void	addMultiInt (const std::string &label, const std::string &desc, const std::vector< index_t > &values)
	Adds an option-group gn containing values of a std::vector. More...

void	addMultiInt (const std::string &flag, const std::string &name, const std::string &desc, std::vector< intVal_t > &value)
	Register an int option for the command line, which can be assigned more than once. More...

void	addMultiReal (const std::string &flag, const std::string &name, const std::string &desc, std::vector< real_t > &value)
	Register a real option for the command line, which can be assigned more than once. More...

void	addMultiString (const std::string &flag, const std::string &name, const std::string &desc, std::vector< std::string > &value)
	Register a string option for the command line, which can be assigned more than once. More...

void	addNewInt (const std::string &flag, const std::string &name, const std::string &desc, intVal_t value)
	Second version: unbinded integer command-line argument.

void	addPlainString (const std::string &name, const std::string &desc, std::string &value)
	Register a string parameter that has to be given directly (not as an option, i.e., not after a flag starting with "-" or "--") More...

void	addReal (const std::string &label, const std::string &desc, const Real &value)
	Adds a option named label, with description desc and value value. More...

void	addReal (const std::string &flag, const std::string &name, const std::string &desc, real_t &value)
	Register a real option for the command line. More...

void	addString (const std::string &label, const std::string &desc, const std::string &value)
	Adds a option named label, with description desc and value value. More...

void	addString (const std::string &flag, const std::string &name, const std::string &desc, std::string &value)
	Register a string option for the command line. More...

void	addSwitch (const std::string &label, const std::string &desc, const bool &value)
	Adds a option named label, with description desc and value value. More...

void	addSwitch (const std::string &flag, const std::string &name, const std::string &desc, bool &value)
	Register a switch option for the command line. More...

void	addSwitch (const std::string &name, const std::string &desc, bool &value)
	Register a switch option for the command line without flag. More...

index_t	askInt (const std::string &label, const index_t &value=0) const
	Reads value for option label from options. More...

Real	askReal (const std::string &label, const Real &value=0) const
	Reads value for option label from options. More...

std::string	askString (const std::string &label, const std::string &value="") const
	Reads value for option label from options. More...

bool	askSwitch (const std::string &label, const bool &value=false) const
	Reads value for option label from options. More...

std::vector< OptionListEntry >	getAllEntries () const
	Provides a list of all entries as vector of gsOptionList::OptionListEntry structs.

bool	getExceptionHandling () const
	Gets the exception handling status (true/false)

gsOptionList	getGroup (const std::string &gn) const
	Creates a new gsOptionList, where only the options from the group gn are taken. In the result, the groupname and the corresponding dot are removed. More...

const index_t &	getInt (const std::string &label) const
	Reads value for option label from options. More...

std::string &	getMessage ()
	Returns the program's description (as specified in the constructor)

std::vector< index_t >	getMultiInt (const std::string &gn) const
	Reads values of an option-group gn into a std::vector. More...

std::vector< Real >	getMultiReal (const std::string &gn) const
	Reads values of an option-group gn into a std::vector. More...

std::vector< std::string >	getMultiString (const std::string &gn) const
	Reads values of an option-group gn into a std::vector. More...

Real	getReal (const std::string &label) const
	Reads value for option label from options. More...

std::string	getString (const std::string &label) const
	Reads value for option label from options. More...

bool	getSwitch (const std::string &label) const
	Reads value for option label from options. More...

void	getValues (int argc, char *argv[])
	Parses the command line based on the specified parameters. More...

	gsCmdLine (const std::string &message, const char delimiter= ' ', bool helpAndVersion=true)
	Command line constructor. Defines how the arguments will be parsed. More...

bool	hasGlobals () const
	Checks if there are labels that do not belong to a group. More...

bool	hasGroup (const std::string &gn) const
	Checks if there are labels that belong to the group gn. More...

std::ostream &	print (std::ostream &os) const
	Prints this list of options to stream os.

void	remove (const std::string &label)
	Removes the option named label (if it exists).

void	setExceptionHandling (const bool state)
	Sets exception handling (true/false)

void	setInt (const std::string &label, const index_t &value)
	Sets an existing option label to be equal to value. More...

void	setReal (const std::string &label, const Real &value)
	Sets an existing option label to be equal to value. More...

void	setString (const std::string &label, const std::string &value)
	Sets an existing option label to be equal to value. More...

void	setSwitch (const std::string &label, const bool &value)
	Sets an existing option label to be equal to value. More...

size_t	size () const
	Returns the length of this list of options.

void	swap (gsOptionList &other)
	Swaps contents.

void	toggleSwitch (const std::string &label)
	Toggles switch ( boolean )

void	update (const gsOptionList &other, updateType type=ignoreIfUnknown)
	Updates the object using the data from other. More...

bool	valid (int argc, char *argv[]) const

gsOptionList	wrapIntoGroup (const std::string &gn) const
	Creates a new gsOptionList where all labels are wrapped into a groupname gn. More...

Static Public Member Functions
static void	printVersion ()
	Prints the version information.

Private Member Functions
void	updateOptionList ()

Constructor & Destructor Documentation

gsCmdLine	(	const std::string &	message,
		const char	delimiter = `' '`,
		bool	helpAndVersion = `true`
	)

Command line constructor. Defines how the arguments will be parsed.

Parameters

message	The message to be used in the usage output.
delimiter	The character that is used to separate the argument flag/name from the value. Defaults to ' ' (space).
helpAndVersion	Whether or not to create the Help and Version switches. Defaults to true.

The options that are allowed in the command line have to be defined using the member functions addInt, addMultiInt, addReal, addMultiReal, addString, addMultiString, addSwitch and addPlainString. Finally, the parsing is invoked by calling getValues.

Member Function Documentation

void addInt	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		intVal_t &	value
	)

Register an int option for the command line.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const variable, initialized with the default value. When getValues is invoked and the user provided a value, it is written to that variable.

If the flag is "n", the user might call "-n 10" at the command line. It the name is "size", the user might call "--size 10" at the command line.

void addInt	(	const std::string &	label,
		const std::string &	desc,
		const index_t &	value
	)

inherited

Adds a option named label, with description desc and value value.

If an option with label already exists with the same type, the function overwrites it. If it has another type, the function throws.

void addMultiInt	(	const std::string &	label,
		const std::string &	desc,
		const std::vector< index_t > &	values
	)

inherited

Adds an option-group gn containing values of a std::vector.

If gn is not found, the function throws.

void addMultiInt	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		std::vector< intVal_t > &	value
	)

Register an int option for the command line, which can be assigned more than once.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const vector. When getValues is invoked, the vector is filled with that values. Pre-existing values are kept only if the option has been used zero times.

If the flag is "n", the user might call "-n 10" at the command line. It the name is "size", the user might call "--size 10" at the command line.

void addMultiReal	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		std::vector< real_t > &	value
	)

Register a real option for the command line, which can be assigned more than once.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const vector. When getValues is invoked, the vector is filled with that values. Pre-existing values are kept only if the option has been used zero times.

If the flag is "t", the user might call "-t .5" at the command line. It the name is "tau", the user might call "--tau .5" at the command line.

void addMultiString	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		std::vector< std::string > &	value
	)

Register a string option for the command line, which can be assigned more than once.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const vector. When getValues is invoked, the vector is filled with that values. Pre-existing values are kept only if the option has been used zero times.

If the flag is "f", the user might call "-f foo.xml" at the command line. If the name is "file", the user might call "--file foo.xml" at the command line.

void addPlainString	(	const std::string &	name,
		const std::string &	desc,
		std::string &	value
	)

Register a string parameter that has to be given directly (not as an option, i.e., not after a flag starting with "-" or "--")

Parameters

name	Name of the option.
desc	Description (printed if –help is invoked)
value	This should be a non-const variable. When getValues is invoked, the user-provided value is written to that variable.

You must not declare more than one plain string.

void addReal	(	const std::string &	label,
		const std::string &	desc,
		const Real &	value
	)

inherited

Adds a option named label, with description desc and value value.

If an option with label already exists with the same type, the function overwrites it. If it has another type, the function throws.

void addReal	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		real_t &	value
	)

Register a real option for the command line.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used
name	Long form of the flag
desc	Description (printed if –help is invoked)
value	This should be a non-const variable, initialized with the default value. When getValues is invoked and the user provided a value, it is written to that variable.

If the flag is "t", the user might call "-t .5" at the command line. It the name is "tau", the user might call "--tau .5" at the command line.

void addString	(	const std::string &	label,
		const std::string &	desc,
		const std::string &	value
	)

inherited

Adds a option named label, with description desc and value value.

If an option with label already exists with the same type, the function overwrites it. If it has another type, the function throws.

void addString	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		std::string &	value
	)

Register a string option for the command line.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const variable, initialized with the default value. When getValues is invoked and the user provided a value, it is written to that variable.

If the flag is "f", the user might call "-f foo.xml" at the command line. If the name is "file", the user might call "--file foo.xml" at the command line.

void addSwitch	(	const std::string &	label,
		const std::string &	desc,
		const bool &	value
	)

inherited

Adds a option named label, with description desc and value value.

If an option with label already exists with the same type, the function overwrites it. If it has another type, the function throws.

void addSwitch	(	const std::string &	flag,
		const std::string &	name,
		const std::string &	desc,
		bool &	value
	)

Register a switch option for the command line.

Parameters

flag	One character flag for using the option. If empty, no such flag can be used.
name	Long form of the flag.
desc	Description (printed if –help is invoked)
value	This should be a non-const bool variable. When getValues is invoked and the user has added the switch on the command line, the value is toggled (i.e. if false it becomes true, if true it becomes false)

If the flag is "l", the user might call "-l" at the command line. If the name is "log", the user might call "--log" at the command line.

void addSwitch	(	const std::string &	name,
		const std::string &	desc,
		bool &	value
	)

inline

Register a switch option for the command line without flag.

See Also: gsCmdLine::addSwitch

index_t askInt	(	const std::string &	label,
		const index_t &	value = `0`
	)		const

inherited

Reads value for option label from options.

If label is not found, it defaults to value (otherwise value is not used).

gsOptionList::Real askReal	(	const std::string &	label,
		const Real &	value = `0`
	)		const

inherited

Reads value for option label from options.

If label is not found, it defaults to value (otherwise value is not used).

std::string askString	(	const std::string &	label,
		const std::string &	value = `""`
	)		const

inherited

Reads value for option label from options.

If label is not found, it defaults to value (otherwise value is not used).

bool askSwitch	(	const std::string &	label,
		const bool &	value = `false`
	)		const

inherited

Reads value for option label from options.

If label is not found, it defaults to value (otherwise value is not used).

gsOptionList getGroup ( const std::string & gn ) const

inherited

Creates a new gsOptionList, where only the options from the group gn are taken. In the result, the groupname and the corresponding dot are removed.

If the groupname is "IterativeSolver", then a label "InterativeSolver.Tolerance" becomes "Tolerance" and a label "Basis.Degree" is ignored.

const index_t & getInt ( const std::string & label ) const

inherited

Reads value for option label from options.

If label is not found, the function throws.

std::vector< index_t > getMultiInt ( const std::string & gn ) const

inherited

Reads values of an option-group gn into a std::vector.

If gn is not found, the function throws.

std::vector< gsOptionList::Real > getMultiReal ( const std::string & gn ) const

inherited

Reads values of an option-group gn into a std::vector.

If gn is not found, the function throws.

std::vector< std::string > getMultiString ( const std::string & gn ) const

inherited

Reads values of an option-group gn into a std::vector.

If gn is not found, the function throws.

gsOptionList::Real getReal ( const std::string & label ) const

inherited

Reads value for option label from options.

If label is not found, the function throws.

std::string getString ( const std::string & label ) const

inherited

Reads value for option label from options.

If label is not found, the function throws.

bool getSwitch ( const std::string & label ) const

inherited

Reads value for option label from options.

If label is not found, the function throws.

void getValues	(	int	argc,
		char *	argv[]
	)

Parses the command line based on the specified parameters.

The specification has to be done using addInt, addMultiInt, addReal, addMultiReal, addString, addMultiString, addSwitch and addPlainString before calling this member function.

The parameters argc and argv are those of the main function.

If the parsing did non succeed, the function throws.

bool hasGlobals ( ) const

inherited

Checks if there are labels that do not belong to a group.

This is the case if there is a label which does not contain a dot.

bool hasGroup ( const std::string & gn ) const

inherited

Checks if there are labels that belong to the group gn.

This is the case if there is a label which starts with the groupname and a dot.

void setInt	(	const std::string &	label,
		const index_t &	value
	)

inherited

Sets an existing option label to be equal to value.

If label is not found, the function throws.

void setReal	(	const std::string &	label,
		const Real &	value
	)

inherited

Sets an existing option label to be equal to value.

If label is not found, the function throws.

void setString	(	const std::string &	label,
		const std::string &	value
	)

inherited

Sets an existing option label to be equal to value.

If label is not found, the function throws.

void setSwitch	(	const std::string &	label,
		const bool &	value
	)

inherited

Sets an existing option label to be equal to value.

If label is not found, the function throws.

void update	(	const gsOptionList &	other,
		gsOptionList::updateType	type = `ignoreIfUnknown`
	)

inherited

Updates the object using the data from other.

Options which do not exist in other, are kept unchanged. Options in other which do not exist in this, are kept unchanged if type is set to gsOptionList::ignoreIfUnknown (default) or are added if type is set to gsOptionList::addIfUnknown.

void updateOptionList ( )

private

Writes all given options (as specified by addInt, addReal, addString or addSwitch or addPlainString) into the gsOptionList base object.

bool valid	(	int	argc,
		char *	argv[]
	)		const

Parses the command line and returns true iff everything is okey. This function should be called after the parameters have been registered.

If the user has invoked –help or –version, the result is true.

gsOptionList wrapIntoGroup ( const std::string & gn ) const

inherited

Creates a new gsOptionList where all labels are wrapped into a groupname gn.

Wrapping means that the label is prepended with the groupname and a dot. So, the label "Tolerance" wrapped into the group "IterativeSolver" is "InterativeSolver.Tolerance"

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Constructor & Destructor Documentation

Member Function Documentation