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

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   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:nonterminal Nonterminal Parsers]
  10
  11 [heading Module Headers]
  12
  13     // forwards to <boost/spirit/home/qi/nonterminal.hpp>
  14     #include <boost/spirit/include/qi_nonterminal.hpp>
  15
  16 Also, see __include_structure__.
  17
  18 [/------------------------------------------------------------------------------]
  19 [section:rule Parser Rule]
  20
  21 [heading Description]
  22
  23 The rule is a polymorphic parser that acts as a named placeholder
  24 capturing the behavior of a __peg__ expression assigned to it. Naming a
  25 __peg__ expression allows it to be referenced later and makes it
  26 possible for the rule to call itself. This is one of the most important
  27 mechanisms and the reason behind the word "recursive" in recursive
  28 descent parsing.
  29
  30 [heading Header]
  31
  32     // forwards to <boost/spirit/home/qi/nonterminal/rule.hpp>
  33     #include <boost/spirit/include/qi_rule.hpp>
  34
  35 Also, see __include_structure__.
  36
  37 [heading Namespace]
  38
  39 [table
  40     [[Name]]
  41     [[`boost::spirit::qi::rule`]]
  42 ]
  43
  44 [heading Synopsis]
  45
  46     template <typename Iterator, typename A1, typename A2, typename A3>
  47     struct rule;
  48
  49 [heading Template parameters]
  50
  51 [table
  52     [[Parameter]            [Description]                   [Default]]
  53     [[`Iterator`]           [The underlying iterator
  54                             type that the rule is
  55                             expected to work on.]           [none]]
  56     [[`A1`, `A2`, `A3`]     [Either `Signature`,
  57                             `Skipper` or `Locals` in
  58                             any order. See table below.]    [See table below.]]
  59 ]
  60
  61 Here is more information about the template parameters:
  62
  63 [table
  64     [[Parameter]            [Description]                   [Default]]
  65     [[`Signature`]          [Specifies the rule's synthesized
  66                             (return value) and inherited
  67                             attributes (arguments). More on
  68                             this here: __qi_nonterminal__.] [__unused_type__.
  69                                                             When `Signature` defaults
  70                                                             to __unused_type__, the effect
  71                                                             is the same as specifying a signature
  72                                                             of `void()` which is also equivalent
  73                                                             to `unused_type()`]]
  74     [[`Skipper`]            [Specifies the rule's skipper
  75                             parser. Specify this if you
  76                             want the rule to skip white
  77                             spaces. If this is not specified,
  78                             the rule is an "implicit lexeme"
  79                             and will not skip spaces.
  80                             "implicit lexeme" rules can
  81                             still be called with a skipper.
  82                             In such a case, the rule does a
  83                             pre-skip just as all lexemes
  84                             and primitives do.]             [__unused_type__]]
  85     [[`Locals`]             [Specifies the rule's local
  86                             variables.
  87                             See __qi_nonterminal__.]        [__unused_type__]]
  88 ]
  89
  90 [heading Model of]
  91
  92 [:__qi_nonterminal__]
  93
  94 [variablelist Notation
  95     [[`r, r2`]                      [Rules]]
  96     [[`p`]                          [A parser expression]]
  97     [[`Iterator`]                   [The underlying iterator type that the rule is
  98                                     expected to work on.]]
  99     [[`A1`, `A2`, `A3`]             [Either `Signature`, `Skipper` or `Locals` in
 100                                     any order.]]
 101 ]
 102
 103 [heading Expression Semantics]
 104
 105 Semantics of an expression is defined only where it differs from, or is
 106 not defined in __qi_nonterminal__.
 107
 108 [table
 109     [[Expression]                               [Description]]
 110     [[
 111 ``rule<Iterator, A1, A2, A3>
 112     r(name);``]                                 [Rule declaration. `Iterator` is required.
 113                                                 `A1, A2, A3` are optional and can be specified in any order.
 114                                                 `name` is an optional string that gives the rule
 115                                                 its name, useful for debugging and error handling.]]
 116     [[
 117 ``rule<Iterator, A1, A2, A3>
 118     r(r2);``]                                   [Copy construct rule `r` from rule `r2`.]]
 119     [[`r = r2;`]                                [Assign rule `r2` to `r`.]]
 120     [[`r.alias()`]                              [return an alias of `r`. The alias is a parser that
 121                                                 holds a reference to `r`.]]
 122     [[`r.copy()`]                               [Get a copy of `r`.]]
 123     [[`r = p;`]                                 [Rule definition. This is equivalent to `r %= p`
 124                                                 (see below) if there are no semantic actions attached
 125                                                 anywhere in `p`.]]
 126     [[`r %= p;`]                                [Auto-rule definition. The attribute of `p` should be
 127                                                 compatible with the synthesized attribute of `r`. When `p`
 128                                                 is successful, its attribute is automatically propagated
 129                                                 to `r`'s synthesized attribute.]]
 130     [[`r.name()`]                               [Retrieve the current name of the rule object.]]
 131     [[`r.name(name)`]                           [Set the current name of the rule object to be `name`.]]
 132 ]
 133
 134 [heading Attributes]
 135
 136 [:The parser attribute of the rule is `T`, its synthesized attribute. See
 137 __qi_nonterminal_attribute__]
 138
 139 [heading Complexity]
 140
 141 [:The complexity is defined by the complexity of the RHS parser, `p`]
 142
 143 [heading Example]
 144
 145 [note The test harness for the example(s) below is presented in the
 146 __qi_basics_examples__ section.]
 147
 148 [reference_rule]
 149
 150 [endsect] [/ Rule]
 151
 152 [/------------------------------------------------------------------------------]
 153 [section:grammar Parser Grammar]
 154
 155 [heading Description]
 156
 157 The grammar encapsulates a set of __qi_rules__ (as well as primitive
 158 parsers (__primitive_parser_concept__) and sub-grammars). The grammar is
 159 the main mechanism for modularization and composition. Grammars can be
 160 composed to form more complex grammars.
 161
 162 [heading Header]
 163
 164     // forwards to <boost/spirit/home/qi/nonterminal/grammar.hpp>
 165     #include <boost/spirit/include/qi_grammar.hpp>
 166
 167 Also, see __include_structure__.
 168
 169 [heading Namespace]
 170
 171 [table
 172     [[Name]]
 173     [[`boost::spirit::qi::grammar`]]
 174 ]
 175
 176 [heading Synopsis]
 177
 178     template <typename Iterator, typename A1, typename A2, typename A3>
 179     struct grammar;
 180
 181 [heading Template parameters]
 182
 183 [table
 184     [[Parameter]            [Description]                   [Default]]
 185     [[`Iterator`]           [The underlying iterator
 186                             type that the rule is
 187                             expected to work on.]           [none]]
 188     [[`A1`, `A2`, `A3`]     [Either `Signature`,
 189                             `Skipper` or `Locals` in
 190                             any order. See table below.]    [See table below.]]
 191 ]
 192
 193 Here is more information about the template parameters:
 194
 195 [table
 196     [[Parameter]            [Description]                   [Default]]
 197     [[`Signature`]          [Specifies the grammar's synthesized
 198                             (return value) and inherited
 199                             attributes (arguments). More on
 200                             this here: __qi_nonterminal__.] [__unused_type__.
 201                                                             When `Signature` defaults
 202                                                             to __unused_type__, the effect
 203                                                             is the same as specifying a signature
 204                                                             of `void()` which is also equivalent
 205                                                             to `unused_type()`]]
 206     [[`Skipper`]            [Specifies the grammar's skipper
 207                             parser. Specify this if you
 208                             want the grammar to skip white
 209                             spaces.]                        [__unused_type__]]
 210     [[`Locals`]             [Specifies the grammar's local
 211                             variables. See __qi_nonterminal__.]          [__unused_type__]]
 212 ]
 213
 214 [heading Model of]
 215
 216 [:__qi_nonterminal__]
 217
 218 [variablelist Notation
 219     [[`g`]                      [A grammar]]
 220 ]
 221
 222 [heading Expression Semantics]
 223
 224 Semantics of an expression is defined only where it differs from, or is not
 225 defined in __qi_nonterminal__.
 226
 227 [table
 228     [[Expression]       [Semantics]]
 229     [[
 230 ``
 231     template <typename Iterator>
 232     struct my_grammar : grammar<Iterator, A1, A2, A3>
 233     {
 234         my_grammar() : my_grammar::base_type(start, name)
 235         {
 236             // Rule definitions
 237             start = /* ... */;
 238         }
 239
 240         rule<Iterator, A1, A2, A3> start;
 241         // more rule declarations...
 242     };
 243 ``
 244     ]                   [Grammar definition. `name` is an optional string that gives the
 245                         grammar its name, useful for debugging and error handling.]]
 246 ]
 247
 248 [note The template parameters of a grammar and its start rule (the rule passed
 249       to the grammar's base class constructor) must match, otherwise you will
 250       see compilation errors.]
 251
 252 [heading Attributes]
 253
 254 [:The parser attribute of the grammar is `T`, its synthesized attribute. See
 255 __qi_nonterminal_attribute__]
 256
 257 [heading Complexity]
 258
 259 [:The complexity is defined by the complexity of the its definition.]
 260
 261 [heading Example]
 262
 263 [note The test harness for the example(s) below is presented in the
 264 __qi_basics_examples__ section.]
 265
 266 [reference_grammar_using]
 267
 268 [reference_grammar_definition]
 269
 270 [reference_grammar]
 271
 272 [endsect] [/ Grammar]
 273
 274 [endsect] [/ Nonterminal]