bps::CmdlineParser Class Reference

A parser for command line arguments. More...

Public Member Functions
void	addHelpSwitch (String aKey, String aName, String aInfo)
	Adds a help-type switch with either a single character key and / or a key name. More...
void	addMandatory (String aName)
	Add a mandatory parameter. More...
void	addOption (String aKey, String aName, String aParam, String aInfo)
	Adds a option with either a single character key and / or a key name. More...
void	addOptional (String aName)
	Add a single optional parameter. More...
void	addOptionals (String aName)
	Add a multiple optional parameter. More...
void	addSwitch (String aKey, String aName, String aInfo)
	Adds a switch with either a single character key and / or a key name. More...
	CmdlineParser ()
	The constructor.
QString	help (Number aWidth)
	Formats a help message for the command line parser. More...
String	mandatory (String aParam)
	Query a mandatory parameter after parsing the arguments. More...
String	option (String aKey, String aName)
	Query an option value after parsing the arguments. More...
String	optional (String aParam)
	Query an optional single parameter after parsing the arguments. More...
Array	optionals ()
	Query the multiple optional parameter after parsing the arguments. More...
void	parse ()
	Parses the command line. More...
String	program ()
	Query the invoked program after parsing the arguments. More...
void	setDescription (String aDescription)
	Set the description what the program is supposed to do. More...
void	setProgram (String aName)
	Set the program name used by the help() funcion. More...
Boolean	switchState (String aKey, String aName)
	Query a switch after parsing the arguments. More...

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:

try {
    var clp = new bps.CmdlineParser;
    with (clp) {
        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("bps");
        addMandatory("test.js");
        addMandatory("JOBNAME");
        addOptional("FILENAME");
        addHelpSwitch('h','help','Show help (this).');
        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', '', "LEVEL", "Warning level: 'all', 'min', 'none'");
        parse();
        if (switchState('h'))
            log(help());
        else {
            var job = mandatory("JOBNAME");
            log('job = '+job);
            // .....
        } // else
    } // with
} // try
catch (err) {
    throw new Error(err+"\nUse 'bps test -h' for help.");
} // catch

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.

Member Function Documentation

addHelpSwitch()

void bps::CmdlineParser::addHelpSwitch	(	String	aKey,
		String	aName,
		String	aInfo
	)

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 empty 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.

addMandatory()

void bps::CmdlineParser::addMandatory

(

String

aName

)

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

aName

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().

addOption()

void bps::CmdlineParser::addOption	(	String	aKey,
		String	aName,
		String	aParam,
		String	aInfo
	)

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 empty string for none.
aParam	A parameter name.
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.

addOptional()

void bps::CmdlineParser::addOptional

(

String

aName

)

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

aName

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().

addOptionals()

void bps::CmdlineParser::addOptionals

(

String

aName

)

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

aName

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.

addSwitch()

void bps::CmdlineParser::addSwitch	(	String	aKey,
		String	aName,
		String	aInfo
	)

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 empty 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.

help()

QString bps::CmdlineParser::help

(

Number

aWidth

)

Formats a help message for the command line parser.

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

SYNOPSYS
 
    bps test.js 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, --help
        Show help (this).
 
    -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()

String bps::CmdlineParser::mandatory

(

String

aParam

)

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()

String bps::CmdlineParser::option	(	String	aKey,
		String	aName
	)

Query an option value 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

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

optional()

String bps::CmdlineParser::optional

(

String

aParam

)

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()

Array bps::CmdlineParser::optionals

(

)

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.

parse()

void bps::CmdlineParser::parse

(

)

Parses the command line.

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

program()

String bps::CmdlineParser::program

(

)

Query the invoked program after parsing the arguments.

Returns

The full path of the invoked program.

setDescription()

void bps::CmdlineParser::setDescription

(

String

aDescription

)

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.

setProgram()

void bps::CmdlineParser::setProgram

(

String

aName

)

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

Parameters

aName

The program name to set.

switchState()

Boolean bps::CmdlineParser::switchState	(	String	aKey,
		String	aName
	)

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:

• bps.CmdlineParser.js