IArgumentDictionary

IArgumentDictionary is a general-purpose class for parsing text arguments on a command line and creating an ordered collection of key/value pairs. It parses arguments from an ITest object, a single string, or UNIX-style argc/argv parameters.

A leading hyphen character identifies keywords. Anything without a leading hyphen is a value argument. A keyword picks up the following argument if it is not another keyword. This example shows how IArgumentDictionary parses the command line input to create the key/value pairs.

Command-line input:

-parm -n sample1 Sue Tom -ccc 84 85

This table lists the options defined for the example:
   Key     Value     Description
   ---     -----     -----------
   -parm             The value associated with -parm is an empty IText, not NIL.
   -n      sample1   The -n argument picks up the following argument.
   1       Sue       There is no associated key so "1" is assigned.
   2       Tom       There is no associated key so "2" is assigned.
   -ccc    84        The -ccc argument picks up the value "84".
   3       85        There is no associated key so "3" is assigned.

The command line input arguments should be parsed and handled in the setup member function.


IArgumentDictionary - Member Functions and Data by Group

Constructors & Destructor

Class constructors and destructors.


[view class]
~IArgumentDictionary
Destructor
public:
virtual ~IArgumentDictionary()
IArgumentDictionary destructor function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IArgumentDictionary
IArgumentDictionary provides several constructors with a variety of signatures. Each constructor calls a corresponding importTextArguments functions. All constructors accept an optional parameter that specifies the options to be treated as naked options. (Naked options are input options never take values in a key/value pair.)


Overload 1
Constructor that uses the input values in theTest parameter as inputs
public:
IArgumentDictionary( ITest& theTest, const IString& nakedOptions = IArgumentDictionary::kEmptyText )
This constructor takes a constant reference to a ITest object and uses the inputs in theTest as arguments.

This unique constructor uses the outputTextStream() of the ITest object for its own error message output. When this constructor is used within an ITest, a failure to parse a number (which typically causes the test to fail) produces an error message in the diagnostic output of the ITest. If a different constructor is used, the error message appears but is lost thereafter. It can then be difficult to determine what caused the test to fail.

theTest
Test object
nakedOptions
The options that never take values

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Constructor that takes input string as inputs
public:
IArgumentDictionary( const IString& argumentString, const IString& nakedOptions = IArgumentDictionary::kEmptyText )
Constructor that takes an argument input string as inputs to the constructor.

argumentString
The argument string
nakedOptions
The options that never take values

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Copy constructor
public:
IArgumentDictionary(const IArgumentDictionary& source)

source
The IArgumentDictionary object to be copied

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
Constructor with standard UNIX style argc and argv arguments as inputs
public:
IArgumentDictionary( const int argc, const char * const* argv, const IString& nakedOptions = IArgumentDictionary::kEmptyText )
Constructor that takes standard UNIX style argc and argv arguments as inputs.

argc
The standard argc argument as passed in from the command line
argv
The standard argv argument as passed in from the command line
nakedOptions
The options that never take values

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
Default constructor
public:
IArgumentDictionary()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Assignment

Standard assignment operators.


[view class]
operator =
public:
IArgumentDictionary& operator =( const IArgumentDictionary& rhs )
Standard assignment operator for IArgumentDictionary class.

rhs
The IArgumentDictionary object used to do assignment

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


General Lookup

Member functions used to do general lookup of IArgumentDictionary values.


[view class]
countOfArguments
Returns the number of key/value pairs in the dictionary
public:
unsigned long countOfArguments() const
The function countofArugments returns the number of key/value pairs that are currently stored in the dictionary.

Return
the number of key/value pairs stored in the dictionary.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
findSimilarKey
Looks for a key similar to keyToMatch
public:
bool findSimilarKey( const IString& keyToMatch, IString& newKey ) const
This function looks for a key similar to value passed in the argument keyToMatch. If a similar key is found, it is returned in the argument newKey.

Note: key is considered to match if it is of equal length or longer than the match key, and if all characters in the match key are equal (case insensitive) to those in the key. Call lookupSimilarKeys(true) to always have the dictionary look for similar keys.

keyToMatch
Name of the key to match
newKey
Name of the key similar to keyToMatch

Return
false if no similar key is found; otherwise true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nthValue
Retrieve the index-th option-less value
public:
bool nthValue(const short index, IString& value)
This function attempts to retrieve the index-th option-less value. It returns false if no such value exists.

index
The given index
value
IString for retrieved value

Return
false if no such value exists; otherwise true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeOnLookup
Removes key/value pairs from the dictionary as they are looked up
public:
void removeOnLookup(bool)
Causes key/value pairs to be removed from the dictionary as they are looked up.

If removeOnLookup is called with argument true, then keys and values will be removed from the dictionary (keys will also be deleted) as they are looked up. This is useful if you want to make sure that all arguments are parsed by:

bool
true to turn on automatic key/value pair removal; false to turn it off

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
textAt
Value lookup for a given key
public:
bool textAt(const IString& key, IString& value)
Returns the value associated with the given key.

