PArgList Class Reference

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

#include <args.h>

Inheritance diagram for PArgList:

Collaboration diagram for PArgList:

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 (const char *theArgStr)
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 char *prefix="Usage: ") const
	Output usage text for parsed arguments. More...
PString	Usage (const char *usage=NULL, const char *prefix="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...
template<typename ValueType , typename OptionType >
ValueType	GetOptionAs (OptionType option, ValueType value=0) const
	Get option as specicied type. 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
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...
__inline void	SetTraceContextIdentifier (unsigned id)
__inline void	SetTraceContextIdentifier (const PObject &obj)
__inline void	SetTraceContextIdentifier (const PObject *obj)
__inline void	CopyTraceContextIdentifier (PObject &obj) const
__inline void	CopyTraceContextIdentifier (PObject *obj) const
virtual	~PObject ()
__inline const char *	GetClass () const
__inline bool	IsClass (const char *name) const
__inline const PObject *	PTraceObjectInstance () const
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 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, OptionalString }

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 __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)
static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)
static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)
static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject *from)
static __inline const char *	Class ()
static __inline const PObject *	PTraceObjectInstance (const char *)
static __inline const PObject *	PTraceObjectInstance (const PObject *obj)
template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. More...
static Comparison	InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

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
OptionalString

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.

template<typename ValueType , typename OptionType >

ValueType PArgList::GetOptionAs ( OptionType  option, ValueType  value = 0  ) const

inline

Get option as specicied type.

Parameters

option	String letter code for the option
value	Default value of the option

References GetOptionString(), and PString::IsEmpty().

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.

Referenced by GetOptionAs().

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, following the single letter version, or an '=' sign for the long version, or in the next argument. If an option is followed by a ';' character, then the option may have an optional associated string but, if present, it MUST follow the single letter immediately, or be be after an '=' for long form.

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 --an-arg --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 )

inline

Set the internal copy of the program arguments.

Parameters

theArgStr

A string constituting the arguments

void PArgList::SetArgs

(

const char *

theArgStr

)

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 char *	prefix = "Usage: "
	)		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
prefix	Prefix for usage first line

PString PArgList::Usage	(	const char *	usage = NULL,
		const char *	prefix = "Usage: "
	)		const

Parameters

usage	Usage first line
prefix	Prefix for usage first line

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