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 14The `kwd[]`, `dkwd[]` and `ikwd[]`, `idkwd[]` provide a powerful and flexible mechanism for parsing keyword 15based input. It works in conjunction with the / operator to create an effective 16keyword parsing loop. The keyword parsing loop doesn't require the 17keywords to appear in a defined order in the input but also provides the possibility 18to check how many times a keyword appears in the input. 19 20The kwd directive will parse the keywords respecting case sensitivity whereas the ikwd 21direcive is case insensitive. You can mix the kwd and ikwd directives inside a set of 22keywords, but be aware that this has a small overhead. It should be preferred not to 23mix the kwd and ikwd directives. 24 25The dkwd and idkwd provide a mechanism to pase distinct keywords. These directives require 26that the skipper successeds parsing input right after the keyword part. 27 28dkwd("keyword1")['='>>int_] 29 30is equivalent to: 31 32lit("keyword1") >> skipper+ >> '=' >> int_ 33 34All the keyword directives can be mixed inside a keyword list. 35 36The kwd directive is very similar to the repeat directive in that it enables to enforce 37keyword occurrence constraints but also provides very interesting speed improvement 38over 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 55For non case sensitive keywords use the ikwd directive. 56If 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 69The keyword as well as the subject parameters can be any valid spirit parser. 70The 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> 78a: Unused --> kwd(k1)[a]: Unused``]] 79 [[`kwd(k1,n)[a]`] 80[``a: A --> kwd(k1,n)[a]: optional<A> or vector<A> 81a: 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> 84a: 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> 87a: 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 93parser. The complexity of the keyword list construct `kwd` itself is O(N), where N is the number 94of repetitions executed. 95 96In 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 98O(log n+k) 99 100Where k is the length of the string to be searched in a TST with n strings. 101 102When the keywords used are complex parsers, then the complexity is the sum of the sub parser complexities. 103 104] 105 106[heading Example] 107 108Please refer to keyword_list. 109 110[endsect] 111