[ceph.git] / ceph / src / boost / libs / spirit / doc / qi / stream.qbk

[/==============================================================================
    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 <boost/spirit/home/qi/stream.hpp>
    #include <boost/spirit/include/qi_stream.hpp>

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 <boost/spirit/home/qi/stream.hpp>
    #include <boost/spirit/include/qi_stream.hpp>

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 <typename Char, typename Attrib>
    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<Char>`]]
]

[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<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.

[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 <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 [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<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__.
]

[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]
Commit	Line	Data
7c673cae FG	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
	11	This module includes the description of the different variants of the `stream`
	12	parser. 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
	20	Also, see __include_structure__.
	21
	22	[section:stream Stream Parsers (`stream`, `wstream`, etc.)]
	23
	24	[heading Description]
	25
	26	The `stream_parser` is a primitive which allows to use pre-existing standard
	27	streaming operators for input parsing integrated with __qi__. It
	28	provides a wrapper parser dispatching the underlying input stream to the stream
	29	operator of the corresponding attribute type to be parsed. Any value `a` to be
	30	parsed using the `stream_parser` will result in invoking the standard streaming
	31	operator 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
	40	Also, 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
80	Semantics of an expression is defined only where it differs from, or is
81	not 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
101	All parsers listed in the table above are predefined specializations of the
102	`stream_parser<Char>` basic stream parser type described below. It is
103	possible to directly use this type to create stream parsers using an
104	arbitrary 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
122	All of the stream parsers listed above require the type of the value to
123	parse (the associated attribute) to implement a streaming operator conforming
124	to the usual I/O streams conventions (where `attribute_type` is the type of the
125	value 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
134	This operator will be called by the stream parsers to gather the input for
135	the 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
171	A 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]