Stream Parsers (stream, wstream, etc.)

Stream Parsers (`stream`, `wstream`, etc.)

Description

The stream_parser is a primitive which allows to use pre-existing standard streaming operators for input parsing integrated with Spirit.Qi. It provides a wrapper parser dispatching the underlying input stream to the stream operator of the corresponding attribute type to be parsed. Any value a to be parsed using the stream_parser will result in invoking the standard streaming operator for its type A, for instance:

std::istream& operator>> (std::istream&, A&);

Header

// forwards to <boost/spirit/home/qi/stream.hpp>
#include <boost/spirit/include/qi_stream.hpp>

Also, see Include Structure.

Namespace

Name
`boost::spirit::stream // alias: boost::spirit::qi::stream`
`boost::spirit::wstream // alias: boost::spirit::qi::wstream`

Synopsis

template <typename Char, typename Attrib>
struct stream_parser;

Template parameters

Parameter	Description	Default
`Char`	The character type to use to generate the input. This type will be used while assigning the generated characters to the underlying input iterator.	`char`
`Attrib`	The type of the attribute the `stream_parser` is expected to parse its input into.	`spirit::basic_hold_any<Char>`

Model of

PrimitiveParser

Notation

s: A variable instance of any type with a defined matching streaming operator>>() or a Lazy Argument that evaluates to any type with a defined matching streaming operator>>().

Expression Semantics

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

Expression	Description
`stream`	Call the streaming `operator>>()` for the type of the mandatory attribute. The input recognized by this operator will be the result of the `stream` parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be `char`.
`wstream`	Call the streaming `operator>>()` for the type of the mandatory attribute. The input recognized by this operator will be the result of the `wstream` parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be `wchar_t`.

All parsers listed in the table above are predefined specializations of the stream_parser<Char> basic stream parser type described below. It is possible to directly use this type to create stream parsers using an arbitrary underlying character type.

Expression	Semantics
stream_parser< Char, Attrib >()	Call the streaming `operator>>()` for the type of the optional attribute, `Attrib`. The input recognized by this operator will be the result of the `stream_parser<>` parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be `Char`

Expression

Semantics

stream_parser<
    Char, Attrib
>()

Call the streaming operator>>() for the type of the optional attribute, Attrib. The input recognized by this operator will be the result of the stream_parser<> parser. This parser never fails (unless the underlying input stream reports an error). The character type of the I/O istream is assumed to be Char

Additional Requirements

All of the stream parsers listed above require the type of the value to parse (the associated attribute) to implement a streaming operator conforming to the usual I/O streams conventions (where attribute_type is the type of the value to recognize while parse):

template <typename Istream>
Istream& operator>> (Istream& os, attribute_type& attr)
{
    // type specific input parsing
    return os;
}

This operator will be called by the stream parsers to gather the input for the attribute of type attribute_type.

	Note
	If the `stream` parser is invoked inside a `match` (or `phrase_match`) stream manipulator the `Istream` passed to the `operator>>()` will have registered (imbued) the same standard locale instance as the stream the `match` (or `phrase_match`) manipulator has been used with. This ensures all facets registered (imbued) with the original I/O stream object are used during input parsing.

Attributes

Expression	Attribute
`stream`	`spirit::hold_any`
`wstream`	`spirit::whold_any`
`stream_parser<Char, Attrib>()`	`Attrib`

	Important
	The attribute type `spirit::hold_any` exposed by some of the stream parsers is semantically and syntactically equivalent to the type implemented by Boost.Any. It has been added to Spirit as it has better performance and a smaller footprint than Boost.Any.

Complexity

O(N), where N is the number of characters consumed by the stream parser

Example

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

A class definition used in the examples:

// a simple complex number representation z = a + bi
struct complex
{
    complex (double a = 0.0, double b = 0.0)
      : a(a), b(b)
    {}

    double a;
    double b;
};

// define streaming operator for the type complex
std::istream&
operator>> (std::istream& is, complex& z)
{
    char lbrace = '\0', comma = '\0', rbrace = '\0';
    is >> lbrace >> z.a >> comma >> z.b >> rbrace;
    if (lbrace != '{' || comma != ',' || rbrace != '}')
        is.setstate(std::ios_base::failbit);
    return is;
}

Using declarations and variables:

using boost::spirit::qi::stream;
using boost::spirit::qi::stream_parser;

Parse a simple string using the operator>>(istream&, std::string&);

std::string str;
test_parser_attr("abc", stream, str);
std::cout << str << std::endl;                  // prints: abc

Parse our complex type using the operator>>(istream&, complex&);

complex c;
test_parser_attr("{1.0,2.5}", stream_parser<char, complex>(), c);
std::cout << c.a << "," << c.b << std::endl;    // prints: 1.0,2.5