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

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:

 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

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.

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

String bps::CmdlineParser::program ( )

Query the invoked program after parsing the arguments.

Returns:: The full path of the invoked program.

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.

void bps::CmdlineParser::setProgram ( String aName )

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

Parameters:

aName The program name to set.

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.

Public Member Functions

Detailed Description

Member Function Documentation