ROSE  0.9.9.139
Public Types | Public Member Functions | Protected Member Functions | List of all members
Sawyer::CommandLine::ValueParser Class Reference

Description

Base class parsing a value from input.

A ValueParser is a functor that attempts to recognize the next few characters of a command-line and to convert those characters to a value of some type. These are two separate but closely related operations. Subclasses of ValueParser must implement one of the operator() methods: either the one that takes a Cursor reference argument, or the one that takes pointers to C strings a la strtod. The cursor-based approach allows a match to span across several program arguments, and the C string pointer approach is a very simple interface.

If the parser is able to recognize the next characters of the input then it indicates so by advancing the cursor or updating the endptr argument; if no match occurs then the cursor is not changed and the endptr should point to the beginning of the string, and the parser throws an std::runtime_error. If, after recognizing and consuming some input, the parser is able to convert the recognized input into a value, then the value is returned as a ParsedValue, which includes information about where the value came from, otherwise an std::runtime_error is thrown. When an error is thrown, the caller can distinguish between the two failure modes by examining whether characters were consumed.

For instance, a parser that recognizes non-negative decimal integers would match (consume) any positive number of consecutive digits. However, if that string represents a mathematical value which is too large to store in the return type, then the parser should throw an exception whose string describes the problem, like "integer overflow", or "argument is too large to store in an 'int'".

Value parsers are always allocated on the heap and reference counted. Each value parser defines a class factory method, instance, to allocate a new object and return a pointer to it. The pointer types are named Ptr and are defined within the class. For convenience, the parsers built into the library also have global factory functions which have the same name as the class but start with an initial lower-case letter (see Command line parser factories for details). For instance:

class IntegerParser; // recognizes integers
IntegerParser::Ptr ptr = IntegerParser::instance(); // construct a new object
IntegerParser::Ptr ptr = integerParser(); // another constructor

Most of the library-provided functors are template classes whose argument specifies the type to use when creating a ParsedValue object. The constructors take an optional L-value in which to store the parsed value when the ParserResult::apply method is called. The factory functions are also templates with an optional argument, but template argument can be inferred by the compiler. As an example, here are three ways to call the factory function for the IntegerParser classes:

IntegerParser::Ptr ip1 = integerParser(); // stores value in ParserResult as int
IntegerParser::Ptr ip2 = integerParser<short>(); // stores value in ParserResult as short
long x;
IntegerParser::Ptr ip3 = integerParser(x); // stores value in ParserResult and x as long

The values are stored in a ParserResult object during the Parser::parse call, but are not moved into user-specified L-values until ParserResult::apply is called.

Users can create their own parsers, and are encouraged to do so, by following this same recipe.

See also
Command line parser factories

Definition at line 677 of file CommandLine.h.

#include <CommandLine.h>

Inheritance diagram for Sawyer::CommandLine::ValueParser:
Inheritance graph
[legend]
Collaboration diagram for Sawyer::CommandLine::ValueParser:
Collaboration graph
[legend]

Public Types

typedef SharedPointer< ValueParserPtr
 Reference counting pointer for this class. More...
 

Public Member Functions

ParsedValue matchString (const std::string &)
 Parse the entire string and return a value. More...
 
ParsedValue match (Cursor &)
 Parse a value from the beginning of the specified string. More...
 
Ptr valueSaver (const ValueSaver::Ptr &f)
 Property: functor responsible for saving a parsed value in user storage. More...
 
const ValueSaver::Ptr valueSaver () const
 Property: functor responsible for saving a parsed value in user storage. More...
 
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 
 SharedObject (const SharedObject &)
 Copy constructor. More...
 
virtual ~SharedObject ()
 Virtual destructor. More...
 
SharedObjectoperator= (const SharedObject &)
 Assignment. More...
 
- Public Member Functions inherited from Sawyer::SharedFromThis< ValueParser >
SharedPointer< ValueParser > sharedFromThis ()
 Create a shared pointer from this. More...
 
SharedPointer< const ValueParser > sharedFromThis () const
 Create a shared pointer from this. More...
 

Protected Member Functions

 ValueParser ()
 Constructor for derived classes. More...
 
 ValueParser (const ValueSaver::Ptr &valueSaver)
 Constructor for derived classes. More...
 

Member Typedef Documentation

Reference counting pointer for this class.

Definition at line 689 of file CommandLine.h.

Constructor & Destructor Documentation

Sawyer::CommandLine::ValueParser::ValueParser ( )
inlineprotected

Constructor for derived classes.

Non-subclass users should use instance or factories instead.

Definition at line 683 of file CommandLine.h.

Sawyer::CommandLine::ValueParser::ValueParser ( const ValueSaver::Ptr valueSaver)
inlineexplicitprotected

Constructor for derived classes.

Non-subclass users should use instance or factories instead.

Definition at line 686 of file CommandLine.h.

Member Function Documentation

ParsedValue Sawyer::CommandLine::ValueParser::matchString ( const std::string &  )

Parse the entire string and return a value.

The matching of the parser against the input is performed by calling match, which may throw an exception if the input is matched but cannot be converted to a value (e.g., integer overflow). If the parser did not match the entire string, then an std::runtime_error is thrown.

ParsedValue Sawyer::CommandLine::ValueParser::match ( Cursor )

Parse a value from the beginning of the specified string.

If the parser does not recognize the input then it throws an std::runtime_error without updating the cursor. If the parser recognizes the input but cannot convert it to a value (e.g., integer overflow) then the cursor should be updated to show the matching region before the matching operator throws the std::runtime_error exception.

Ptr Sawyer::CommandLine::ValueParser::valueSaver ( const ValueSaver::Ptr f)
inline

Property: functor responsible for saving a parsed value in user storage.

Many of the ValueParser subclasses take an argument which is a reference to a user-defined storage location, such as:

bool verbose;
Switch("verbose")
.intrinsicValue("true", booleanParser(verbose));

When a parser is created in such a way, a ValueSaver object is created and recorded in this property. After parsing, if the user invokes ParserResult::apply, the parsed value is saved into the user location. No value is saved until apply is called–this allows command-lines to be parsed for their error side effects without actually changing any program state.

Definition at line 718 of file CommandLine.h.

const ValueSaver::Ptr Sawyer::CommandLine::ValueParser::valueSaver ( ) const
inline

Property: functor responsible for saving a parsed value in user storage.

Many of the ValueParser subclasses take an argument which is a reference to a user-defined storage location, such as:

bool verbose;
Switch("verbose")
.intrinsicValue("true", booleanParser(verbose));

When a parser is created in such a way, a ValueSaver object is created and recorded in this property. After parsing, if the user invokes ParserResult::apply, the parsed value is saved into the user location. No value is saved until apply is called–this allows command-lines to be parsed for their error side effects without actually changing any program state.

Definition at line 719 of file CommandLine.h.


The documentation for this class was generated from the following file: