A parser for command line arguments. More...

#include <bpscmdlineparser.h>

Inheritance diagram for BpsCmdlineParser:

Public Slots
BpsCmdlineParser &	addHelpSwitch (QChar aKey, const QString &aName, const QString &aInfo)
	Adds a help-type switch with either a single character key and / or a key name. More...

BpsCmdlineParser &	addMandatory (const QString &aParam)
	Add a mandatory parameter. More...

BpsCmdlineParser &	addOption (QChar aKey, const QString &aName, const QString &aParam, const QString &aInfo)
	Adds a option with either a single character key and / or a key name. More...

BpsCmdlineParser &	addOptional (const QString &aParam)
	Add a single optional parameter. More...

BpsCmdlineParser &	addOptionals (const QString &aParam)
	Add a multiple optional parameter. More...

BpsCmdlineParser &	addOptions (QChar aKey, const QString &aName, const QString &aParam, const QString &aInfo)
	Adds a option that can occure multiple times with either a single character key and / or a key name. More...

BpsCmdlineParser &	addSwitch (QChar aKey, const QString &aName, const QString &aInfo)
	Adds a switch with either a single character key and / or a key name. More...

QString	help (int aWidth=79) const
	Formats a help message for the command line parser. More...

QString	mandatory (const QString &aParam) const
	Query a mandatory parameter after parsing the arguments. More...

QString	option (QChar aKey, const QString &aName=QString()) const
	Query an option value after parsing the arguments. More...

QString	optional (const QString &aParam) const
	Query an optional single parameter after parsing the arguments. More...

QStringList	optionals () const
	Query the multiple optional parameter after parsing the arguments. More...

QStringList	options (QChar aKey, const QString &aName=QString()) const
	Query options values after parsing the arguments. More...

BpsCmdlineParser &	parse ()
	Parses the command line. More...

QString	program () const
	Query the invoked program after parsing the arguments. More...

BpsCmdlineParser &	setDescription (const QString &aDescription)
	Set the description what the program is supposed to do. More...

BpsCmdlineParser &	setProgram (const QString &aName)
	Set the program name used by the help() funcion. More...

bool	switchState (QChar aKey, const QString &aName=QString()) const
	Query a switch after parsing the arguments. More...

Public Member Functions
	BpsCmdlineParser (QObject *aParent=nullptr)
	Default constructor for the BpsCmdlineParser class. More...

Public Member Functions inherited from QObject
bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo ()

void	dumpObjectInfo () const const

void	dumpObjectTree ()

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_DISABLE_COPY (Class)

	Q_DISABLE_COPY_MOVE (Class)

	Q_DISABLE_MOVE (Class)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qFindChild (const QObject *obj, const QString &name)

QList< T >	qFindChildren (const QObject *obj, const QRegExp &regExp)

QList< T >	qFindChildren (const QObject *obj, const QString &name)

	QObject (QObject *parent)

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Detailed Description

A parser for command line arguments.

Specify the command line syntax with a minimum of statements in a readable way, check it against the actual command line arguments and find the retrieved values.

A command line that a user might have entered is:

foobar testjob -v --config=my.cnf -wall input.dat

The typical usage has three stages:

Construct a parser specifying what arguments to parse
Run the parser
Query the parsed arguments

For the first step setting up the accepted syntax is done by a set of functions like setDescription() and addSwitch(). The final step of running the parser is simply done by calling parse().

A short example implementing a parser for the sample above:

