Stream Parsers (stream, wstream, etc.)

| Home | Libraries | People | FAQ | More

##### 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`

###### 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