PArgList Class Reference

#include <args.h>

Inheritance diagram for PArgList:

List of all members.

Public Member Functions
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)
PArgList &	operator<< (int sh)
PArgList &	operator>> (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

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

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 PString &

theArgStr

)

Set the internal copy of the program arguments.

Parameters:

theArgStr

A string 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

void PArgList::SetArgs

(

const PStringArray &

theArgs

)

Set the internal copy of the program arguments.

Parameters:

theArgs

A string array constituting the arguments

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

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

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

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

(

const PString &

optionName

)

const [virtual]

Get the count of option

Parameters:

optionName

String code for the option

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

PINLINE BOOL PArgList::HasOption

(

const char *

optionStr

)

const

Get if option present.

Parameters:

optionStr

String letter code for the option

PINLINE BOOL PArgList::HasOption

(

const PString &

optionName

)

const

Get if option present.

Parameters:

optionName

String code for the option

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

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

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.

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.

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.

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.

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

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

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

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

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.

---

Member Data Documentation

PStringArray PArgList::argumentArray [protected]

The original program arguments.

PString PArgList::optionLetters [protected]

The specification letters for options.

PStringArray PArgList::optionNames [protected]

The specification strings for options.

PIntArray PArgList::optionCount [protected]

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

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 files:

• args.h
• osutil.inl

---