int main(int argc, char **argv)
{
    QCoreApplication a(argc, argv);
    try {
        BpsCmdlineParser cp;
        cp
            .setDescription(
                "This program does not do very much at all. It is simply a "
                "sample to show how command line parsing is working. Enter "
                "a JOBNAME to identify the job and a FILENAME where the data "
                "is stored.\n"
                "\n"
                "NOTES: \n"
                " - If FILENAME has no extension, .dat will be assumed.\n"
                " - JOBNAME and FILENAME must not contain any whitespaces."
             )
            .setProgram("foobar")
            .addMandatory("JOBNAME")
            .addOptional("FILENAME")
            .addHelpSwitch('h', QString(), "Show help.")
            .addSwitch('v', "verbose", "Write status information to stdout.")
            .addOption(0, "config", "CFGFILE",
                       "Provide configuration file. If none provided, "
                       "the system configuration file will be used.")
            .addOption('w', QString(), "LEVEL", "Warning level: 'all', 'min', 'none'")
            .parse();
        if (cp.switchState('h', QString()) {
            cout << cp.help();
        } else {
            QString job(cp.mandatory("JOBNAME"));
            // ....
        } // if
    }
    catch (const BpsException& exc) {
        cerr << "Error: " << exc.message() << endl
             << "Use 'foobar -h' for help." << endl;
    }
}

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

Mandatory A mandatory parameter is a plain text token like e.g. a file name one typically passes to an editor when invoking it.
Optional A optional parameter is also a plain text token, however as it is optional no error will happen when parsing and no such argument is present.
Optionals Optionals is an arbitrary number of parameters. Note that everything not matching any other topic will be added to the Optionals. Only one Optionals can be present.
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
Options Options is an arbitraty number of argument with a key-value syntax like –expression="e/foo/bar/g" or -ee/foo/bar/i

Constructor & Destructor Documentation

◆ BpsCmdlineParser()

BpsCmdlineParser::BpsCmdlineParser ( QObject * aParent = nullptr )

Default constructor for the BpsCmdlineParser class.

Parameters

aParent Pointer to parent QObject.

Member Function Documentation

◆ addHelpSwitch

BpsCmdlineParser& BpsCmdlineParser::addHelpSwitch	(	QChar	aKey,
		const QString &	aName,
		const QString &	aInfo
	)

slot

Adds a help-type switch with either a single character key and / or a key name.

When this switch is found while parsing the arguments, the parsing will stop no check for missing mandatory parameters will be done.

Parameters

aKey	The single character key. Enter 0 for none.
aName	The name key. Enter an emtpy string for none.
aInfo	A descriptive text for the switch to be displayed by the help() function. Paragraphs can be separated by a newline character. Running text in paragraphs is word-wrapped to the available line length, except for paragraphs starting with a blank which are output as-is for preformated text.

Returns: A reference to the current command line parser for convenience.

◆ addMandatory

BpsCmdlineParser& BpsCmdlineParser::addMandatory ( const QString & aParam )

slot

Add a mandatory parameter.

An arbitrary number of mandatory parameters may be added. When parsing the arguments, the mandatory parameters will be served before any optional parameters, and in the order they were added.

Parameters

aParam Name of the parameter. By convention this should be all uppercase. The name will be used again when querying the parse results later with mandatory().

Returns: A reference to the current command line parser for convenience.

◆ addOption

BpsCmdlineParser& BpsCmdlineParser::addOption	(	QChar	aKey,
		const QString &	aName,
		const QString &	aParam,
		const QString &	aInfo
	)

slot

Adds a option with either a single character key and / or a key name.

Parameters

aKey	The single character key. Enter 0 for none.
aName	The name key. Enter an emtpy string for none.
aParam	A parameter name. By convention this should be all uppercase.
aInfo	A descriptive text for the option to be displayed by the help() function. Paragraphs can be separated by a newline character. Running text in paragraphs is word-wrapped to the available line length, except for paragraphs starting with a blank which are output as-is for preformated text.

Returns: A reference to the current command line parser for convenience.

◆ addOptional

BpsCmdlineParser& BpsCmdlineParser::addOptional ( const QString & aParam )

slot

Add a single optional parameter.

An arbitrary number of single optional parameters may be added. When parsing the arguments, the single optional parameters will be served after the mandatory parameters, but before the multiple optional parameter, and in the order they were added.

Parameters

aParam Name of the parameter. By convention this should be all uppercase. The name will be used again when querying the parse results later with optional().

Returns: A reference to the current command line parser for convenience.

◆ addOptionals

BpsCmdlineParser& BpsCmdlineParser::addOptionals ( const QString & aParam )

slot

Add a multiple optional parameter.

Only one multiple optional parameter may be added. When parsing the arguments, the multiple optional parameter will be served after the mandatory and after the single optional parameters.

Parameters

aParam Name of the parameter. By convention this should be all uppercase. Enter an empty string if you want an invisible multi-optional parameter to silently eat up all supernumerary tokens.

Returns: A reference to the current command line parser for convenience.

◆ addOptions

BpsCmdlineParser& BpsCmdlineParser::addOptions	(	QChar	aKey,
		const QString &	aName,
		const QString &	aParam,
		const QString &	aInfo
	)

slot

Adds a option that can occure multiple times with either a single character key and / or a key name.

Parameters

aKey	The single character key. Enter 0 for none.
aName	The name key. Enter an emtpy string for none.
aParam	A parameter name. By convention this should be all uppercase.
aInfo	A descriptive text for the option to be displayed by the help() function. Paragraphs can be separated by a newline character. Running text in paragraphs is word-wrapped to the available line length, except for paragraphs starting with a blank which are output as-is for preformated text.

Returns: A reference to the current command line parser for convenience.

◆ addSwitch

BpsCmdlineParser& BpsCmdlineParser::addSwitch	(	QChar	aKey,
		const QString &	aName,
		const QString &	aInfo
	)

slot

Adds a switch with either a single character key and / or a key name.

Parameters

aKey	The single character key. Enter 0 for none.
aName	The name key. Enter an emtpy string for none.
aInfo	A descriptive text for the switch to be displayed by the help() function. Paragraphs can be separated by a newline character. Running text in paragraphs is word-wrapped to the available line length, except for paragraphs starting with a blank which are output as-is for preformated text.

Returns: A reference to the current command line parser for convenience.

◆ help

QString BpsCmdlineParser::help ( int aWidth = 79 ) const

slot

Formats a help message for the command line parser.

The message format is similar to the man pages on unix based operating systems:

SYNOPSYS

    foobar JOBNAME [FILENAME] [OPTION]...

DESCRIPTION

    This program does not do very much at all. It is simply a sample to show
    how command line parsing is working. Enter a JOBNAME to identify the job
    and a FILENAME where the data is stored.

    NOTES:
     -If FILENAME has no extension, .dat will be assumed.
     -JOBNAME and FILENAME must not contain any whitespaces.

OPTIONS

    -h
        Show help.

    -v, --verbose
        Write status information to stdout.

    --config=CFGFILE
        Provide configuration file. If none provided, the system configuration
        file will be used.

    -w LEVEL
        Warning level: 'all', 'min', 'none'

Parameters

aWidth The maximum width of the message. Default is 79.

Returns: The formatted help message.

◆ mandatory

QString BpsCmdlineParser::mandatory ( const QString & aParam ) const

slot

Query a mandatory parameter after parsing the arguments.

Parameters

aParam The name of the parameter, exactly as defined with addMandatory().

Returns: The argument matching this mandatory parameter.

◆ option

QString BpsCmdlineParser::option	(	QChar	aKey,
		const QString &	aName = `QString()`
	)		const

slot

Query an option value after parsing the arguments.

Parameters

aKey	The single character key, exactly as defined with addOption().
aName	The name key, exactly as defined with addOption().

Returns: The argument matching this option. Returns an empty string in case none was provided in the arguments.

◆ optional

QString BpsCmdlineParser::optional ( const QString & aParam ) const

slot

Query an optional single parameter after parsing the arguments.

Parameters

aParam The name of the parameter, exactly as defined with addOptional().

Returns: The argument matching this single optional parameter. Returns an empty string in case none was provided in the arguments.

◆ optionals

QStringList BpsCmdlineParser::optionals ( ) const

slot

Query the multiple optional parameter after parsing the arguments.

Returns: The argument list matching the multiple optional parameter. Returns an empty list in case none was provided in the arguments.

◆ options

QStringList BpsCmdlineParser::options	(	QChar	aKey,
		const QString &	aName = `QString()`
	)		const

slot

Query options values after parsing the arguments.

Parameters

aKey	The single character key, exactly as defined with addOptions().
aName	The name key, exactly as defined with addOptions().

Returns: The list of arguments matching this options. Returns an empty list in case none were provided in the arguments.

◆ parse

BpsCmdlineParser& BpsCmdlineParser::parse ( )

slot

Parses the command line.

In case of errors, a BpsException will be thrown. After parsing, the results can be collected by the functions program(), mandatory(), optional(), optionals(), switchState() and option().

Returns: A reference to the current command line parser for convenience.

◆ program

QString BpsCmdlineParser::program ( ) const

slot

Query the invoked program after parsing the arguments.

Returns: The full path of the invoked program.

◆ setDescription

BpsCmdlineParser& BpsCmdlineParser::setDescription ( const QString & aDescription )

slot

Set the description what the program is supposed to do.

You should also explain the parameters added by addMandatory(), addOptional() and addOptionals() in this description. By convention the names of those parameters are written in all uppercase.

Paragraphs can be separated by a newline character. Running text in paragraphs is word-wrapped to the available line length, except for paragraphs starting with a blank which are output as-is to enable preformating.

Parameters

aDescription The description to set.

Returns: A reference to the current command line parser for convenience.

◆ setProgram

BpsCmdlineParser& BpsCmdlineParser::setProgram ( const QString & aName )

slot

Set the program name used by the help() funcion.

Parameters

aName The program name to set.

Returns: A reference to the current command line parser for convenience.

◆ switchState

bool BpsCmdlineParser::switchState	(	QChar	aKey,
		const QString &	aName = `QString()`
	)		const

slot

Query a switch after parsing the arguments.

Parameters

aKey	The single character key, exactly as defined with addSwitch().
aName	The name key, exactly as defined with addSwitch().

Returns: True if the switch was found in the arguments, otherwise false.

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

bpscmdlineparser.h

Public Slots

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BpsCmdlineParser()

Member Function Documentation

◆ addHelpSwitch

◆ addMandatory

◆ addOption

◆ addOptional

◆ addOptionals

◆ addOptions

◆ addSwitch

◆ help

◆ mandatory

◆ option

◆ optional

◆ optionals

◆ options

◆ parse

◆ program

◆ setDescription

◆ setProgram

◆ switchState