Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
Expectation Directive (expect[])

There are occasions in which it is expected that the input must match a particular parser or the input is invalid. Such cases generally arise after matching a portion of a grammar, such that the context is fully known. In such a situation, failure to match should result in an exception. For example, when parsing an e-mail address, a name, an "@" and a domain name must be matched or the address is invalid.

The expect directive requires that the argument parser matches the input or an exception is emitted. Using on_error(), that exception can be handled by calling a handler with the context at which the parsing failed can be reported.

The expect directive parses an operand parser expression which may be a single parser or a complex parser expression like a sequence.

Single parser:


Parser expression:

expect[a >> b >> ...]

In the latter case while the plain Sequence simply returns a no-match (returns false) when one of the elements fail, the expect directive throws an expectation_failure<Iter> if any of the parsers (even the first parser of a sequence) fails to match.

[Note] Note

Spirit provides two ways to handle expectation failures by throwing an expectation exception. Use the Expectation operator if you do not need an exception to be thrown when the first parser of a sequence fails.

// forwards to <boost/spirit/home/qi/directive/expect.hpp>
#include <boost/spirit/include/qi_expect.hpp>

Also, see Include Structure.

Model of




A Parser


A ForwardIterator type

Expectation Failure

When the operand parser fails to match an expectation_failure<Iter> is thrown:

template <typename Iter>
struct expectation_failure : std::runtime_error
    Iter first;           // [first, last) iterator pointing
    Iter last;            // to the error position in the input.
    info what_;       // Information about the nature of the error.
Expression Semantics

Semantics of an expression is defined only where it differs from, or is not defined in UnaryParser.




Match a. If a fails, throw an expectation_failure<Iter>


See Compound Attribute Notation.




a: A --> expect[a]: A
a: Unused --> expect[a] : Unused


The overall complexity of the expectation parser is defined by the complexity of it's argument parser. The complexity of the expect directive itself is O(1).

[Note] Note

The test harness for the example(s) below is presented in the Basics Examples section.

Some using declarations:

using boost::spirit::ascii::char_;
using boost::spirit::qi::expect;
using boost::spirit::qi::expectation_failure;

The code below uses an expectation operator to throw an expectation_failure with a deliberate parsing error when "o" is expected and "x" is what is found in the input. The catch block prints the information related to the error. Note: This is low level code that demonstrates the bare-metal. Typically, you use an Error Handler to deal with the error.

    test_parser("xi", expect[char_('o')]); // should throw an exception
catch (expectation_failure<char const*> const& x)
    std::cout << "expected: "; print_info(x.what_);
    std::cout << "got: \"" << std::string(x.first, x.last) << '"' << std::endl;

The code above will print:

expected: tag: literal-char, value: o
got: "x"