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:
theArgPtr A string constituting the arguments
argumentSpecPtr The specification C string for argument options. See description for details.
optionsBeforeParams Parse options only before parameters
PArgList::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
PArgList::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
PArgList::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
PArgList::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

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 ( const PString optionName  )  const [virtual]

Get the count of option

Parameters:
optionName String code for the option
virtual PINDEX PArgList::GetOptionCount ( const char *  optionStr  )  const [virtual]

Get the count of option

Parameters:
optionStr String code for the option
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:
optionChar Character letter code for the option

Referenced by HasOption().

virtual PString PArgList::GetOptionString ( const PString optionName,
const char *  dflt = NULL 
) const [virtual]

Get option string.

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

Get option string.

Parameters:
optionStr String letter code for the option
dflt Default value of the option string
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:
optionChar Character letter code for the option
dflt Default 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:
num Number 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 ( const PString optionName  )  const

Get if option present.

Parameters:
optionName String code for the option

References GetOptionCount().

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

Get if option present.

Parameters:
optionStr String letter code for the option

References GetOptionCount().

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:
optionChar Character letter 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:
idx Number 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:
option Option 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:
sh Number 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:
sh Number 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:
num Number of the parameter to retrieve.

References GetParameter().

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

Parse the arguments.

Parameters:
theArgumentStr The specification string for argument options. See description for details.
optionsBeforeParams Parse options only before parameters

References Parse().

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:
theArgumentSpec The specification string for argument options. See description for details.
optionsBeforeParams Parse options only before parameters

Referenced by Parse().

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

Output the string to the specified stream.

Parameters:
strm I/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:
strm I/O stream to input from.

Reimplemented from PObject.

void PArgList::SetArgs ( const PStringArray theArgs  ) 

Set the internal copy of the program arguments.

Parameters:
theArgs A string array constituting the arguments
PINLINE void PArgList::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

References SetArgs().

void PArgList::SetArgs ( const PString theArgStr  ) 

Set the internal copy of the program arguments.

Parameters:
theArgStr A string constituting the arguments

Referenced by SetArgs().

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:
sh Number 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:
option Option 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:

Generated on Sun Sep 6 03:50:34 2009 for PWLib by  doxygen 1.6.1