]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |