class PArgList

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

Inheritance:


Public Methods

[more] Construction
[more] Overrides from class PObject
[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 Methods

Run Time Type functions

I/O functions

Public Members

Comparison 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 Overrides from class PObject

ovirtual void PrintOn( ostream & strm ) const
Output the string to the specified stream.
Parameters:
- strm I/O stream to output to.

ovirtual void ReadFrom( istream & strm )
Input the string from the specified stream. This will read all characters until a end of line is reached, then parsing the arguments.
Parameters:
- strm I/O stream to input from.

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, "ab:c" allows for "-a -b arg -barg -c" and "a-an-arg.b-option:c;" allows for "-a --an-arg --option arg -c -copt".

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

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.

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

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.

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

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.

Parameters:
optionChar - Character letter code for the option
dflt - Default value of the option string
Returns:
the options associated 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.

oPStringArray GetParameters( PINDEX first = 0, PINDEX last = P_MAX_INDEX ) const
Get the parameters that were parsed in the argument list.

Returns:
array of parameter strings at the specified index range.

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

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

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 "array" of parameters.

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

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 "array".
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 "array".
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 "array".
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++.