PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
PArgList Class Reference

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

#include <args.h>

Inheritance diagram for PArgList:
PObject PCLI::Arguments PConfigArgs

Public Member Functions

Construction
 PArgList (const char *theArgPtr=NULL, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true)
 Create an argument list. More...
 
 PArgList (const PString &theArgStr, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true)
 Create an argument list. More...
 
 PArgList (const PString &theArgStr, const PString &argumentSpecStr, PBoolean optionsBeforeParams=true)
 Create an argument list. More...
 
 PArgList (int theArgc, char **theArgv, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true)
 Create an argument list. More...
 
 PArgList (int theArgc, char **theArgv, const PString &argumentSpecStr, PBoolean optionsBeforeParams=true)
 Create an argument list. More...
 
Overrides from class PObject
virtual void PrintOn (ostream &strm) const
 Output the string to the specified stream. More...
 
virtual void ReadFrom (istream &strm)
 Input the string from the specified stream. More...
 
Setting & Parsing
void SetArgs (const PString &theArgStr)
 Set the internal copy of the program arguments. More...
 
void SetArgs (int theArgc, char **theArgv)
 Set the internal copy of the program arguments. More...
 
void SetArgs (const PStringArray &theArgs)
 Set the internal copy of the program arguments. More...
 
virtual PBoolean Parse (const char *theArgumentSpec, PBoolean optionsBeforeParams=true)
 Parse the arguments. More...
 
virtual PBoolean Parse (const PString &theArgumentStr, PBoolean optionsBeforeParams=true)
 Parse the arguments. More...
 
Getting parsed arguments
virtual PINDEX GetOptionCount (char optionChar) const
 Get the count of the number of times the option was specified on the command line. More...
 
virtual PINDEX GetOptionCount (const char *optionStr) const
 Get the count of option. More...
 
virtual PINDEX GetOptionCount (const PString &optionName) const
 Get the count of option. More...
 
PBoolean HasOption (char optionChar) const
 Get if option present. More...
 
PBoolean HasOption (const char *optionStr) const
 Get if option present. More...
 
PBoolean HasOption (const PString &optionName) const
 Get if option present. More...
 
virtual PString GetOptionString (char optionChar, const char *dflt=NULL) const
 Get option string. More...
 
virtual PString GetOptionString (const char *optionStr, const char *dflt=NULL) const
 Get option string. More...
 
virtual PString GetOptionString (const PString &optionName, const char *dflt=NULL) const
 Get option string. More...
 
PINDEX GetCount () const
 Get the argument count. More...
 
PStringArray GetParameters (PINDEX first=0, PINDEX last=P_MAX_INDEX) const
 Get the parameters that were parsed in the argument list. More...
 
PString GetParameter (PINDEX num) const
 Get the parameter that was parsed in the argument list. More...
 
PString operator[] (PINDEX num) const
 Get the parameter that was parsed in the argument list. More...
 
void Shift (int sh)
 Shift the parameters by the specified amount. More...
 
PArgListoperator<< (int sh)
 Shift the parameters by the specified amount. More...
 
PArgListoperator>> (int sh)
 Shift the parameters by the specified amount. More...
 
Errors
virtual void IllegalArgumentIndex (PINDEX idx) const
 This function is called when access to illegal parameter index is made in the GetParameter function. More...
 
virtual void UnknownOption (const PString &option) const
 This function is called when an unknown option was specified on the command line. More...
 
virtual 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. More...
 
- Public Member Functions inherited from PObject
virtual ~PObject ()
 
virtual PObjectClone () const
 Create a copy of the class on the heap. More...
 
virtual PINDEX HashFunction () const
 This function yields a hash value required by the PDictionary class. More...
 
virtual Comparison Compare (const PObject &obj) const
 Compare the two objects and return their relative rank. More...
 
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects. More...
 
bool operator== (const PObject &obj) const
 Compare the two objects. More...
 
bool operator!= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator< (const PObject &obj) const
 Compare the two objects. More...
 
bool operator> (const PObject &obj) const
 Compare the two objects. More...
 
bool operator<= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator>= (const PObject &obj) const
 Compare the two objects. More...
 
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance. More...
 
PBoolean IsClass (const char *cls) const
 
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class. More...
 

Protected Attributes

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

Additional Inherited Members

- Public Types inherited from PObject
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
 Result of the comparison operation performed by the Compare() function. More...
 
- Static Public Member Functions inherited from PObject
static Comparison InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
 Internal function caled from CompareObjectMemoryDirect() More...
 
static const char * Class ()
 Get the name of the class as a C string. More...
 
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own. More...
 
- Friends inherited from PObject

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,
PBoolean  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,
PBoolean  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,
PBoolean  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,
PBoolean  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,
PBoolean  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

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

Reimplemented in PConfigArgs.

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

Get the count of option.

Parameters
optionStrString code for the option

Reimplemented in PConfigArgs.

virtual PINDEX PArgList::GetOptionCount ( const PString optionName) const
virtual

Get the count of option.

Parameters
optionNameString code for the option

Reimplemented in PConfigArgs.

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

Reimplemented in PConfigArgs.

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

Reimplemented in PConfigArgs.

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

Reimplemented in PConfigArgs.

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.
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.
PBoolean 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
PBoolean PArgList::HasOption ( const char *  optionStr) const

Get if option present.

Parameters
optionStrString letter code for the option
PBoolean PArgList::HasOption ( const PString optionName) const

Get if option present.

Parameters
optionNameString code for the option
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.
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
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
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.
virtual PBoolean PArgList::Parse ( const char *  theArgumentSpec,
PBoolean  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 &ndash;an-arg &ndash;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
virtual PBoolean PArgList::Parse ( const PString theArgumentStr,
PBoolean  optionsBeforeParams = true 
)
virtual

Parse the arguments.

Parameters
theArgumentStrThe specification string for argument options. See description for details.
optionsBeforeParamsParse options only before parameters
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
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
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
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

PStringArray PArgList::argumentArray
protected

The original program arguments.

PIntArray PArgList::optionCount
protected

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

PString PArgList::optionLetters
protected

The specification letters for options.

PStringArray PArgList::optionNames
protected

The specification strings for options.

PStringArray PArgList::optionString
protected

The array of associated strings to options.

PIntArray PArgList::parameterIndex
protected

The index of each .

int PArgList::shift
protected

Shift count for the parameters in the argument list.


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