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

commandl::parser Class Reference

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

#include <parser.hpp>

List of all members.

Public Methods

 parser (const std::vector< argument * > &, const matcher &, const policy &)
 This is one of the many constructors for parser. More...

 parser (const std::vector< argument * > &, const matcher &)
 This constructor uses a default policy object. More...

 parser (const std::vector< argument * > &)
 This constructor uses both a default policy object and a default matcher object. More...

 parser (const parser &)
 This constructor is a copy constructor allowing a new parser object to be created from an existing parser object. More...

virtual ~parser ()
 This destructor takes care of cleaning things up. More...

virtual std::string name () const
 Returns the Name for this parser. More...

virtual unsigned long stop_position () const
 Returns the Position where the parser stopped. More...

virtual std::map< unsigned
long, std::string > 
elements_without_prefixes () const
 Returns the elements without valid prefixes. More...

virtual std::map< unsigned
long, std::string > 
elements_without_keys () const
 Returns the elements without matching keys. More...

virtual std::map< unsigned
long, std::string > 
elements_after_stop () const
 Returns the elements after the Stop_Position. More...

virtual std::ostream & usage (std::ostream &=std::cout) const
 Returns a complete usage statement based on the parser's Arguments. More...

virtual std::ostream & usage (argument *, std::ostream &=std::cout) const
 Returns a usage statement for the given argument_ptr. More...

virtual std::ostream & short_usage (std::ostream &=std::cout) const
 Returns a short usage statement based on the parser's Arguments. More...

virtual std::ostream & short_usage (argument *, std::ostream &=std::cout) const
 Returns a short usage statement for the given argument_ptr. More...

virtual void set_name (const std::string &)
 This simply sets a string that the parser will use as the name of this program in usage statements. More...

virtual void exceptions (bool=true)
 Determines whether this parser will throw exceptions or not. More...

virtual bool parse (int, char **, std::ostream &=std::cout)
 This is the main argument parsing method for this class. More...

virtual bool parse (std::vector< std::string >, std::ostream &=std::cout)
 This is the method that will parse the passed container. More...

virtual parser & operator= (const parser &)

Protected Methods

virtual std::pair< std::string,
std::string > 
separate_prefix_from (std::string)
 Identifies a prefix in the passed string and returns a pair. More...

virtual std::pair< std::string::size_type,
std::string > 
find_assignment_in (std::string)
 Identifies an assignment operator in a string. More...

virtual void identify_prefix_and_key (std::string)
 This method determines if there is a prefix and key in a string. More...

virtual void parse_required_values (std::string, std::string, std::string, std::string, commandl::argument *, std::vector< std::string >::iterator &, std::vector< std::string >::iterator)
 If the argument requires values, this method parses it. More...

virtual void parse_optional_values (std::string, std::string, std::string, std::string, commandl::argument *, std::vector< std::string >::iterator &, std::vector< std::string >::iterator)
 If the argument has optional values, this method parses it. More...

virtual void parse_character_keys (std::string, std::string, std::vector< std::string >::iterator &, std::vector< std::string >::iterator, bool=false)
 This method will recursively break up a token to try and find keys amongst the leading characters. More...


Protected Attributes

std::vector< argument * > Arguments
 This is the vector of argument* that parser will parse for. More...

matcherMatcher_ptr
 This is the matcher* that parser will use to match arguments. More...

policy Policy
 This is the policy object that parser will use. More...

bool Throws_Exceptions
 This determines whether parser throws commandl exceptions or not. More...

std::string Name
unsigned long int Position
 This is a counter for how far along the parser is. More...

unsigned long int Stop_Position
 This is the position at which the parser stopped parsing. More...

std::vector< std::string > Elements
 This is the vector of Elements that parser is currently parsing. More...

std::map< unsigned long, std::string > Elements_without_prefixes
std::map< unsigned long, std::string > Elements_without_keys
std::map< unsigned long, std::string > Elements_after_stop


Detailed Description

The class from which all parsers descend.

The parser is the heavy workhorse of the commandl library. Once you have set up all the other kinds of objects, it is the parser that uses them all to do the work. It is highly flexible (because of the other classes that it depends on), and configurable. It can be configured to either throw exceptions or not. My guess is that the commandl::parser class will probably be the least subclassed, but I could very well be wrong.


Constructor & Destructor Documentation

commandl::parser::parser const std::vector< argument * > &    arguments,
const matcher   matcher,
const policy   policy
 

This is one of the many constructors for parser.

commandl::parser::parser const std::vector< argument * > &    arguments,
const matcher   matcher
 

This constructor uses a default policy object.

commandl::parser::parser const std::vector< argument * > &    arguments
 

This constructor uses both a default policy object and a default matcher object.