If the value was numeric, textAt returns it as a string. If no value was given, an empty IString object is returned.

key
The given key for lookup
value
The retrieved value, if one is found

Return
bool false if no such key exists; otherwise true

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Importing and Exporting

Member functions used to import and export information to and from the IArugmentDictionary.


[view class]
exportTextArguments
Exports the arguments in this dictionary
public:
void exportTextArguments(IString& argumentString)
This function exports the arguments in the given dictionary as a string of space-delimited keys and values.

argumentString
The string of keys and values

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
importTextArguments
Copies input text arguments from the passed-in parameters.

It places the key/value pairs from the input arguments in the dictionary. Arguments are added to any existing dictionary entries. Options are recognized by a leading '-' character. IArgumentDictionary tries to recognize negative numbers so you can not have input options that could be confused with negative numbers. For example, "-2ab" is a valid option; "-123" is not.


Overload 1
Copies the white-spaced delimited string of keys and values from the inputs
public:
void importTextArguments(const IString& argumentString)
Copies the white-spaced delimited string of keys and values from the input argument string.

argumentString
Name of a white-space delimited string of keys and values

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Copies the UNIX style argc and argv key/value input text parameters
public:
void importTextArguments( const int argc, const char * const* argv )
Copies the UNIX style argc and argv key/value input text parameters.

argc
UNIX-style argument count
argv
UNIX-style argument vector

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
Copies text arguments from the ITest object parameter
public:
void importTextArguments(ITest& theTest)
Copies text arguments from the ITest object parameter.

theTest
The ITest object where the text arguments should be copied from

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
lookupSimilarKeys
Toggles on or off the use of the findSimilarKey lookups
public:
void lookupSimilarKeys(bool)
This function toggles on or off the use of the findSimilarKey lookups. If lookupSimilarKeys(true) is called, the dictionary will henceforth call findSimilarKey for all lookups. It will also match similar keys during importTextArguments calls when checking to see if keys are naked keys.

bool
true/false

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
specifyNakedOptions
Specifies which options are "naked"
public:
void specifyNakedOptions(const IString& nakedOptions)
Specifies that the given options never take values in a key/value pair.

Call these methods *before* calling ImportTextArguments to change the way input arguments are handled.

nakedOptions
IString containing a space delineated list of the options that never takes values (e.g., ("-p -i -q)")@@@@@

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Number lookup

Member functions used to lookup values in the IArgumentDictionary based on a given key or index.


[view class]
nthNumber
This function returns the index-th option-less value parsed as a number in the parameter value. It behaves like the range-checked numberAt methods. The number must fall in the range minAllowed and maxAllowed.


Overload 1
Returns the index-th option-less value parsed as a number in the parameter value
public:
bool nthNumber( const short index, long& value, long minAllowed = LONG_MIN, long maxAllowed = LONG_MAX )

index
Index number of the value that is being looked up
value
Retrieved value (long)
minAllowed
Minimum value allowed (long)
maxAllowed
Maximum value allowed (long)

Return
true if the argument exists, it parses perfectly, and it is within the given range. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Returns the index-th option-less value parsed as a number in the parameter value
public:
bool nthNumber( const short index, double& value, double minAllowed = - DBL_MAX, double maxAllowed = DBL_MAX )

index
Index number of the value that is being looked up
value
Retrieved value (double)
minAllowed
Minimum value allowed (double)
maxAllowed
Maximum value allowed (double)

Return
true if the argument exists, it parses perfectly, and it is within the given range. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberAt
Looks up a number argument corresponding to the given key. The number must fall in the range minAllowed <= x <= maxAllowed. If the number parse badly, the argument does not exist, or is out of range, false is returned and leaves "value" unchanged.


Overload 1
public:
bool numberAt( const IString& key, double& value, double minAllowed = - DBL_MAX, double maxAllowed = DBL_MAX )

key
Key of the value that is being looked up
value
Retrieved value (double)
minAllowed
Minimum value allowed (double)
maxAllowed
Maximum value allowed (double)

Return
true if the argument exists, it parses perfectly and is within the given range, inclusively. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
bool numberAt( const IString& key, long& value, long minAllowed = LONG_MIN, long maxAllowed = LONG_MAX )

key
Key of the number
value
Retrieved value (long)
minAllowed
Minimum value allowed (long)
maxAllowed
Maximum value allowed (long)

Return
true if the argument exists, it parses perfectly and is within the given range, inclusively. false if the number parses badly, is out of range, or the argument does not exist, leaving value unchanged.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Public Constants

Public constants


[view class]
kEmptyText
Used to represent empty text fields in the IArgumentDictionary class.


Overload 1
Class member for empty text fields.
public:
static const IString & _Import kEmptyText

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
Class member for empty text fields.
public:
static const IString& kEmptyText

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations
This definition used for AIX Platforms only.


IArgumentDictionary - Inherited Member Functions and Data

Inherited Public Functions

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data