BpsCmdlineParser Class Reference

A parser for command line arguments. More...

#include <bpscmdlineparser.h>

List of all members.

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.
BpsCmdlineParser &	addMandatory (const QString &aParam)
	Add a mandatory parameter.
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.
BpsCmdlineParser &	addOptional (const QString &aParam)
	Add a single optional parameter.
BpsCmdlineParser &	addOptionals (const QString &aParam)
	Add a multiple optional parameter.
BpsCmdlineParser &	addSwitch (QChar aKey, const QString &aName, const QString &aInfo)
	Adds a switch with either a single character key and / or a key name.
QString	help (int aWidth=79) const
	Formats a help message for the command line parser.
QString	mandatory (const QString &aParam) const
	Query a mandatory parameter after parsing the arguments.
QString	option (QChar aKey, const QString &aName=QString()) const
	Query an option value after parsing the arguments.
QString	optional (const QString &aParam) const
	Query an optional single parameter after parsing the arguments.
QStringList	optionals () const
	Query the multiple optional parameter after parsing the arguments.
BpsCmdlineParser &	parse ()
	Parses the command line.
QString	program () const
	Query the invoked program after parsing the arguments.
BpsCmdlineParser &	setDescription (const QString &aDescription)
	Set the description what the program is supposed to do.
BpsCmdlineParser &	setProgram (const QString &aName)
	Set the program name used by the help() funcion.
bool	switchState (QChar aKey, const QString &aName=QString()) const
	Query a switch after parsing the arguments.
Public Member Functions
	BpsCmdlineParser (QObject *aParent=0)
	Default constructor for the BpsCmdlineParser class.

---

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:

1. Construct a parser specifying what arguments to parse
2. Run the parser
3. 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 (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.

---

Constructor & Destructor Documentation

BpsCmdlineParser::BpsCmdlineParser

(

QObject *

aParent = 0

)

Default constructor for the BpsCmdlineParser class.

Parameters:

[in]

aParent

Pointer to parent QObject.

---

Member Function Documentation

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:

[in]	aKey	The single character key. Enter 0 for none.
[in]	aName	The name key. Enter an emtpy string for none.
[in]	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.

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:

[in]

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.

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:

[in]	aKey	The single character key. Enter 0 for none.
[in]	aName	The name key. Enter an emtpy string for none.
[in]	aParam	A parameter name. By convention this should be all uppercase.
[in]	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.

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:

[in]

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.

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:

[in]

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.

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:

[in]	aKey	The single character key. Enter 0 for none.
[in]	aName	The name key. Enter an emtpy string for none.
[in]	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.

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:

[in]

aWidth

The maximum width of the message. Default is 79.

Returns:

The formatted help message.

QString BpsCmdlineParser::mandatory

(

const QString &

aParam

)

const [slot]

Query a mandatory parameter after parsing the arguments.

Parameters:

[in]

aParam

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

Returns:

The argument matching this mandatory parameter.

QString BpsCmdlineParser::option	(	QChar	aKey,
		const QString &	aName = QString()
	)		const [slot]

Query an option value after parsing the arguments.

Parameters:

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

Returns:

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

QString BpsCmdlineParser::optional

(

const QString &

aParam

)

const [slot]

Query an optional single parameter after parsing the arguments.

Parameters:

[in]

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.

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.

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.

QString BpsCmdlineParser::program

(

)

const [slot]

Query the invoked program after parsing the arguments.

Returns:

The full path of the invoked program.

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:

[in]

aDescription

The description to set.

Returns:

A reference to the current command line parser for convenience.

BpsCmdlineParser& BpsCmdlineParser::setProgram

(

const QString &

aName

)

[slot]

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

Parameters:

[in]

aName

The program name to set.

Returns:

A reference to the current command line parser for convenience.

bool BpsCmdlineParser::switchState	(	QChar	aKey,
		const QString &	aName = QString()
	)		const [slot]

Query a switch after parsing the arguments.

Parameters:

[in]	aKey	The single character key, exactly as defined with addSwitch().
[in]	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