ArgumentsParser Class Reference

Abstract base class for dealing with command line arguments. More...

#include <Workspace/Application/argumentsparser.h>

Inheritance diagram for ArgumentsParser:

Public Member Functions
	ArgumentsParser (ArgumentsParser &&args)
	ArgumentsParser (const ArgumentsParser &args)
	ArgumentsParser (const QStringList &expectedArguments=QStringList(), const QString &usageHeader="")
virtual	~ArgumentsParser ()
QString	argument (int index) const
bool	flagExists (const QString &name) const
int	flagOccurrence (const QString &name) const
QString	flagParameter (const QString &name, int paramIndex, int occurrence=0) const
QStringList	flagParameters (const QString &name, int occurrence=0) const
const QStringList &	getArguments () const
int	numArguments () const
ArgumentsParser &	operator= (ArgumentsParser args)
bool	parse (const QStringList &arguments, int &exitCode)
virtual QString	usage () const

Static Public Member Functions
static bool	parseBoolean (const QString &s)
static bool	validBoolean (const QString &s)

Protected Member Functions
void	addSupportedFlag (const QString &name, const QString &description, int numParameters=0, const QStringList &paramNames=QStringList(), bool developOnly=false)
void	logError (const QString &msg)
void	purgeArgument (int index)
void	purgeFlag (const QString &name, int occurrence=0)
virtual bool	validate (int &exitCode)

Detailed Description

Derived classes should use addSupportedFlag() during construction to specify the flags and flag parameter counts they expect.

When a user calls parse() for a given set of arguments any argument prefixed with "--" is checked against the supported flags and the appropriate number of parameters are stored. The derived class is expected to expose these flags through it's own new methods that can call the protected flagExists() and flagParameters() methods on the base class. If while reading in the expected number of parameters for a supported flag we encounter a new flag ('–' prefix) we stop reading parameters even if more are expected and interpret this value as a new flag.

Derived classes must also implement validate() which will be called by parse() after it has parsed all the arguments - allowing the derived class to confirm that the parsed arguments are valid. During validate() derived classes can call logError() and return false if problems are detected.

If any arguments are encountered during parse() which have not been specified by addSupportedFlag(), they are made available directly to the user via numArguments() and argument(index).

Note

If an argument is encountered with a '–' prefix that is not listed as a supported flag, it is added to the arguments list instead and will still include the '–' prefix. A derived class could potentially check the arguments list for any argument starting with '–' in its validate() function if it didn't want to allow this behaviour.

See WorkspaceArgumentParser for an example derived class.

Constructor & Destructor Documentation

ArgumentsParser() [1/3]

ArgumentsParser	(	const QStringList &	expectedArguments = QStringList(),
		const QString &	usageHeader = ""
	)

Parameters

expectedArguments	A list of names for the expected arguments of this application.
usageHeader	A header for the usage message. If this is an empty string, the constructor will attempt to create a default header based on the application name and version as obtained from QCoreApplication.

The constructor always adds the help flag. If the application version has also been set by a call to QCoreApplication::setApplicationVersion(), then a version flag will also be automatically added by this constructor. Note that the version must be set before the arguments parser object is created or else the version flag will not be added automatically.

ArgumentsParser() [2/3]

ArgumentsParser

(

const ArgumentsParser &

args

)

ArgumentsParser() [3/3]

ArgumentsParser

(

ArgumentsParser &&

args

)

~ArgumentsParser()

~ArgumentsParser ( )

virtualdefault

Member Function Documentation

addSupportedFlag()

void addSupportedFlag ( const QString &  name, const QString &  description, int  numParameters = 0, const QStringList &  paramNames = QStringList(), bool  developOnly = false  )

protected

Derived classes should call this function during construction to specify all the flags they support along with the number of parameters expected for each of then.

argument()

QString argument

(

int

index

)

const

Parameters

index

Specifies which non-flag argument to retrieve. Arguments are indexed in the order they were specified on the command line, with the first non-flag argument having an index of zero.

Returns

The argument at the specified index, or an empty string if there are no arguments or if index is not valid.

See also

numArguments(), getArguments()

flagExists()

bool flagExists

(

const QString &

name

)

const

Returns

True if the flag with the given name has been parsed.

flagOccurrence()

int flagOccurrence

(

const QString &

name

)

const

Returns

The number of times a flag was parsed.

flagParameter()

QString flagParameter	(	const QString &	name,
		int	paramIndex,
		int	occurrence = 0
	)		const

Returns

The paramIndex(th) parameter parsed for the given flag names occurrence.

flagParameters()

QStringList flagParameters	(	const QString &	name,
		int	occurrence = 0
	)		const

Returns

The parameters parsed for the given flag names occurrence.

getArguments()

const QStringList & getArguments

(

)

const

Returns

The list of non-flag arguments.

See also

argument(), numArguments()

logError()

void logError ( const QString &  msg )

protected

This is a convenience only. It simply prepends msg with an appropriate prefix denoting the text as an error (eg "ERROR: " for English languages) and also appends a new line character. The whole lot is then passed to LogManager::logText() to send it to the main log, which is typically just stdout.

numArguments()

int numArguments

(

)

const

Returns

The number of non-flag arguments.

See also

argument(), getArguments()

operator=()

ArgumentsParser & operator=

(

ArgumentsParser

args

)

parse()

bool parse	(	const QStringList &	arguments,
		int &	exitCode
	)

Parameters

arguments	The command line arguments supplied to the application. This would normally be the same as those passed to the QCoreApplication constructor or simply be the result of calling QCoreApplication::arguments().
exitCode	Subclasses can set this to a non-zero value in their validate() function to indicate some specific validation error. When parse() returns, if exitCode is non-zero, its value should be used as the exit code of the application.

This function parses the command line in arguments and populates the internal data structures for the supported flags, etc. It must be called before any of the query methods. Unless one of the standard options –version or –help is present, parse() will call validate() as the last thing it does. If one of the standard options is present, then exitCode() will have the value of zero upon return and the function will return false to indicate that the application should terminate.

Returns

True if the arguments were parsed successfully and the application should be allowed to continue. If the return value is false, the caller should ensure the application is terminated after parse() returns. Note that parse() can return false even if there is no error parsing arguments, such as when an argument like –version or –help is present. In order to distinguish between an error and one of these such arguments, the exitCode can be inspected. If exitCode is zero, the caller can assume there was no error in the arguments. Subclasses should ensure they obey this rule.

parseBoolean()

bool parseBoolean ( const QString &  s )

static

purgeArgument()

void purgeArgument ( int  index )

protected

Derived classed can call this function to remove the given non-flag argument.

purgeFlag()

void purgeFlag ( const QString &  name, int  occurrence = 0  )

protected

Derived class can call this function to remove the given flags.

usage()

QString usage ( ) const

virtual

Returns

A QString explaining the usage of this application. The base implementation constructs a message based on the values set with setUsageHeader() and addSupportedFlag() however derived classes may implement a custom message.

validate()

bool validate ( int &  exitCode )

protectedvirtual

Reimplemented in WorkflowAnalyseBatchArgumentsParser, OOPScheduleeArgumentsParser, and WorkspaceArgumentsParser.

validBoolean()

bool validBoolean ( const QString &  s )

static