Parser

Description

The Parser is the most fundamental concept. A Parser has a member function, parse, that accepts a first-last ForwardIterator pair and returns bool as its result. The iterators delimit the data being parsed. The Parser's parse member function returns true if the parse succeeds, in which case the first iterator is advanced accordingly. Each Parser can represent a specific pattern or algorithm, or it can be a more complex parser formed as a composition of other Parsers.

Notation

p: A Parser.
P: A Parser type.
Iter: a ForwardIterator type.
f, l: ForwardIterator. first/last iterator pair.
Context: The parser's Context type.
context: The parser's Context, or unused.
skip: A skip Parser, or unused.
attrib: A Compatible Attribute, or unused.

Valid Expressions

In the expressions below, the behavior of the parser, p, and how skip and attrib are handled by p, are left unspecified in the base Parser concept. These are specified in subsequent, more refined concepts and by the actual models thereof.

For any Parser the following expressions must be valid:

Expression	Semantics	Return type
p.parse(f, l, context, skip, attr)	Match the input sequence starting from `f`. Return `true` if successful, otherwise return `false`.	`bool`
`p.what(context)`	Get information about a Parser.	`info`

Expression

Semantics

Return type

p.parse(f, l, context, skip, attr)

Match the input sequence starting from f. Return true if successful, otherwise return false.

bool

p.what(context)

Get information about a Parser.

info

Type Expressions

Expression	Description
`P::template attribute<Context, Iter>::type`	The Parser's expected attribute.
`traits::is_parser<P>::type`	Metafunction that evaluates to `mpl::true_` if a certain type, `P` is a Parser, `mpl::false_` otherwise (See MPL Boolean Constant).

Postcondition

Upon return from p.parse the following post conditions should hold:

On a successful match, f is positioned one past the last matching character/token.
On a failed match, if a skip parser is unused, f is restored to its original position prior to entry.
On a failed match, if a skip parser is not unused, f is positioned one past the last character/token matching skip.
On a failed match, attrib state is undefined.
No post-skips: trailing skip characters/tokens will not be skipped.

Models

All parsers in Spirit.Qi are models of the Parser concept.