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:
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:
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 699 of file util/Sawyer/CommandLine.h.
#include <CommandLine.h>
Public Types | |
| typedef SharedPointer< ValueParser > | Ptr |
| Reference counting pointer for this class. | |
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... | |
| SharedObject & | operator= (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... | |
Constructor & Destructor Documentation
◆ ValueParser() [1/2]
|
inlineprotected |
Constructor for derived classes.
Non-subclass users should use instance or factories instead.
Definition at line 705 of file util/Sawyer/CommandLine.h.
◆ ValueParser() [2/2]
|
inlineexplicitprotected |
Constructor for derived classes.
Non-subclass users should use instance or factories instead.
Definition at line 708 of file util/Sawyer/CommandLine.h.
Member Function Documentation
◆ matchString()
| 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.
◆ match()
| 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.
◆ valueSaver() [1/2]
|
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:
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 740 of file util/Sawyer/CommandLine.h.
◆ valueSaver() [2/2]
|
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:
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 741 of file util/Sawyer/CommandLine.h.
Referenced by Rose::CommandLine::IntervalParser< Interval >::instance(), Rose::CommandLine::SuffixMultiplierParser< uint64_t >::instance(), Rose::Color::ColorizationParser::instance(), Sawyer::CommandLine::AnyParser< T >::instance(), Sawyer::CommandLine::IntegerParser< T >::instance(), Sawyer::CommandLine::NonNegativeIntegerParser< T >::instance(), Sawyer::CommandLine::PositiveIntegerParser< T >::instance(), Sawyer::CommandLine::RealNumberParser< T >::instance(), Sawyer::CommandLine::BooleanParser< T >::instance(), and Sawyer::CommandLine::EnumParser< T >::instance().
The documentation for this class was generated from the following file:
