ceph/src/boost/libs/spirit/repository/doc/qi/keywords.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Joel de Guzman
   3     Copyright (C) 2001-2011 Hartmut Kaiser
   4     Copyright (C) 2011 Thomas Bernard
   5
   6     Distributed under the Boost Software License, Version 1.0. (See accompanying
   7     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   8 ===============================================================================/]
   9
  10 [section:keyword_list Keyword List  Operator]
  11
  12 [heading Description]
  13
  14 The keyword list operator, `kwd("k1")[a] / kwd("k2")[b]`,  works tightly with the kwd, ikwd, dkwd and idkwd directives
  15 to effeciently match keyword lists. As long as one of the keywords specified through the kwd, ikwd, dkwd or idkwd directive
  16 matches, the keyword will be immediatly followed by the keyword's associated subject parser.
  17 The parser will continue parsing input as long as the one of the keywords and it's associated parser succeed.
  18 Writing :
  19 (kwd("k1")[a] / kwd("k2")[b] / ... )
  20 is equivalent to:
  21 *( "k1" > a | "k2" > b ... ).
  22
  23
  24 [heading Header]
  25
  26     // forwards to <boost/spirit/repository/home/qi/operator/keywords.hpp>
  27     #include <boost/spirit/repository/include/qi_keywords.hpp>
  28
  29 [heading Expression Semantics]
  30
  31 [table
  32     [[Expression]       [Semantics]]
  33     [[`kwd(k1)[a] / kwd(k2)[b]`]         [Match `lit(k1) > a` or `lit(k2) > b`, equivalent to `lit(k1) > a | lit(k2) > b`]]
  34 ]
  35
  36 [heading Attributes]
  37
  38
  39 [table
  40     [[Expression]       [Attribute]]
  41     [[`kwd("k1")[a] / kwd("k2")[b]`]
  42 [``a: A, b: B --> (kwd(k1)[a] / kwd(k2)[b]): tuple<A, B>
  43 a: A, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): optional<A>
  44 a: Unused, b: B --> (kwd("k1")[a] / kwd(k2)[b]): optional<B>
  45 a: Unused, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): Unused
  46
  47 a: A, b: A -->(kwd(k1)[a] / kwd(k2)[b]): tuple<A, A>``]]
  48 ]
  49
  50 [note The keyword list parser works tightly with the kwd, ikwd, dkwd and idkwd directives
  51       and can't be used without it. A compile time error will warn you
  52       of any mistakes. This parser collects all the kwd directives and
  53       extracts the keyword literals or parsers from the directives to internaly
  54       build a Ternary Search Tree (TST) and permutation loop (for complex parsers)
  55       to effectively parse the keywords.
  56       Because you can't mix character types inside a TST you must take
  57       care not to mix wide strings with normal strings in the keywords you supply
  58       to a keyword list. Should it happen the compiler will trap the mistake for you.]
  59
  60 [note The kwd directive also works a bit like the repeat directive
  61       and can be used to formulate additional contraints on the number of
  62       times a keyword can or must occur while parsing a keyword list.]
  63
  64 [note The kwd, dkwd and ikwd, idkwd directives can be mixed inside a keyword list. This has
  65       however a small overhead and should be avoided when possible.]
  66
  67 [heading Complexity]
  68
  69 [:The overall complexity of the keyword list parser is defined by the
  70 sum of the complexities of its elements.]
  71
  72 [heading Example]
  73
  74 [import ../example/qi/keywords.cpp]
  75
  76 [note The test harness for the example(s) below is presented in the
  77 __qi_basics_examples__ section.]
  78
  79 Declare a small data structure representing a person:
  80
  81 [reference_keyword_list_test_data_structure]
  82
  83 Some using declarations:
  84
  85 [reference_using_declarations_keyword_list]
  86
  87 Now let's declare a keyword parser:
  88
  89 [reference_keyword_list_no_constraint_rule]
  90
  91 A couple of input string variations run on the same parser:
  92
  93 [reference_keyword_list]
  94
  95 Now let's delcare a parser with some occurrence constraints:
  96
  97 [reference_keyword_list_constraint_rule]
  98
  99 And see how it works in these two cases:
 100
 101 [reference_keyword_list_constraints]
 102
 103 [endsect] [/ Keyword list]