commandl::parser::parser const parser &   
 

This constructor is a copy constructor allowing a new parser object to be created from an existing parser object.

commandl::parser::~parser   [virtual]
 

This destructor takes care of cleaning things up.


Member Function Documentation

std::map< unsigned long, std::string > commandl::parser::elements_after_stop   const [virtual]
 

Returns the elements after the Stop_Position.

If parsing is stopped before all of the elements are parsed, then the remaining elements can be retrieved via this method. The map contains their Positions and the elements themselves.

Returns:
A map of Positions and elements.

std::map< unsigned long, std::string > commandl::parser::elements_without_keys   const [virtual]
 

Returns the elements without matching keys.

If the parser's Policy allows it, when elements that do not match a key are found, they are placed in this map, indexed by their Position.

Returns:
A map of Positions and elements.

std::map< unsigned long, std::string > commandl::parser::elements_without_prefixes   const [virtual]
 

Returns the elements without valid prefixes.

If the parser's Policy allows it, when elements that do not have a valid prefix are found, they are placed in this map, indexed by their Position.

Returns:
A map of Positions and elements.

void commandl::parser::exceptions bool    throws_exceptions = true [virtual]
 

Determines whether this parser will throw exceptions or not.

The default behavior is for the parser to not throw any exceptions when parse() is called. If there is a failure within that operation, the parse() method will simply return false. However, if you'd like to get more information, you can always set this on, and get the exceptions out of the parse() method that may allow you more refined control.

Parameters:
A  boolean.

std::pair< std::string::size_type, std::string > commandl::parser::find_assignment_in std::string    element [protected, virtual]
 

Identifies an assignment operator in a string.

This method searches for a valid assignment operator within the string. If it identifies one it returns the position of that assignment operator and string that is the operator that was found. If it doesn't find one, it still returns a pair where the location is string::npos, and the opertor is the empty string.

Parameters:
A  string to be searched.
Returns:
A pair of std::string::size_type and a string.

void commandl::parser::identify_prefix_and_key std::string    element [protected, virtual]
 

This method determines if there is a prefix and key in a string.

This method either returns quietly, or throws if it cannot identify a valid prefix and a valid key within the given string.

Parameters:
A  string.

std::string commandl::parser::name   const [virtual]
 

Returns the Name for this parser.

Returns:
A string.

commandl::parser & commandl::parser::operator= const parser &    [virtual]
 

bool commandl::parser::parse std::vector< std::string >    elements,
std::ostream &    output = std::cout
[virtual]
 

This is the method that will parse the passed container.

This method does the work of parsing the elements based on this object's matcher and policy.

This library will not terminate your program, that's your job. As such, it is highly recommended that you check the return value of this method (or turn on exceptions and catch them via the exceptions() method), and do something appropriate (maybe calling the usage() statement and exiting) if the value is false.

Parameters:
A  vector of strings that will be parsed for arguments.
An  ostream on which to write error messages.
Returns:
A boolean indicating success or failure.

bool commandl::parser::parse int    argc,
char **    argv,
std::ostream &    output = std::cout
[virtual]
 

This is the main argument parsing method for this class.

This library will not terminate your program, that's your job. As such, it is highly recommended that you check the return value of this method (or turn on exceptions and catch them via the exceptions() method), and do something appropriate (maybe calling the usage() statement and exiting) if the value is false.

This class does little more than convert the char** into a proper STL container and pass it to a different version of parse.

Parameters:
An  integer that is the number of elements in the char** array.
A  char** array with the tokens to parse.
An  ostream on which to write error messages.
Returns:
A boolean indicating success or failure.

void commandl::parser::parse_character_keys std::string    prefix,
std::string    element,
std::vector< std::string >::iterator &    element_iterator,
std::vector< std::string >::iterator    element_end,
bool    nested = false
[protected, virtual]
 

This method will recursively break up a token to try and find keys amongst the leading characters.

For example, this method would could take the token "fbar" and depending on the Policy would interpret in in different ways:

key(s) value
fbar Can be optionally looked for in the next token.
f bar
f,b,a,r The key "r" could optionally look to the next token.
f,b The key "b" could take "ar"
f,b,a The key "a" could take "r"

Parameters:
A  string that will be used as the prefix.
A  string that will be used as the element to break up.
The  iterator that points to the tokens to be parsed.
The  iterator indicating the end of the tokens to be parsed.
A  boolean indicating whether this method is being called from within itself.

void commandl::parser::parse_optional_values std::string    prefix,
std::string    key,
std::string    assignment,
std::string    value,
commandl::argument   argument,
std::vector< std::string >::iterator &    element_iterator,
std::vector< std::string >::iterator    element_end
[protected, virtual]
 

