A command line option parser. More...

Public Member Functions
	OptionParser ()
	Constructs a command line parser from the arguments stored in a previously created QApplication instance.

	OptionParser (int argc, char *argv[])

	OptionParser (const QStringList &a)

	OptionParser (int offset)

void	addArgument (const QString &name, QString *v)

void	addOption (char s, const QString &l, QString *v)

void	addOptionalArgument (const QString &name, QString *v)

void	addOptionalOption (const QString &l, QString *v, const QString &def)

void	addOptionalOption (char s, const QString &l, QString *v, const QString &def)

void	addRepeatableOption (char s, QStringList *v)

void	addRepeatableOption (const QString &l, QStringList *v)

void	addSwitch (const QString &lname, bool *b)

void	addVarLengthOption (const QString &l, QStringList *v)

QString	appName () const
	Boo.

int	currentArgument () const

bool	isSet (const QString &name) const

bool	parse (bool untilFirstSwitchOnly)

bool	parse ()

Friends
struct	Option

Detailed Description

A command line option parser.

This class is based on GetOpt class implemented by froglogic GbR (conta.nosp@m.ct@f.nosp@m.roglo.nosp@m.gic..nosp@m.com).
This class helps to overcome the repetitive, tedious and error-prone task of parsing the command line options passed to your application by the user. Specify the acceptable syntax with a minimum of statements in a readable way, check it against the actual arguments passed and find the retrieved values in variables of your program.

A command line that a user might have entered is:

app -v --config=my.cnf -Wall input.dat

The typical usage has three stages:

Construct a parser specifying what arguments to parse
Set up the list of allowed and required options
Run the parser

For the first step there are three different constructors that either take arguments directly from main(), QApplication or a user specified list. Setting up the accepted syntax is done by a set of add functions like addSwitch(). The final step of running the parser is simply done by calling parse().

A short example implementing a –verbose switch:

