PTLib
Version 2.10.4
|
This class allows the parsing of a set of program arguments. More...
#include <args.h>
Public Member Functions | |
Construction | |
PArgList (const char *theArgPtr=NULL, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true) | |
Create an argument list. | |
PArgList (const PString &theArgStr, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true) | |
Create an argument list. | |
PArgList (const PString &theArgStr, const PString &argumentSpecStr, PBoolean optionsBeforeParams=true) | |
Create an argument list. | |
PArgList (int theArgc, char **theArgv, const char *argumentSpecPtr=NULL, PBoolean optionsBeforeParams=true) | |
Create an argument list. | |
PArgList (int theArgc, char **theArgv, const PString &argumentSpecStr, PBoolean optionsBeforeParams=true) | |
Create an argument list. | |
Overrides from class PObject | |
virtual void | PrintOn (ostream &strm) const |
Output the string to the specified stream. | |
virtual void | ReadFrom (istream &strm) |
Input the string from the specified stream. | |
Setting & Parsing | |
void | SetArgs (const PString &theArgStr) |
Set the internal copy of the program arguments. | |
void | SetArgs (int theArgc, char **theArgv) |
Set the internal copy of the program arguments. | |
void | SetArgs (const PStringArray &theArgs) |
Set the internal copy of the program arguments. | |
virtual PBoolean | Parse (const char *theArgumentSpec, PBoolean optionsBeforeParams=true) |
Parse the arguments. | |
virtual PBoolean | Parse (const PString &theArgumentStr, PBoolean optionsBeforeParams=true) |
Parse the arguments. | |
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. | |
virtual PINDEX | GetOptionCount (const char *optionStr) const |
Get the count of option. | |
virtual PINDEX | GetOptionCount (const PString &optionName) const |
Get the count of option. | |
PBoolean | HasOption (char optionChar) const |
Get if option present. | |
PBoolean | HasOption (const char *optionStr) const |
Get if option present. | |
PBoolean | HasOption (const PString &optionName) const |
Get if option present. | |
virtual PString | GetOptionString (char optionChar, const char *dflt=NULL) const |
Get option string. | |
virtual PString | GetOptionString (const char *optionStr, const char *dflt=NULL) const |
Get option string. | |
virtual PString | GetOptionString (const PString &optionName, const char *dflt=NULL) const |
Get option string. | |
PINDEX | GetCount () const |
Get the argument count. | |
PStringArray | GetParameters (PINDEX first=0, PINDEX last=P_MAX_INDEX) const |
Get the parameters that were parsed in the argument list. | |
PString | GetParameter (PINDEX num) const |
Get the parameter that was parsed in the argument list. | |
PString | operator[] (PINDEX num) const |
Get the parameter that was parsed in the argument list. | |
void | Shift (int sh) |
Shift the parameters by the specified amount. | |
PArgList & | operator<< (int sh) |
Shift the parameters by the specified amount. | |
PArgList & | operator>> (int sh) |
Shift the parameters by the specified amount. | |
Errors | |
virtual void | IllegalArgumentIndex (PINDEX idx) const |
This function is called when access to illegal parameter index is made in the GetParameter function. | |
virtual void | UnknownOption (const PString &option) const |
This function is called when an unknown option was specified on the command line. | |
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. | |
![]() | |
virtual | ~PObject () |
virtual PObject * | Clone () const |
Create a copy of the class on the heap. | |
virtual PINDEX | HashFunction () const |
This function yields a hash value required by the PDictionary class. | |
virtual Comparison | Compare (const PObject &obj) const |
Compare the two objects and return their relative rank. | |
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const |
Determine the byte wise comparison of two objects. | |
bool | operator== (const PObject &obj) const |
Compare the two objects. | |
bool | operator!= (const PObject &obj) const |
Compare the two objects. | |
bool | operator< (const PObject &obj) const |
Compare the two objects. | |
bool | operator> (const PObject &obj) const |
Compare the two objects. | |
bool | operator<= (const PObject &obj) const |
Compare the two objects. | |
bool | operator>= (const PObject &obj) const |
Compare the two objects. | |
virtual const char * | GetClass (unsigned ancestor=0) const |
Get the current dynamic type of the object instance. | |
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. |
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. |
Additional Inherited Members | |
![]() | |
enum | Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 } |
Result of the comparison operation performed by the Compare() function. More... | |
![]() | |
static Comparison | InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size) |
Internal function caled from CompareObjectMemoryDirect() | |
static const char * | Class () |
Get the name of the class as a C string. | |
![]() | |
PObject () | |
Constructor for PObject, made protected so cannot ever create one on its own. | |
![]() |
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.
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.
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 , |
||
PBoolean | optionsBeforeParams = true |
||
) |
Create an argument list.
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, | ||
PBoolean | optionsBeforeParams = true |
||
) |
Create an argument list.
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 , |
||
PBoolean | optionsBeforeParams = true |
||
) |
Create an argument list.
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, | ||
PBoolean | optionsBeforeParams = true |
||
) |
Create an argument list.
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 |
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.
|
virtual |
Get the count of the number of times the option was specified on the command line.
optionChar | Character letter code for the option |
Reimplemented in PConfigArgs.
|
virtual |
Get the count of option.
optionStr | String code for the option |
Reimplemented in PConfigArgs.
|
virtual |
Get the count of option.
optionName | String code for the option |
Reimplemented in PConfigArgs.
|
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.
optionChar | Character letter code for the option |
dflt | Default value of the option string |
Reimplemented in PConfigArgs.
|
virtual |
Get option string.
optionStr | String letter code for the option |
dflt | Default value of the option string |
Reimplemented in PConfigArgs.
|
virtual |
Get option string.
optionName | String code for the option |
dflt | Default value of the option string |
Reimplemented in PConfigArgs.
PString PArgList::GetParameter | ( | PINDEX | num | ) | const |
Get the parameter that was parsed in the argument list.
num | Number 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.
PBoolean PArgList::HasOption | ( | char | optionChar | ) | const |
Get if option present.
Determines whether the option was specified on the command line.
optionChar | Character letter code for the option |
PBoolean PArgList::HasOption | ( | const char * | optionStr | ) | const |
Get if option present.
optionStr | String letter code for the option |
Get if option present.
optionName | String code for the option |
|
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.
idx | Number of the parameter that was accessed. |
|
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.
option | Option 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".
sh | Number 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".
sh | Number 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.
num | Number of the parameter to retrieve. |
|
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".
theArgumentSpec | The specification string for argument options. See description for details. |
optionsBeforeParams | Parse options only before parameters |
|
virtual |
Parse the arguments.
theArgumentStr | The specification string for argument options. See description for details. |
optionsBeforeParams | Parse options only before parameters |
|
virtual |
Output the string to the specified stream.
strm | I/O stream to output to. |
Reimplemented from PObject.
|
virtual |
Input the string from the specified stream.
This will read all characters until a end of line is reached, then parsing the arguments.
strm | I/O stream to input from. |
Reimplemented from PObject.
void PArgList::SetArgs | ( | const PString & | theArgStr | ) |
Set the internal copy of the program arguments.
theArgStr | A string constituting the arguments |
void PArgList::SetArgs | ( | int | theArgc, |
char ** | theArgv | ||
) |
Set the internal copy of the program arguments.
theArgc | Count of argument strings in theArgv |
theArgv | An array of strings constituting the arguments |
void PArgList::SetArgs | ( | const PStringArray & | theArgs | ) |
Set the internal copy of the program arguments.
theArgs | A 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".
sh | Number of parameters to shift forward through list |
|
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.
option | Option that was illegally placed on command line. |
|
protected |
The original program arguments.
|
protected |
The count of the number of times an option appeared in the command line.
|
protected |
The specification letters for options.
|
protected |
The specification strings for options.
|
protected |
The array of associated strings to options.
|
protected |
The index of each .
|
protected |
Shift count for the parameters in the argument list.