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 14The keyword list operator, `kwd("k1")[a] / kwd("k2")[b]`, works tightly with the kwd, ikwd, dkwd and idkwd directives 15to efficiently match keyword lists. As long as one of the keywords specified through the kwd, ikwd, dkwd or idkwd directive 16matches, the keyword will be immediately followed by the keyword's associated subject parser. 17The parser will continue parsing input as long as the one of the keywords and it's associated parser succeed. 18Writing : 19(kwd("k1")[a] / kwd("k2")[b] / ... ) 20is 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> 43a: A, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): optional<A> 44a: Unused, b: B --> (kwd("k1")[a] / kwd(k2)[b]): optional<B> 45a: Unused, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): Unused 46 47a: 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 70sum 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 79Declare a small data structure representing a person: 80 81[reference_keyword_list_test_data_structure] 82 83Some using declarations: 84 85[reference_using_declarations_keyword_list] 86 87Now let's declare a keyword parser: 88 89[reference_keyword_list_no_constraint_rule] 90 91A couple of input string variations run on the same parser: 92 93[reference_keyword_list] 94 95Now let's delcare a parser with some occurrence constraints: 96 97[reference_keyword_list_constraint_rule] 98 99And see how it works in these two cases: 100 101[reference_keyword_list_constraints] 102 103[endsect] [/ Keyword list] 104