Main Page   Namespace List   Class Hierarchy   Compound List   File List   Compound Members   File Members  

commandl::argument Class Reference

The class from which all arguments descend. More...

#include <argument.hpp>

Inheritance diagram for commandl::argument:

commandl::float_arg commandl::int_arg commandl::stop_arg commandl::string_arg commandl::usage_arg List of all members.

Public Methods

 argument (std::vector< std::string >, std::string, std::string, bool, int, bool)
 Constructor for a vector of keys. More...

 argument (std::string, std::string, std::string, bool, int, bool)
 Constructor for a single key. More...

virtual ~argument ()
virtual void operator() (const std::string &, const std::string &, const unsigned long)=0
virtual void operator() (const std::string &, const std::string &, const std::string &, const std::string &, const unsigned long)=0
virtual void operator() (const std::vector< std::string > &, const std::string &, const std::string &, const std::string &, const unsigned long)=0
virtual std::vector< std::string > get_keys () const
 Returns the keys for this argument. More...

virtual bool required () const
 Indicates whether this argument is a required argument. More...

virtual int values_size () const
 Returns the number of values that this argument expects. More...

virtual bool values_required () const
 Returns whether the values are required by this argument. More...

virtual bool was_found () const
 Indicates whether this argument was found. More...

virtual unsigned long order () const
 Returns an unsigned long int that indicates the order in which this argument was found. More...

virtual std::string description () const
 Gets the description of this argument. More...

virtual std::string value_description () const
 Gets the description of the value. More...

virtual void add_key (const std::string &)
 Allows addition of another string to the list of keys. More...

virtual void found (const unsigned long)
 Sets the order in which this argument was found. More...


Protected Attributes

std::vector< std::string > Keys
bool Argument_Required
int Number_Of_Values
bool Values_Required
unsigned long Found
std::string Description
std::string Value_Description

Detailed Description

The class from which all arguments descend.

The argument class is an abstract base class that covers the various kinds of things that you want to be modifiable by the user of your program. If these objects were just special function commandl objects, then you'd have to go through a second step to get the information that you want out of them to use in your program. However, through the magic of multiple inheritance and overloading, these objects are so much more. For example, the commandl::int_arg class inherits from the abstract base class argument, but also functions just like an int. You can use it just like you would use an int anywhere in your code, it just has a few extra methods that it inherits from commandl::argument so that it can be used by the commandl::parser object. For example, once the parser has used the matcher to determine a match, it passes the prefix, key, assignment, value and other information to the argument, and the argument at this point can take those values and fill itself out, or it can throw an exception (if you try and pass the value blah to an int_arg, it will do just that).

