[/============================================================================== Copyright (C) 2001-2011 Hartmut Kaiser Copyright (C) 2001-2011 Joel de Guzman Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ===============================================================================/] [section:stream Stream Parsers] This module includes the description of the different variants of the `stream` parser. It can be used to utilize existing streaming operators (`operator>>(std::istream&, ...)`) for input parsing. [heading Header] // forwards to #include Also, see __include_structure__. [section:stream Stream Parsers (`stream`, `wstream`, etc.)] [heading Description] The `stream_parser` is a primitive which allows to use pre-existing standard streaming operators for input parsing integrated with __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&); [heading Header] // forwards to #include Also, see __include_structure__. [heading Namespace] [table [[Name]] [[`boost::spirit::stream // alias: boost::spirit::qi::stream`]] [[`boost::spirit::wstream // alias: boost::spirit::qi::wstream`]] ] [heading Synopsis] template struct stream_parser; [heading Template parameters] [table [[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`]] ] [heading Model of] [:__primitive_parser_concept__] [variablelist Notation [[`s`] [A variable instance of any type with a defined matching streaming `operator>>()` or a __qi_lazy_argument__ that evaluates to any type with a defined matching streaming `operator>>()`.]] ] [heading Expression Semantics] Semantics of an expression is defined only where it differs from, or is not defined in __primitive_parser_concept__. [table [[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` basic stream parser type described below. It is possible to directly use this type to create stream parsers using an arbitrary underlying character type. [table [[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`]] ] [heading 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 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 [qi_match `match`] (or [qi_match `phrase_match`]) stream manipulator the `Istream` passed to the `operator>>()` will have registered (imbued) the same standard locale instance as the stream the [qi_match `match`] (or [qi_match `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. ] [heading Attributes] [table [[Expression] [Attribute]] [[`stream`] [`spirit::hold_any`]] [[`wstream`] [`spirit::whold_any`]] [[`stream_parser()`] [`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__. ] [heading Complexity] [:O(N), where N is the number of characters consumed by the stream parser] [heading Example] [note The test harness for the example(s) below is presented in the __qi_basics_examples__ section.] A class definition used in the examples: [reference_qi_complex] [reference_qi_stream_complex] [reference_qi_stream] [endsect] [endsect]