1[/============================================================================== 2 Copyright (C) 2001-2011 Hartmut Kaiser 3 Copyright (C) 2001-2011 Joel de Guzman 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section:stream Stream Parsers] 10 11This module includes the description of the different variants of the `stream` 12parser. It can be used to utilize existing streaming operators 13(`operator>>(std::istream&, ...)`) for input parsing. 14 15[heading Header] 16 17 // forwards to <boost/spirit/home/qi/stream.hpp> 18 #include <boost/spirit/include/qi_stream.hpp> 19 20Also, see __include_structure__. 21 22[section:stream Stream Parsers (`stream`, `wstream`, etc.)] 23 24[heading Description] 25 26The `stream_parser` is a primitive which allows to use pre-existing standard 27streaming operators for input parsing integrated with __qi__. It 28provides a wrapper parser dispatching the underlying input stream to the stream 29operator of the corresponding attribute type to be parsed. Any value `a` to be 30parsed using the `stream_parser` will result in invoking the standard streaming 31operator for its type `A`, for instance: 32 33 std::istream& operator>> (std::istream&, A&); 34 35[heading Header] 36 37 // forwards to <boost/spirit/home/qi/stream.hpp> 38 #include <boost/spirit/include/qi_stream.hpp> 39 40Also, see __include_structure__. 41 42[heading Namespace] 43 44[table 45 [[Name]] 46 [[`boost::spirit::stream // alias: boost::spirit::qi::stream`]] 47 [[`boost::spirit::wstream // alias: boost::spirit::qi::wstream`]] 48] 49 50[heading Synopsis] 51 52 template <typename Char, typename Attrib> 53 struct stream_parser; 54 55[heading Template parameters] 56 57[table 58 [[Parameter] [Description] [Default]] 59 [[`Char`] [The character type to use to generate 60 the input. This type will be used while 61 assigning the generated characters to the 62 underlying input iterator.] [`char`]] 63 [[`Attrib`] [The type of the attribute the `stream_parser` is 64 expected to parse its input into.] [`spirit::basic_hold_any<Char>`]] 65] 66 67[heading Model of] 68 69[:__primitive_parser_concept__] 70 71[variablelist Notation 72 [[`s`] [A variable instance of any type with a defined matching 73 streaming `operator>>()` or a __qi_lazy_argument__ that 74 evaluates to any type with a defined matching streaming 75 `operator>>()`.]] 76] 77 78[heading Expression Semantics] 79 80Semantics of an expression is defined only where it differs from, or is 81not defined in __primitive_parser_concept__. 82 83[table 84 [[Expression] [Description]] 85 [[`stream`] [Call the streaming `operator>>()` for the type 86 of the mandatory attribute. The input recognized 87 by this operator will be the result of the 88 `stream` parser. This parser never fails 89 (unless the underlying input stream reports an 90 error). The character type of the I/O istream 91 is assumed to be `char`.]] 92 [[`wstream`] [Call the streaming `operator>>()` for the type 93 of the mandatory attribute. The input recognized 94 by this operator will be the result of the 95 `wstream` parser. This parser never fails 96 (unless the underlying input stream reports an 97 error). The character type of the I/O istream 98 is assumed to be `wchar_t`.]] 99] 100 101All parsers listed in the table above are predefined specializations of the 102`stream_parser<Char>` basic stream parser type described below. It is 103possible to directly use this type to create stream parsers using an 104arbitrary underlying character type. 105 106[table 107 [[Expression] [Semantics]] 108 [ 109[``stream_parser< 110 Char, Attrib 111>()``] [Call the streaming `operator>>()` for the type 112 of the optional attribute, `Attrib`. The input recognized 113 by this operator will be the result of the 114 `stream_parser<>` parser. This parser never fails 115 (unless the underlying input stream reports an 116 error). The character type of the I/O istream 117 is assumed to be `Char`]] 118] 119 120[heading Additional Requirements] 121 122All of the stream parsers listed above require the type of the value to 123parse (the associated attribute) to implement a streaming operator conforming 124to the usual I/O streams conventions (where `attribute_type` is the type of the 125value to recognize while parse): 126 127 template <typename Istream> 128 Istream& operator>> (Istream& os, attribute_type& attr) 129 { 130 // type specific input parsing 131 return os; 132 } 133 134This operator will be called by the stream parsers to gather the input for 135the attribute of type `attribute_type`. 136 137[note If the `stream` parser is invoked inside a [qi_match `match`] 138 (or [qi_match `phrase_match`]) stream manipulator the `Istream` 139 passed to the `operator>>()` will have registered (imbued) the same 140 standard locale instance as the stream the [qi_match `match`] (or 141 [qi_match `phrase_match`]) manipulator has been used with. 142 This ensures all facets registered (imbued) with the original I/O 143 stream object are used during input parsing. 144] 145 146[heading Attributes] 147 148[table 149 [[Expression] [Attribute]] 150 [[`stream`] [`spirit::hold_any`]] 151 [[`wstream`] [`spirit::whold_any`]] 152 [[`stream_parser<Char, Attrib>()`] [`Attrib`]] 153] 154 155[important The attribute type `spirit::hold_any` exposed by some of the stream 156 parsers is semantically and syntactically equivalent to 157 the type implemented by __boost_any__. It has been added to /Spirit/ 158 as it has better performance and a smaller footprint than 159 __boost_any__. 160] 161 162[heading Complexity] 163 164[:O(N), where N is the number of characters consumed by the stream parser] 165 166[heading Example] 167 168[note The test harness for the example(s) below is presented in the 169__qi_basics_examples__ section.] 170 171A class definition used in the examples: 172 173[reference_qi_complex] 174[reference_qi_stream_complex] 175 176[reference_qi_stream] 177 178[endsect] 179 180[endsect] 181