class PArgList: public PObject

This class allows the parsing of a set of program arguments.

Inheritance:


Public

[more] Construction
[more] Setting & Parsing
[more] Getting parsed arguments
[more] Errors

Protected Fields

[more]PStringArray argumentArray
The original program arguments.
[more]PString optionLetters
The specification letters for options
[more]PStringArray optionNames
The specification strings for options
[more]PIntArray optionCount
The count of the number of times an option appeared in the command line.
[more]PStringArray optionString
The array of associated strings to options.
[more]PIntArray parameterIndex
The index of each .
[more]int shift
Shift count for the parameters in the argument list.


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions

Miscellaneous functions


Documentation

This class allows the parsing of a set of program arguments. This translates the standard argc/argv style variables passed into the main() function into a set of options (preceded by a '-' character) and parameters.
o Construction

o PArgList( const char * theArgPtr = NULL, const char * argumentSpecPtr = NULL, BOOL optionsBeforeParams = TRUE )
Create an argument list. An argument list is created given the standard arguments and a specification for options. The program arguments are parsed from this into options and parameters.

The specification string consists of case significant letters for each option. If the letter is followed by the ':' character then the option has an associated string. This string must be in the argument or in the next argument.

Parameters:
theArgPtr - A string constituting the arguments
argumentSpecPtr - The specification C string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o PArgList( const PString & theArgStr, const char * argumentSpecPtr = NULL, BOOL optionsBeforeParams = TRUE )
Create an argument list.
Parameters:
theArgStr - A string constituting the arguments
argumentSpecPtr - The specification C string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o PArgList( const PString & theArgStr, const PString & argumentSpecStr, BOOL optionsBeforeParams = TRUE )
Create an argument list.
Parameters:
theArgStr - A string constituting the arguments
argumentSpecStr - The specification string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o PArgList( int theArgc, char ** theArgv, const char * argumentSpecPtr = NULL, BOOL optionsBeforeParams = TRUE )
Create an argument list.
Parameters:
theArgc - Count of argument strings in theArgv
theArgv - An array of strings constituting the arguments
argumentSpecPtr - The specification C string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o PArgList( int theArgc, char ** theArgv, const PString & argumentSpecStr, BOOL optionsBeforeParams = TRUE )
Create an argument list.
Parameters:
theArgc - Count of argument strings in theArgv
theArgv - An array of strings constituting the arguments
argumentSpecStr - The specification string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o Setting & Parsing

ovoid SetArgs( const PString & theArgStr )
Set the internal copy of the program arguments.
Parameters:
theArgStr - A string constituting the arguments

ovoid SetArgs( int theArgc, char ** theArgv )
Set the internal copy of the program arguments.
Parameters:
theArgc - Count of argument strings in theArgv
theArgv - An array of strings constituting the arguments

ovoid SetArgs( const PStringArray & theArgs )
Set the internal copy of the program arguments.
Parameters:
theArgs - A string array constituting the arguments

ovirtual BOOL Parse( const char * theArgumentSpec, BOOL optionsBeforeParams = TRUE )
Parse the arguments. Parse the standard C program arguments into an argument of options and parameters. Consecutive calls with optionsBeforeParams set to TRUE will parse out different options and parameters. If SetArgs() function is called then the Parse() function will restart from the beginning of the argument list.

The specification string consists of case significant letters for each option. If the letter is followed by a '-' character then a long name version of the option is present. This is terminated either by a '.' or a ':' character. If the single letter or long name is followed by the ':' character then the option has may have an associated string. This string must be within the argument or in the next argument. If a single letter option is followed by a ';' character, then the option may have an associated string but this MUST follow the letter immediately, if it is present at all.

For example, äb:c" allows for "-a -b arg -barg -c" and ä-an-arg.b-option:c;" allows for "-a --an-arg --option arg -c -copt".

Returns:
TRUE if there is at least one parameter after parsing.
Parameters:
theArgumentSpec - The specification string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

ovirtual BOOL Parse( const PString & theArgumentStr, BOOL optionsBeforeParams = TRUE )
Parse the arguments.
Parameters:
theArgumentStr - The specification string for argument options. See description for details.
optionsBeforeParams - Parse options only before parameters

