PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Protected Types | Protected Member Functions | Protected Attributes | List of all members
PArgList Class Reference

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

`#include <args.h>`

Inheritance diagram for PArgList:
[legend]
Collaboration diagram for PArgList:
[legend]

## Classes
struct | OptionSpec

## 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...
void | SetCommandName (const PString &name)
| Set the comand name. More...
const PString & | GetCommandName () const
| Get the command name. More...
virtual bool | Parse (const char *theArgumentSpec=NULL, PBoolean optionsBeforeParams=true)
| Parse the arguments. More...
virtual bool | Parse (const PString &theArgumentStr, PBoolean optionsBeforeParams=true)
| Parse the arguments. More...
bool | IsParsed () const
| Determine if already parsed at least once. More...
const PString & | GetParseError () const
| Return error message after a call to Parse(). More...
ostream & | Usage (ostream &strm, const char *usage=NULL) const
| Output usage text for parsed arguments. More...
PString | Usage () const
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...
PArgList & | operator<< (int sh)
| Shift the parameters by the specified amount. More...
PArgList & | operator>> (int sh)
| Shift the parameters by the specified amount. More...
Public Member Functions inherited from PObject
unsigned | GetTraceContextIdentifier () const
| Get PTRACE context identifier. More...
void | SetTraceContextIdentifier (unsigned id)
void | GetTraceContextIdentifier (PObject &obj)
void | GetTraceContextIdentifier (PObject *obj)
void | SetTraceContextIdentifier (const PObject &obj)
void | SetTraceContextIdentifier (const PObject *obj)
virtual | ~PObject ()
virtual PObject * | Clone () const
| Create a copy of the class on the heap. More...
template<class CLS >
CLS * | CloneAs () const
| As for Clone() but converts to specified type. 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...
__inline const PObject * | PTraceObjectInstance () const
virtual void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. More...

## Protected Types
enum | OptionType { NoString, HasString, StringWithLetter }

## Protected Member Functions
bool | InternalSpecificationError (bool isError, const PString &msg)
size_t | InternalFindOption (const PString &name) const
int | InternalParseOption (const PString &opt, PINDEX offset, PINDEX &arg)
PINDEX | InternalGetOptionCountByIndex (size_t idx) const
PString | InternalGetOptionStringByIndex (size_t idx, const char *dflt) const
Protected Member Functions inherited from PObject
| PObject ()
| Constructor for PObject, made protected so cannot ever create one on its own. More...

## Protected Attributes
PString | m_commandName
bool | m_parsed
PString | m_parseError
PStringArray | m_argumentArray
vector< OptionSpec > | m_options
PIntArray | m_parameterIndex
| The index of each parameter. More...
int | m_shift
| Shift count for the parameters in the argument list. More...
int | m_argsParsed
Protected Attributes inherited from PObject
unsigned | m_traceContextIdentifier

## 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...
static __inline const PObject * | PTraceObjectInstance (const char *)
static __inline const PObject * | PTraceObjectInstance (const PObject *obj)
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.

## Member Enumeration Documentation

enum PArgList::OptionType
| protected

Enumerator
NoString |
HasString |
StringWithLetter |

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

  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.

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

const PString& PArgList::GetCommandName | ( |  | ) | const
| inline

Get the command name.

References m_commandName.

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

  optionChar | Character letter code for the option

Reimplemented in PConfigArgs.

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

Get the count of option.

Parameters

  optionStr | String code for the option

Reimplemented in PConfigArgs.

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

Get the count of option.

Parameters

  optionName | String 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

  optionChar | Character letter code for the option
  dflt | Default 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

  optionStr | String letter code for the option
  dflt | Default 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

  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.

Returns
  parameter string at the specified index.

Parameters

  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.

Returns
  array of parameter strings at the specified index range.

const PString& PArgList::GetParseError | ( |  | ) | const
| inline

Return error message after a call to Parse().

The return value will be an empty string if there was no error in parsing the command line.

References m_parseError.

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

  optionChar | Character letter code for the option

PBoolean PArgList::HasOption | ( | const char * | optionStr | ) | const

Get if option present.

Parameters

  optionStr | String letter code for the option

PBoolean PArgList::HasOption | ( | const PString & | optionName | ) | const

Get if option present.

Parameters

  optionName | String code for the option

