ceph/src/boost/libs/spirit/doc/qi/stream.qbk

   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]