If the argument has optional values, this method parses it.

Parameters:
A  string that will be used as the prefix.
A  string that will be used as the key.
A  string that will be used as the assignment.
A  string that will be used as the value.
The  argument* that will get values.
The  iterator that points to the tokens to be parsed.
The  iterator indicating the end of the tokens to be parsed.

void commandl::parser::parse_required_values std::string    prefix,
std::string    key,
std::string    assignment,
std::string    value,
commandl::argument   argument,
std::vector< std::string >::iterator &    element_iterator,
std::vector< std::string >::iterator    element_end
[protected, virtual]
 

If the argument requires values, this method parses it.

Parameters:
A  string that will be used as the prefix.
A  string that will be used as the key.
A  string that will be used as the assignment.
A  string that will be used as the value.
The  argument* that will get values.
The  iterator that points to the tokens to be parsed.
The  iterator indicating the end of the tokens to be parsed.

std::pair< std::string, std::string > commandl::parser::separate_prefix_from std::string    element [protected, virtual]
 

Identifies a prefix in the passed string and returns a pair.

The returned pair's first element is the prefix, and the second element is the non-prefix part of the passed in string. If this method cannot find a prefix, it will throw.

Parameters:
A  string.
Returns:
A pair of strings.

void commandl::parser::set_name const std::string &    name [virtual]
 

This simply sets a string that the parser will use as the name of this program in usage statements.

This value doesn't affect the parsing at all.

Parameters:
A  string that will be used as the name.

std::ostream & commandl::parser::short_usage argument   argument_ptr,
std::ostream &    output = std::cout
const [virtual]
 

Returns a short usage statement for the given argument_ptr.

This method places a short usage statement about the given argument. This method is written such that it can easily be used in a standard ostream inserter sequence, if desired.

Parameters:
An  argument* that we will get the usage information from.
The  ostream on which to write.
Returns:
An ostream reference.

std::ostream & commandl::parser::short_usage std::ostream &    output = std::cout const [virtual]
 

Returns a short usage statement based on the parser's Arguments.

This method places a short, one-line, usage statement on the given ostream. It consists of the information for all of the Arguments that this parser knows about. This method is written such that it can easily be used in a standard ostream inserter sequence, if desired.

Parameters:
The  ostream on which to write.
Returns:
An ostream reference.

unsigned long commandl::parser::stop_position   const [virtual]
 

Returns the Position where the parser stopped.

For most cases, this will be the last Position. However, if the parser came across a stop_arg, then parsing would have terminated sooner.

Returns:
An unsigned long

std::ostream & commandl::parser::usage argument   argument_ptr,
std::ostream &    output = std::cout
const [virtual]
 

Returns a usage statement for the given argument_ptr.

This method places a full usage statement about the given argument. This method is written such that it can easily be used in a standard ostream inserter sequence, if desired.

Returns:
An ostream reference.

std::ostream & commandl::parser::usage std::ostream &    output = std::cout const [virtual]
 

Returns a complete usage statement based on the parser's Arguments.

This method places a full usage statement on the given ostream. It consists of the information for all of the Arguments that this parser knows about. This method is written such that it can easily be used in a standard ostream inserter sequence, if desired.

Returns:
An ostream reference.


Member Data Documentation

std::vector<argument*> commandl::parser::Arguments [protected]
 

This is the vector of argument* that parser will parse for.

std::vector<std::string> commandl::parser::Elements [protected]
 

This is the vector of Elements that parser is currently parsing.

std::map<unsigned long, std::string> commandl::parser::Elements_after_stop [protected]
 

If there were any elements after the parser was told to stop parsing they will be in this map. They are stored as the position of the element, and the element itself.

std::map<unsigned long, std::string> commandl::parser::Elements_without_keys [protected]
 

If the Policy allows for it, this map contains the parsed elements that did not have matching keys. They are stored as the position of an element without a matching key, and the element itself.

std::map<unsigned long, std::string> commandl::parser::Elements_without_prefixes [protected]
 

If the Policy allows for it, this map contains the parsed elements that did not have valid prefixes. They are stored as the position of an element without a valid prefix, and the element itself.

matcher* commandl::parser::Matcher_ptr [protected]
 

This is the matcher* that parser will use to match arguments.

std::string commandl::parser::Name [protected]
 

Optional name of the program, can be set in parser for nice usage statements.

policy commandl::parser::Policy [protected]
 

This is the policy object that parser will use.

unsigned long int commandl::parser::Position [protected]
 

This is a counter for how far along the parser is.

unsigned long int commandl::parser::Stop_Position [protected]
 

This is the position at which the parser stopped parsing.

bool commandl::parser::Throws_Exceptions [protected]
 

This determines whether parser throws commandl exceptions or not.


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