int main(int argc, char **argv)
{
    OptionParser opts(argc, argv);
    bool verbose;
    opts.addSwitch("verbose", &verbose);
    if (!opts.parse())
        return 1;
    if (verbose)
        cout << "VERBOSE mode on" << endl;
    ...

For a better understanding of the function names we'll better define some terms used in the API and its documentation:

Argument An argument is a plain text token like e.g. a file name one typically passes to an editor when invoking it.
Switch A switch is an on/off kind of argument without the need of additional information. Example: –debug.
Option An option is a normally optional argument with a key-value syntax like –output=out.txt or -I/usr/include.
Short Option A short option is a one letter option with a preceding dash. Like -v.
Long Option A long option has a more verbose, multi-letter name like –debug.

Author: froglogic GbR (GetOpt class)conta.nosp@m.ct@f.nosp@m.roglo.nosp@m.gic..nosp@m.com; G. Massera (this modified and QT4 complaint version)

Definition at line 92 of file optionparser.h.

Constructor & Destructor Documentation

OptionParser ( )

Constructs a command line parser from the arguments stored in a previously created QApplication instance.

Example usage:

QApplication a(argc, argv);
OptionParser opt;

This constructor is probably the most convenient one to use in a regular Qt application. Note that QApplication may already have removed Qt (or X11) specific arguments. Also see QApplication::argv() and QApplication::argc().

Definition at line 33 of file optionparser.cpp.

OptionParser	(	int	argc,
		char *	argv[]
	)

Construct a command line parser from the array argv of string pointers with the size argc. Those parameters have the form typically found in the main() function. That means that you can simply pass on the arguments specified by the user of your application.

Example usage:

int main(int argc, char **argv) {
    OptionParser opt(argc, argv);
    ...
}

Definition at line 49 of file optionparser.cpp.

OptionParser ( const QStringList & a )

Construct a command line parser from the arguments specified in the list of arguments a. This constructor is convenient in those cases where you want to parse a command line assembled on-the-fly instead of relying on the argc and arg parameters passed to the main() function.

Definition at line 53 of file optionparser.cpp.

Member Function Documentation

void addArgument	(	const QString &	name,
		QString *	v
	)

Registers a required command line argument name. If the argument is missing parse() will return false to indicate an error and *v will remain with its default QString::null value. Otherwise *v will be set to the value of the argument.

Example:

To accept simple arguments like

myeditor letter.txt

use a call like:

QString &file;

opt.addArgument("file", &file);

Note: the name parameter has a rather descriptive meaning for now. It might be used for generating a usage or error message in the future. Right now, the only current use is in relation with the isSet() function.

Definition at line 343 of file optionparser.cpp.

void addOption	(	char	s,
		const QString &	l,
		QString *	v
	)

Registers an option with the short name s and long name l to the parser. If this option is found during parsing the value will be stored in the string pointed to by v. By default *v will be initialized to QString::null.

Definition at line 303 of file optionparser.cpp.

Referenced by OptionParser::addOptionalOption(), OptionParser::addRepeatableOption(), OptionParser::addSwitch(), and OptionParser::addVarLengthOption().

void addOptionalArgument	(	const QString &	name,
		QString *	v
	)

Registers an optional command line argument name. For a more detailed description see the addArgument() documentation.

Definition at line 351 of file optionparser.cpp.

void addOptionalOption	(	const QString &	l,
		QString *	v,
		const QString &	def
	)

Adds a long option l that has an optional value parameter. If the value is not specified by the user it will be set to def.

Example:

OptionParser opt;
QString file;
opt.addOptionalOption("dump", &file, "<stdout>");

See Also: addOption

Definition at line 331 of file optionparser.cpp.

void addOptionalOption	(	char	s,
		const QString &	l,
		QString *	v,
		const QString &	def
	)

Adds a short option s that has an optional value parameter. If the value is not specified by the user it will be set to def.

Definition at line 335 of file optionparser.cpp.

References OptionParser::addOption().

void addRepeatableOption	(	char	s,
		QStringList *	v
	)

Registers an option with the short name s that can be specified repeatedly in the command line. The option values will be stored in the list pointed to by v. If no s option is found *v will remain at its default value of an empty QStringList instance.

Example:

To parse the -I options in a command line like

myapp -I/usr/include -I/usr/local/include

you can use code like this:

OptionParser opt;
QStringList includes;
opt.addRepeatableOption('I', &includes);
opt.parse();

Definition at line 317 of file optionparser.cpp.

References OptionParser::addOption().

void addRepeatableOption	(	const QString &	l,
		QStringList *	v
	)

Registers an option with the long name l that can be specified repeatedly in the command line.

See Also: addRepeatableOption( char, QStringList* )

Definition at line 324 of file optionparser.cpp.

References OptionParser::addOption().

void addSwitch	(	const QString &	lname,
		bool *	b
	)

Adds a switch with the long name lname. If the switch is found during parsing the bool *b will bet set to true. Otherwise the bool will be initialized to false.

Example:

OptionParser opt;
bool verbose;
opt.addSwitch("verbose", &verbose);

The boolean flag verbose will be set to true if –verbose has been specified in the command line; false otherwise.

Definition at line 290 of file optionparser.cpp.

References OptionParser::addOption().

void addVarLengthOption	(	const QString &	l,
		QStringList *	v
	)

Registers a long option l that can have a variable number of corresponding value parameters. As there currently is no way to tell the end of the value list the only sensible use of this option is at the end of the command line.

Example:

QStringList args;

opt.addVarLengthOption("exec", &args);

Above code will lead to "-f" and "test.txt" being stored in args upon

myapp --exec otherapp -f test.txt

Definition at line 310 of file optionparser.cpp.

References OptionParser::addOption().

QString appName ( ) const

inline

Boo.

Definition at line 142 of file optionparser.h.

bool isSet ( const QString & name ) const

Returns true if the (long) option or switch name has been found in the command line; returns false otherwise. Leading hyphens are not part of the name.

As the set/not set decision can also be made depending on the value of the variable reference used in the respective add*() call there's generally little use for this function.

Definition at line 360 of file optionparser.cpp.

bool parse ( )

inline

Parse the command line arguments specified in the constructor under the conditions set by the various add*() functions. On success, the given variable reference will be initialized with their respective values and true will be returned. Returns false otherwise.

In the future there'll be a way to retrieve an error message. In the current version the message will be printed to stderr.

Definition at line 294 of file optionparser.h.

References OptionParser::parse().

Referenced by OptionParser::parse().

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

utilities/include/optionparser.h
utilities/src/optionparser.cpp

Utilities - 1.2.3

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation