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

   1 [/==============================================================================
   2     Copyright (C) 2001-2012 Joel de Guzman
   3     Copyright (C) 2001-2012 Hartmut Kaiser
   4     Copyright (C) 2011-2012 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:kwd Qi Keyword Parser Directive ]
  11
  12 [heading Description]
  13
  14 The `kwd[]`, `dkwd[]` and `ikwd[]`, `idkwd[]` provide a powerful and flexible mechanism for parsing keyword
  15 based input. It works in conjuction with the / operator to create an effective
  16 keyword parsing loop. The keyword parsing loop doesn't require the
  17 keywords to appear in a defined order in the input but also provides the possibility
  18 to check how many times a keyword appears in the input.
  19
  20 The kwd directive will parse the keywords respecting case sensitivity whereas the ikwd
  21 direcive is case insensitive. You can mix the kwd and ikwd directives inside a set of
  22 keywords, but be aware that this has a small overhead. It should be prefered not to
  23 mix the kwd and ikwd directives.
  24
  25 The dkwd and idkwd provide a mechanism to pase distinct keywords. These directives require
  26 that the skipper successeds parsing input right after the keyword part.
  27
  28 dkwd("keyword1")['='>>int_]
  29
  30 is equivalent to:
  31
  32 lit("keyword1") >> skipper+ >> '=' >> int_
  33
  34 All the keyword directives can be mixed inside a keyword list.
  35
  36 The kwd directive is very similar to the repeat directive in that it enables to enforce
  37 keyword occurrence constraints but also provides very interesting speed improvement
  38 over the pure EBNF syntax or the Nabialek-Trick.
  39
  40 [heading Header]
  41
  42     // forwards to <boost/spirit/repository/home/qi/directive/kwd.hpp>
  43     #include <boost/spirit/repository/include/qi_kwd.hpp>
  44
  45 [heading Synopsis]
  46
  47 [table
  48     [[Expression]               [Semantics]]
  49     [[`kwd(keyword)[subject]`]              [Parse ( `"keyword"` > `subject`) zero or more times.]]
  50     [[`kwd(keyword,n)[subject]`]           [Parse ( `"keyword"` > `subject`) exactly `n` times.]]
  51     [[`kwd(keyword,min, max)[subject]`]    [Parse ( `"keyword"` > `subject`) at least `min` times and at most `max` times.]]
  52     [[`kwd(keyword,min, inf)[subject]`]    [Parse ( `"keyword"` > `subject`) at least `min` or more. ]]
  53 ]
  54
  55 For non case sensitive keywords use the ikwd directive.
  56 If distinct keyword parsing is required, use the dkwd and idkwd directive instead.
  57
  58 [heading Parameters]
  59
  60 [table
  61     [[Parameter]            [Description]]
  62     [[`keyword`]             [The parser for the opening (the prefix).]]
  63     [[`subject`]            [The parser for the input sequence following the keyword part.]]
  64     [[`n`]            [Int representing the exact number of times the keyword must be repeated.]]
  65     [[`min`]            [Int representing the minimum number of times the keyword must be repeated.]]
  66     [[`max`]            [Int representing the maximum number of times the keyword must be repeated.]]
  67 ]
  68
  69 The keyword as well as the subject parameters can be any valid spirit parser.
  70 The parameter n, min and max are integer constants.
  71
  72 [heading Attributes]
  73
  74 [table
  75     [[Expression]             [Attribute]]
  76     [[`kwd(k1)[a]`]
  77 [``a: A --> kwd(k1)[a]: optional<A> or vector<A>
  78 a: Unused --> kwd(k1)[a]: Unused``]]
  79     [[`kwd(k1,n)[a]`]
  80 [``a: A --> kwd(k1,n)[a]: optional<A> or vector<A>
  81 a: Unused --> kwd(k1,n)[a]: Unused``]]
  82     [[`kwd(k1,min, max)[a]`]
  83 [``a: A --> kwd(k1,min, max)[a]: optional<A> or vector<A>
  84 a: Unused --> kwd(k1,min, max)[a]: Unused``]]
  85     [[`kwd(k1,min, inf)[a]`]
  86 [``a: A --> kwd(k1,min, inf)[a]: optional<A> or vector<A>
  87 a: Unused --> kwd(k1,min, inf)[a]: Unused``]]
  88 ]
  89
  90 [heading Complexity]
  91
  92 [:The overall complexity is defined by the complexity of its subject
  93 parser. The complexity of the keyword list construct `kwd` itself is O(N), where N is the number
  94 of repetitions executed.
  95
  96 In the case where all the keywords are strings, the complexity of the keyword list itself determined by the complexity of the internal TST contents :
  97
  98 O(log n+k)
  99
 100 Where k is the length of the string to be searched in a TST with n strings.
 101
 102 When the keywords used are complex parsers, then the complexity is the sum of the sub parser complexities.
 103
 104 ]
 105
 106 [heading Example]
 107
 108 Please refer to keyword_list.
 109
 110 [endsect]