size_t PArgList::InternalFindOption | ( | const PString & | name | ) | const
| protected

PINDEX PArgList::InternalGetOptionCountByIndex | ( | size_t | idx | ) | const
| protected

PString PArgList::InternalGetOptionStringByIndex | ( | size_t | idx,
|  | const char * | dflt
| ) |  | const
| protected

int PArgList::InternalParseOption | ( | const PString & | opt,
|  | PINDEX | offset,
|  | PINDEX & | arg
| ) |  |
| protected

bool PArgList::InternalSpecificationError | ( | bool | isError,
|  | const PString & | msg
| ) |  |
| protected

bool PArgList::IsParsed | ( |  | ) | const
| inline

Determine if already parsed at least once.

References m_parsed.

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

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

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.

virtual bool PArgList::Parse | ( | const char * | theArgumentSpec = `NULL`,
|  | PBoolean | optionsBeforeParams = `true`
| ) |  |
| virtual

Parse the arguments.

Parse the standard C program arguments into an argument of options and parameters.

If `optionsBeforeParams` is set to true then options will be parsed up until the first parameter. Consecutive calls maybe made using `theArgumentSpec` of NULL and sets of options/parametes may be parsed, e.g. -f -g first one -h -k second. A – indicates the end of the first parsed set if there are no parameters, e.g. -f -g – -h -k second

If `optionsBeforeParams` is set to false then options and parameters may be mixed in any order. If a – is seen then option parsing is stopped and all remaining arguments are passed as parameters, e.g. -a -b – "-param starting with minus sign".

If SetArgs() function is called then the Parse() function will restart from the beginning of the argument list. SetArgs(0, NULL) may be used to reset parsing without altering the supplied arguments.

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.

If the option is followed by a space character then all text up until a new line '\n' is used as a usage/help text for the option.

Any text comainted with '[' and ']' characters will provide a section break in the usage/help text.

For example, "ab:c" allows for "-a -b arg -barg -c" and "a-an-arg. help\nb-option:c;" allows for "-a &ndash;an-arg &ndash;option arg -c -copt".

Returns
  true if there is at least one parameter after parsing. Note if false is returned, IsParsed() should be used to determined if there was a parsing error, or there was just no parameters.

Parameters

  theArgumentSpec | The specification string for argument options. See description for details.
  optionsBeforeParams | Parse options only before parameters

virtual bool PArgList::Parse | ( | const PString & | theArgumentStr,
|  | PBoolean | optionsBeforeParams = `true`
| ) |  |
| virtual

Parse the arguments.

Parameters

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

virtual void PArgList::PrintOn | ( | ostream & | strm | ) | const
| virtual

Output the string to the specified stream.

Parameters

  strm | I/O stream to output to.

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.

void PArgList::SetArgs | ( | const PString & | theArgStr | ) |

Set the internal copy of the program arguments.

Parameters

  theArgStr | A string constituting the arguments

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

void PArgList::SetArgs | ( | const PStringArray & | theArgs | ) |

Set the internal copy of the program arguments.

Parameters

  theArgs | A string array constituting the arguments

void PArgList::SetCommandName | ( | const PString & | name | ) |
| inline

Set the comand name.

References m_commandName.

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

ostream& PArgList::Usage | ( | ostream & | strm,
|  | const char * | usage = `NULL`
| ) |  | const

Output usage text for parsed arguments.

If `usage` is non-null then text of the form "usage: processname args" is output wgere args is the text in the `usage` parameter. If `usage` has multiple lines in it, then each argument pattern is output.

Parameters

  strm | Stream to output usage text.
  usage | Usage first line

PString PArgList::Usage | ( |  | ) | const

## Member Data Documentation

int PArgList::m_argsParsed
| protected

PStringArray PArgList::m_argumentArray
| protected

PString PArgList::m_commandName
| protected

Referenced by GetCommandName(), and SetCommandName().

vector<OptionSpec> PArgList::m_options
| protected

PIntArray PArgList::m_parameterIndex
| protected

The index of each parameter.

bool PArgList::m_parsed
| protected

Referenced by IsParsed().

PString PArgList::m_parseError
| protected

Referenced by GetParseError().

int PArgList::m_shift
| protected

Shift count for the parameters in the argument list.

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

- args.h