o Getting parsed arguments

ovirtual PINDEX GetOptionCount( char optionChar ) const
Get the count of the number of times the option was specified on the command line.

Returns:
option repeat count.
Parameters:
optionChar - Character letter code for the option

ovirtual PINDEX GetOptionCount( const char * optionStr ) const
Get the count of option
Parameters:
optionStr - String code for the option

ovirtual PINDEX GetOptionCount( const PString & optionName ) const
Get the count of option
Parameters:
optionName - String code for the option

oBOOL HasOption( char optionChar ) const
Get if option present. Determines whether the option was specified on the command line.

Returns:
TRUE if the option was present.
Parameters:
optionChar - Character letter code for the option

oBOOL HasOption( const char * optionStr ) const
Get if option present.
Parameters:
optionStr - String letter code for the option

oBOOL HasOption( const PString & optionName ) const
Get if option present.
Parameters:
optionName - String code for the option

ovirtual PString GetOptionString( char optionChar, const char * dflt = NULL ) const
Get option string. Gets the string associated with an option e.g. -ofile or -o file would return the string "file". An option may have an associated string if it had a ':' character folowing it in the specification string passed to the Parse() function.

Returns:
the options associated string.
Parameters:
optionChar - Character letter code for the option
dflt - Default value of the option string

ovirtual PString GetOptionString( const char * optionStr, const char * dflt = NULL ) const
Get option string.
Parameters:
optionStr - String letter code for the option
dflt - Default value of the option string

ovirtual PString GetOptionString( const PString & optionName, const char * dflt = NULL ) const
Get option string.
Parameters:
optionName - String code for the option
dflt - Default value of the option string

oPINDEX GetCount() const
Get the argument count. Get the number of parameters that may be obtained via the GetParameter() function. Note that this does not include options and option strings.

Returns:
count of parameters.

oPString GetParameter( PINDEX num ) const
Get the parameter that was parsed in the argument list.

Returns:
parameter string at the specified index.
Parameters:
num - Number of the parameter to retrieve.

oPString operator[]( PINDEX num ) const
Get the parameter that was parsed in the argument list. The argument list object can thus be treated as an ärray" of parameters.

Returns:
parameter string at the specified index.
Parameters:
num - Number of the parameter to retrieve.

ovoid Shift( int sh )
Shift the parameters by the specified amount. This allows the parameters to be parsed at the same position in the argument list ärray".
Parameters:
sh - Number of parameters to shift forward through list

oPArgList& operator<<( int sh )
Shift the parameters by the specified amount. This allows the parameters to be parsed at the same position in the argument list ärray".
Parameters:
sh - Number of parameters to shift forward through list

oPArgList& operator>>( int sh )
Shift the parameters by the specified amount. This allows the parameters to be parsed at the same position in the argument list ärray".
Parameters:
sh - Number of parameters to shift backward through list

o Errors

ovirtual void IllegalArgumentIndex( PINDEX idx ) const
This function is called when access to illegal parameter index is made in the GetParameter function. The default behaviour is to output a message to the standard PError stream.
Parameters:
idx - Number of the parameter that was accessed.

ovirtual void UnknownOption( const PString & option ) const
This function is called when an unknown option was specified on the command line. The default behaviour is to output a message to the standard PError stream.
Parameters:
option - Option that was illegally placed on command line.

ovirtual void MissingArgument( const PString & option ) const
This function is called when an option that requires an associated string was specified on the command line but no associated string was provided. The default behaviour is to output a message to the standard PError stream.
Parameters:
option - Option for which the associated string was missing.

oPStringArray argumentArray
The original program arguments.

oPString optionLetters
The specification letters for options

oPStringArray optionNames
The specification strings for options

oPIntArray optionCount
The count of the number of times an option appeared in the command line.

oPStringArray optionString
The array of associated strings to options.

oPIntArray parameterIndex
The index of each .

oint shift
Shift count for the parameters in the argument list.


Direct child classes:
PConfigArgs

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.