PWLib  1.10.10
Protected Attributes
PArgList Class Reference

#include <args.h>

Inheritance diagram for PArgList:
PObject

List of all members.

Public Member Functions

Construction
 PArgList (const char *theArgPtr=NULL, const char *argumentSpecPtr=NULL, BOOL optionsBeforeParams=TRUE)
 PArgList (const PString &theArgStr, const char *argumentSpecPtr=NULL, BOOL optionsBeforeParams=TRUE)
 PArgList (const PString &theArgStr, const PString &argumentSpecStr, BOOL optionsBeforeParams=TRUE)
 PArgList (int theArgc, char **theArgv, const char *argumentSpecPtr=NULL, BOOL optionsBeforeParams=TRUE)
 PArgList (int theArgc, char **theArgv, const PString &argumentSpecStr, BOOL optionsBeforeParams=TRUE)
Overrides from class PObject
virtual void PrintOn (ostream &strm) const
virtual void ReadFrom (istream &strm)
Setting & Parsing
void SetArgs (const PString &theArgStr)
void SetArgs (int theArgc, char **theArgv)
void SetArgs (const PStringArray &theArgs)
virtual BOOL Parse (const char *theArgumentSpec, BOOL optionsBeforeParams=TRUE)
virtual BOOL Parse (const PString &theArgumentStr, BOOL optionsBeforeParams=TRUE)
Getting parsed arguments
virtual PINDEX GetOptionCount (char optionChar) const
virtual PINDEX GetOptionCount (const char *optionStr) const
virtual PINDEX GetOptionCount (const PString &optionName) const
BOOL HasOption (char optionChar) const
BOOL HasOption (const char *optionStr) const
BOOL HasOption (const PString &optionName) const
virtual PString GetOptionString (char optionChar, const char *dflt=NULL) const
virtual PString GetOptionString (const char *optionStr, const char *dflt=NULL) const
virtual PString GetOptionString (const PString &optionName, const char *dflt=NULL) const
PINDEX GetCount () const
PStringArray GetParameters (PINDEX first=0, PINDEX last=P_MAX_INDEX) const
PString GetParameter (PINDEX num) const
PString operator[] (PINDEX num) const
void Shift (int sh)
PArgListoperator<< (int sh)
PArgListoperator>> (int sh)
Errors
virtual void IllegalArgumentIndex (PINDEX idx) const
virtual void UnknownOption (const PString &option) const
virtual void MissingArgument (const PString &option) const

Protected Attributes

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

Detailed Description

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.


Constructor & Destructor Documentation

PArgList::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:
theArgPtrA string constituting the arguments
argumentSpecPtrThe specification C string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters
PArgList::PArgList ( const PString theArgStr,
const char *  argumentSpecPtr = NULL,
BOOL  optionsBeforeParams = TRUE 
)

Create an argument list.

Parameters:
theArgStrA string constituting the arguments
argumentSpecPtrThe specification C string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters
PArgList::PArgList ( const PString theArgStr,
const PString argumentSpecStr,
BOOL  optionsBeforeParams = TRUE 
)

Create an argument list.

Parameters:
theArgStrA string constituting the arguments
argumentSpecStrThe specification string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters
PArgList::PArgList ( int  theArgc,
char **  theArgv,
const char *  argumentSpecPtr = NULL,
BOOL  optionsBeforeParams = TRUE 
)

Create an argument list.

Parameters:
theArgcCount of argument strings in theArgv
theArgvAn array of strings constituting the arguments
argumentSpecPtrThe specification C string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters
PArgList::PArgList ( int  theArgc,
char **  theArgv,
const PString argumentSpecStr,
BOOL  optionsBeforeParams = TRUE 
)

Create an argument list.

Parameters:
theArgcCount of argument strings in theArgv
theArgvAn array of strings constituting the arguments
argumentSpecStrThe specification string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters

Member Function Documentation

PINLINE PINDEX PArgList::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.

References parameterIndex, and shift.

virtual PINDEX PArgList::GetOptionCount ( char  optionChar) const [virtual]

Get the count of the number of times the option was specified on the command line.

Returns:
option repeat count.
Parameters:
optionCharCharacter letter code for the option

Referenced by HasOption().