In addition to things like int_arg, float_arg, and string_arg that function like ints, floats, and strings, there are also a few special purpose argument classes, like usage_arg and stop_arg which essentially just interrupt the parsing process and cause the parser object to do some specific things (this is done via exceptions, such that argument objects don't have to know about the parser directly). The commandl::usage_arg argument object when matched causes the parser to emit a usage message either on STDERR or on an output stream of your choosing. The commandl::stop_arg when matched causes the parser to stop parsing the tokens that it was given, and depending on the commandl::policy object being used will most likely put any extra tokens into a vector for later use.

Also, a commandl::argument object is what I think of as a distal class. It isn't involved in any of the parsing or matching activities, and doesn't use either of those classes.


Constructor & Destructor Documentation

commandl::argument::argument std::vector< std::string >    key_strings,
std::string    val_desc,
std::string    desc,
bool    required,
int    values_count,
bool    values_required
 

Constructor for a vector of keys.

This constructor allows for multiple keys for this argument, such that multiple keys can be aliased to this argument. How the keys are matched to command line tokens is dependent on the matcher object used.

Parameters:
key_strings  A vector of strings that will be parsed into keys (by the matcher) for this argument object.
val_desc  A string which is intended to be a textual description of value that this argument takes.
desc  A string which is intended to be a plain textual description of the function of this argument.
required  If true, indicates that this argument object is required, but it is up to other code to respect that.
values_count  This indicates the number of values that this argument expects to receive.
values_required  If true, indicates that this argument requires a value or values.

commandl::argument::argument std::string    key_string,
std::string    val_desc,
std::string    desc,
bool    required,
int    values_count,
bool    values_required
 

Constructor for a single key.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This constructor allows for construction with a single key.

virtual commandl::argument::~argument   [inline, virtual]
 


Member Function Documentation

void commandl::argument::add_key const std::string &    new_key [virtual]
 

Allows addition of another string to the list of keys.

This is generally used for adding more aliases to a particular argument.

Parameters:
new_key  The string that should be added to the list of keys for this argument.

std::string commandl::argument::description   const [inline, virtual]
 

Gets the description of this argument.

Be warned that this string may be empty if the programmer is lazy.

Returns:
A string that should describe this argument.

void commandl::argument::found const unsigned    long [virtual]
 

Sets the order in which this argument was found.

This argument should be given the an unsigned long value indicating the order in which this argument was found. For example, if the prefix were a "-", and the following are valid keys: "s" (which takes a value), "z", "x", "v", "f" (which takes a value), and "blah". Then if we get the following tokens:

-sstate -zxvf foo.txt -blah

then the following unsigned long ints should be assigned to the found method:

key value found() value
s state 1
z (true) 2
x (true) 3
v (true) 4
f foo.txt 5
blah (true) 6

Parameters:
order  The unsigned long integer indicating the order that this argument was found in.

std::vector< std::string > commandl::argument::get_keys   const [inline, virtual]
 

Returns the keys for this argument.

This method returns a copy of the vector of strings that represents the keys for this argument.

Returns:
A vector of strings.

virtual void commandl::argument::operator() const std::vector< std::string > &   ,
const std::string &   ,
const std::string &   ,
const std::string &   ,
const unsigned    long
[pure virtual]
 

Implemented in commandl::float_arg, commandl::int_arg, commandl::stop_arg, commandl::string_arg, and commandl::usage_arg.

virtual void commandl::argument::operator() const std::string &   ,
const std::string &   ,
const std::string &   ,
const std::string &   ,
const unsigned    long
[pure virtual]
 

Implemented in commandl::float_arg, commandl::int_arg, commandl::stop_arg, commandl::string_arg, and commandl::usage_arg.

virtual void commandl::argument::operator() const std::string &   ,
const std::string &   ,
const unsigned    long
[pure virtual]
 

Implemented in commandl::float_arg, commandl::int_arg, commandl::stop_arg, commandl::string_arg, and commandl::usage_arg.

unsigned long commandl::argument::order   const [inline, virtual]
 

Returns an unsigned long int that indicates the order in which this argument was found.

Returns:
An unsigned long integer indicating the order this argument was found.

bool commandl::argument::required   const [inline, virtual]
 

Indicates whether this argument is a required argument.

Returns:
A boolean indicating whether this argument is required.

std::string commandl::argument::value_description   const [inline, virtual]
 

Gets the description of the value.

Returns:
A string that should describe the value or values that this argument takes.

bool commandl::argument::values_required   const [inline, virtual]
 

Returns whether the values are required by this argument.

If number_of_values is zero, this value is meaningless.

Returns:
A boolean indicating whether the values for this argument are required.

int commandl::argument::values_size   const [inline, virtual]
 

Returns the number of values that this argument expects.

The returned integer indicates to callers how many values this argument knows how to deal with. It also allows callers to determine which of the operator() methods to call.

If this is 0 or 1, the operator()(string) version can be called. If this is >1 or <0, then operator()(vector< string >) should be called.

It is assumed that callers will check this value prior to a call of operator(). Return values >1 will indicate that a vector with that many elements will be properly dealt with in operator(), conversely negative values here indicate that the operator() is expecting to handle a vector with "many" elements. In this regard all negative numbers are identical.

Returns:
The number of values this argument is prepared to accept.

bool commandl::argument::was_found   const [inline, virtual]
 

Indicates whether this argument was found.

This usually indicates that the argument was found during a parsing cycle. However, the found( bool ) method is public, and things other than the argument parser could have called it.

Returns:
A boolean, if true, then this argument was found by something.


Member Data Documentation

bool commandl::argument::Argument_Required [protected]
 

This indicates whether the argument itself is required.

std::string commandl::argument::Description [protected]
 

The description of this argument.

unsigned long commandl::argument::Found [protected]
 

Indicates whether the argument was found during parsing, and in which position.

std::vector<std::string> commandl::argument::Keys [protected]
 

This contains the strings which are keys for this argument, how these keys are interpreted is based on the matcher object.

int commandl::argument::Number_Of_Values [protected]
 

This defines how many values this argument knows how to accept.

std::string commandl::argument::Value_Description [protected]
 

The description of this argument's value.

bool commandl::argument::Values_Required [protected]
 

Indicates whether the values are required, if number_of_values is zero, this doesn't mean anything.


The documentation for this class was generated from the following files:
Generated on Sat Apr 5 21:17:28 2003 for commandl Library by doxygen1.2.15