Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.

Keyword List Operator


The keyword list operator, kwd("k1")[a] / kwd("k2")[b], works tightly with the kwd, ikwd, dkwd and idkwd directives to efficiently match keyword lists. As long as one of the keywords specified through the kwd, ikwd, dkwd or idkwd directive matches, the keyword will be immediately followed by the keyword's associated subject parser. The parser will continue parsing input as long as the one of the keywords and it's associated parser succeed. Writing : (kwd("k1")[a] / kwd("k2")[b] / ... ) is equivalent to: *( "k1" > a | "k2" > b ... ).

// forwards to <boost/spirit/repository/home/qi/operator/keywords.hpp>
#include <boost/spirit/repository/include/qi_keywords.hpp>
Expression Semantics



kwd(k1)[a] / kwd(k2)[b]

Match lit(k1) > a or lit(k2) > b, equivalent to lit(k1) > a | lit(k2) > b




kwd("k1")[a] / kwd("k2")[b]

a: A, b: B --> (kwd(k1)[a] / kwd(k2)[b]): tuple<A, B>
a: A, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): optional<A>
a: Unused, b: B --> (kwd("k1")[a] / kwd(k2)[b]): optional<B>
a: Unused, b: Unused --> (kwd(k1)[a] / kwd(k2)[b]): Unused

a: A, b: A -->(kwd(k1)[a] / kwd(k2)[b]): tuple<A, A>

[Note] Note

The keyword list parser works tightly with the kwd, ikwd, dkwd and idkwd directives and can't be used without it. A compile time error will warn you of any mistakes. This parser collects all the kwd directives and extracts the keyword literals or parsers from the directives to internaly build a Ternary Search Tree (TST) and permutation loop (for complex parsers) to effectively parse the keywords. Because you can't mix character types inside a TST you must take care not to mix wide strings with normal strings in the keywords you supply to a keyword list. Should it happen the compiler will trap the mistake for you.

[Note] Note

The kwd directive also works a bit like the repeat directive and can be used to formulate additional contraints on the number of times a keyword can or must occur while parsing a keyword list.

[Note] Note

The kwd, dkwd and ikwd, idkwd directives can be mixed inside a keyword list. This has however a small overhead and should be avoided when possible.


The overall complexity of the keyword list parser is defined by the sum of the complexities of its elements.

[Note] Note

The test harness for the example(s) below is presented in the Basics Examples section.

Declare a small data structure representing a person:

// Data structure definitions to test the kwd directive
// and the keywords list operator

struct person {
    std::string name;
    int age;
    double size;
    std::vector<std::string> favorite_colors;


std::ostream &operator<<(std::ostream &os, const person &p)
    os<<"Person : "<<<<", "<<p.age<<", "<<p.size<<std::endl;
    return os;

    (std::string, name)
    (int, age)
    (double, size)
    (std::vector<std::string>, favorite_colors)

Some using declarations:

using boost::spirit::repository::qi::kwd;
using boost::spirit::qi::inf;
using boost::spirit::ascii::space_type;
using boost::spirit::ascii::char_;
using boost::spirit::qi::double_;
using boost::spirit::qi::int_;
using boost::spirit::qi::rule;

Now let's declare a keyword parser:

no_constraint_person_rule %=
    kwd("name")['=' > parse_string ]
  / kwd("age")   ['=' > int_]
  / kwd("size")   ['=' > double_ > 'm']

A couple of input string variations run on the same parser:

Parsing a keyword list:

// Let's declare a small list of people for which we want to collect information.
person John,Mary,Mike,Hellen,Johny;
                "name = \"John\" \n age = 10 \n size = 1.69m "
                ,John);  // full in original order

                "age = 10 \n size = 1.69m \n name = \"Mary\""
                ,Mary);  // keyword oder doesn't matter

                 "size = 1.69m \n name = \"Mike\" \n age = 10 "
                ,Mike);  // still the same result


The code above will print:

Person : John, 10, 1.69
Person : Mary, 10, 1.69
Person : Mike, 10, 1.69

Now let's delcare a parser with some occurrence constraints:

The parser definition below uses the kwd directive occurrence constraint variants to make sure that the name and age keyword occur only once and allows the favorite color entry to appear 0 or more times.

constraint_person_rule %=
    kwd("name",1)                 ['=' > parse_string ]
  / kwd("age"   ,1)                 ['=' > int_]
  / kwd("size"   ,1)                 ['=' > double_ > 'm']
  / kwd("favorite color",0,inf) [ '=' > parse_string ]

And see how it works in these two cases:

 // Here all the give constraint are resepected : parsing will succeed.
     "name = \"Hellen\" \n age = 10 \n size = 1.80m \n favorite color = \"blue\" \n favorite color = \"green\" "

// Parsing this string will fail because the age and size minimum occurrence requirements aren't met.
     "name = \"Johny\"  \n favorite color = \"blue\" \n favorite color = \"green\" "
     ,Johny );

Parsing the first string will succeed but fail for the second string as the occurrence constraints aren't met. This code should print:

Person : Hellen, 10, 1.8