virtual PINDEX PArgList::GetOptionCount ( const char *  optionStr) const [virtual]

Get the count of option

Parameters:
optionStrString code for the option
virtual PINDEX PArgList::GetOptionCount ( const PString optionName) const [virtual]

Get the count of option

Parameters:
optionNameString code for the option
virtual PString PArgList::GetOptionString ( char  optionChar,
const char *  dflt = NULL 
) const [virtual]

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:
optionCharCharacter letter code for the option
dfltDefault value of the option string
virtual PString PArgList::GetOptionString ( const char *  optionStr,
const char *  dflt = NULL 
) const [virtual]

Get option string.

Parameters:
optionStrString letter code for the option
dfltDefault value of the option string
virtual PString PArgList::GetOptionString ( const PString optionName,
const char *  dflt = NULL 
) const [virtual]

Get option string.

Parameters:
optionNameString code for the option
dfltDefault value of the option string
PString PArgList::GetParameter ( PINDEX  num) const

Get the parameter that was parsed in the argument list.

Returns:
parameter string at the specified index.
Parameters:
numNumber of the parameter to retrieve.

Referenced by operator[]().

PStringArray PArgList::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.
PINLINE BOOL PArgList::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:
optionCharCharacter letter code for the option

References GetOptionCount().

PINLINE BOOL PArgList::HasOption ( const char *  optionStr) const

Get if option present.

Parameters:
optionStrString letter code for the option

References GetOptionCount().

PINLINE BOOL PArgList::HasOption ( const PString optionName) const

Get if option present.

Parameters:
optionNameString code for the option

References GetOptionCount().

virtual void PArgList::IllegalArgumentIndex ( PINDEX  idx) const [virtual]

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:
idxNumber of the parameter that was accessed.
virtual void PArgList::MissingArgument ( const PString option) const [virtual]

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:
optionOption for which the associated string was missing.
PINLINE PArgList & PArgList::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:
shNumber of parameters to shift forward through list

References Shift().

PINLINE PArgList & PArgList::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:
shNumber of parameters to shift backward through list

References Shift().

PINLINE PString PArgList::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.

Returns:
parameter string at the specified index.
Parameters:
numNumber of the parameter to retrieve.

References GetParameter().

virtual BOOL PArgList::Parse ( const char *  theArgumentSpec,
BOOL  optionsBeforeParams = TRUE 
) [virtual]

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

Returns:
TRUE if there is at least one parameter after parsing.
Parameters:
theArgumentSpecThe specification string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters

Referenced by Parse().

PINLINE BOOL PArgList::Parse ( const PString theArgumentStr,
BOOL  optionsBeforeParams = TRUE 
) [virtual]

Parse the arguments.

Parameters:
theArgumentStrThe specification string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters

References Parse().

virtual void PArgList::PrintOn ( ostream &  strm) const [virtual]

Output the string to the specified stream.

Parameters:
strmI/O stream to output to.

Reimplemented from PObject.

virtual void PArgList::ReadFrom ( istream &  strm) [virtual]

Input the string from the specified stream. This will read all characters until a end of line is reached, then parsing the arguments.

Parameters:
strmI/O stream to input from.

Reimplemented from PObject.

void PArgList::SetArgs ( const PString theArgStr)

Set the internal copy of the program arguments.

Parameters:
theArgStrA string constituting the arguments

Referenced by SetArgs().

PINLINE void PArgList::SetArgs ( int  theArgc,
char **  theArgv 
)

Set the internal copy of the program arguments.

Parameters:
theArgcCount of argument strings in theArgv
theArgvAn array of strings constituting the arguments

References SetArgs().

void PArgList::SetArgs ( const PStringArray theArgs)

Set the internal copy of the program arguments.

Parameters:
theArgsA string array constituting the arguments
void PArgList::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:
shNumber of parameters to shift forward through list

Referenced by operator<<(), and operator>>().

virtual void PArgList::UnknownOption ( const PString option) const [virtual]

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:
optionOption that was illegally placed on command line.

Member Data Documentation

The original program arguments.

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

The specification letters for options.

The specification strings for options.

The array of associated strings to options.

The index of each .

Referenced by GetCount().

int PArgList::shift [protected]

Shift count for the parameters in the argument list.

Referenced by GetCount().


The documentation for this class was generated from the following files: