| [/============================================================================== |
| Copyright (C) 2001-2010 Joel de Guzman |
| Copyright (C) 2001-2010 Hartmut Kaiser |
| |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| ===============================================================================/] |
| |
| This quick reference section is provided for convenience. You can use |
| this section as a sort of a "cheat-sheet" on the most commonly used Qi |
| components. It is not intended to be complete, but should give you an |
| easy way to recall a particular component without having to dig up on |
| pages and pages of reference documentation. |
| |
| [section Common Notation] |
| |
| [variablelist Notation |
| [[`P`] [Parser type]] |
| [[`p, a, b, c`] [Parser objects]] |
| [[`A, B, C`] [Attribute types of parsers `a`, `b` and `c`]] |
| [[`I`] [The iterator type used for parsing]] |
| [[`Unused`] [An `unused_type`]] |
| [[`Context`] [The enclosing rule's `Context` type]] |
| [[`attrib`] [An attribute value]] |
| [[`Attrib`] [An attribute type]] |
| [[`b`] [A boolean expression]] |
| [[`fp`] [A (lazy parser) function with signature `P(Unused, Context)`]] |
| [[`fa`] [A (semantic action) function with signature `void(Attrib, Context, bool&)`. |
| The third parameter is a boolean flag that can be set to false to |
| force the parse to fail. Both `Context` and the boolean flag are |
| optional.]] |
| [[`first`] [An iterator pointing to the start of input]] |
| [[`last`] [An iterator pointing to the end of input]] |
| [[`Ch`] [Character-class specific character type (See __char_class_types__)]] |
| [[`ch`] [Character-class specific character (See __char_class_types__)]] |
| [[`ch2`] [Character-class specific character (See __char_class_types__)]] |
| [[`charset`] [Character-set specifier string (example: "a-z0-9")]] |
| [[`str`] [Character-class specific string (See __char_class_types__)]] |
| [[`Str`] [Attribute of `str`: `std::basic_string<T>` where `T` is the underlying character type of `str`]] |
| [[`tuple<>`] [Used as a placeholder for a fusion sequence]] |
| [[`vector<>`] [Used as a placeholder for an STL container]] |
| [[`variant<>`] [Used as a placeholder for a boost::variant]] |
| [[`optional<>`] [Used as a placeholder for a boost::optional]] |
| ] |
| |
| [endsect] |
| [section:qi_parsers Qi Parsers] |
| |
| [section:char Character Parsers] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[qi_lit_string `ch`]] [`Unused`] [Matches `ch`]] |
| [[[qi_lit_string `lit(ch)`]][`Unused`] [Matches `ch`]] |
| [[`char_`] [`Ch`] [Matches any character]] |
| [[`char_(ch)`] [`Ch`] [Matches `ch`]] |
| [[`char_("c")`] [`Ch`] [Matches a single char string literal, `c`]] |
| [[`char_(ch, ch2)`] [`Ch`] [Matches a range of chars from `ch` to `ch2` (inclusive)]] |
| [[`char_(charset)`] [`Ch`] [Matches a character set `charset`]] |
| |
| [[`alnum`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isalnum` in the current character set]] |
| [[`alpha`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isalpha` in the current character set]] |
| [[`blank`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isblank` in the current character set]] |
| [[`cntrl`] [`Ch`] [Matches a character based on the equivalent of |
| `std::iscntrl` in the current character set]] |
| [[`digit`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isdigit` in the current character set]] |
| [[`graph`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isgraph` in the current character set]] |
| [[`print`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isprint` in the current character set]] |
| [[`punct`] [`Ch`] [Matches a character based on the equivalent of |
| `std::ispunct` in the current character set]] |
| [[`space`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isspace` in the current character set]] |
| [[`xdigit`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isxdigit` in the current character set]] |
| [[`lower`] [`Ch`] [Matches a character based on the equivalent of |
| `std::islower` in the current character set]] |
| [[`upper`] [`Ch`] [Matches a character based on the equivalent of |
| `std::isupper` in the current character set]] |
| ] |
| |
| [endsect] |
| [section:numeric Numeric Parsers] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[`float_`] [`float`] [Parse a floating point number into a `float`]] |
| [[`double_`] [`double`] [Parse a floating point number into a `double`]] |
| [[`long_double`] [`long double`] [Parse a floating point number into a `long double`]] |
| |
| [[`bin`] [`unsigned`] [Parse a binary integer into an `unsigned`]] |
| [[`oct`] [`unsigned`] [Parse an octal integer into an `unsigned`]] |
| [[`hex`] [`unsigned`] [Parse a hexadecimal integer into an `unsigned`]] |
| [[`ushort_`] [`unsigned short`] [Parse an unsigned short integer]] |
| [[`ulong_`] [`unsigned long`] [Parse an unsigned long integer]] |
| [[`uint_`] [`unsigned int`] [Parse an unsigned int]] |
| [[`ulong_long`] [`unsigned long long`] [Parse an unsigned long long]] |
| [[`short_`] [`short`] [Parse a short integer]] |
| [[`long_`] [`long`] [Parse a long integer]] |
| [[`int_`] [`int`] [Parse an int]] |
| [[`long_long`] [`long long`] [Parse a long long]] |
| ] |
| |
| [endsect] |
| [section:string String Parsers] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[qi_lit_string `str`]] [`Unused`] [Matches `str`]] |
| [[[qi_lit_string `lit(str)`]] [`Unused`] [Matches `str`]] |
| [[[qi_lit_string `string(str)`]] [`Str`] [Matches `str`]] |
| |
| [[__qi_symbols__] [N/A] [Declare a symbol table, `sym`. `Ch` is the |
| underlying char type of the symbol table keys. |
| `T` is the data type associated with each key.]] |
| [[ |
| `` |
| sym.add |
| (str1, val1) |
| (str2, val2) |
| /*...more...*/ |
| ; |
| `` |
| ] |
| [N/A] [Add symbols into a symbol table, `sym`. |
| val1 and val2 are optional data of type `T`, |
| the data type associated with each key.]] |
| [[`sym`] [`T`] [Matches entries in the symbol table, `sym`. If |
| successful, returns the data associated with |
| the key]] |
| ] |
| |
| [endsect] |
| [section:auxiliary Auxiliary Parsers] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[__qi_eol__] [`Unused`] [Matches the end of line (`\r` or `\n` or `\r\n`)]] |
| [[__qi_eoi__] [`Unused`] [Matches the end of input (first == last)]] |
| [[__qi_eps__] [`Unused`] [Match an empty string]] |
| [[__qi_eps__`(b)`] [`Unused`] [If `b` is true, match an empty string]] |
| [[__qi_lazy__`(fp)`] [Attribute of `P` where `P` |
| is the return type of `fp`] [Invoke `fp` at parse time, returning a parser |
| `p` which is then called to parse.]] |
| [[`fp`] [see `lazy(fp)` above] [Equivalent to `lazy(fp)`]] |
| [[__qi_attr__] [`Attrib`] [Doesn't consume/parse any input, but exposes the |
| argument `attrib` as its attribute.]] |
| ] |
| |
| [endsect] |
| [section:binary Binary Parsers] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[`byte_`] [8 bits native endian] [Matches an 8 bit binary]] |
| [[`word`] [16 bits native endian] [Matches a 16 bit binary]] |
| [[`big_word`] [16 bits big endian] [Matches a 16 bit binary]] |
| [[`little_word`] [16 bits little endian] [Matches a 16 bit binary]] |
| [[`dword`] [32 bits native endian] [Matches a 32 bit binary]] |
| [[`big_dword`] [32 bits big endian] [Matches a 32 bit binary]] |
| [[`little_dword`] [32 bits little endian] [Matches a 32 bit binary]] |
| [[`qword`] [64 bits native endian] [Matches a 64 bit binary]] |
| [[`big_qword`] [64 bits big endian] [Matches a 64 bit binary]] |
| [[`little_qword`] [64 bits little endian] [Matches a 64 bit binary]] |
| ] |
| |
| [endsect] |
| |
| [section:auto Auto Parsers] |
| |
| See here for more information about [qi_auto Auto Parsers]. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[qi_auto `auto_`]] [`hold_any`] [Parse input using a parser |
| created from the supplied attribute type |
| using the __create_parser__ API function.]] |
| ] |
| |
| [endsect] |
| |
| [section:directive Parser Directives] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[__qi_lexeme__`[a]`] [`A`] [Disable skip parsing for `a`, does pre-skipping]] |
| [[[qi_no_skip `no_skip[a]`]] [`A`] [Disable skip parsing for `a`, no pre-skipping]] |
| [[__qi_no_case__`[a]`] [`A`] [Inhibits case-sensitivity for `a`]] |
| [[__qi_omit__`[a]`] [`Unused`] [Ignores the attribute type of `a`]] |
| [[__qi_matches__`[a]`] [`bool`] [Return if the embedded parser `a` matched its input]] |
| |
| [[__qi_raw__`[a]`] [__boost_iterator_range__`<I>`] [Presents the transduction of `a` as an iterator range]] |
| |
| [[[qi_repeat `repeat[a]`]] [`vector<A>`] [Repeat `a` zero or more times]] |
| [[[qi_repeat `repeat(N)[a]`]] [`vector<A>`] [Repeat `a` `N` times]] |
| [[[qi_repeat `repeat(N, M)[a]`]] [`vector<A>`] [Repeat `a` `N` to `M` times]] |
| [[[qi_repeat `repeat(N, inf)[a]`]] [`vector<A>`] [Repeat `a` `N` or more times]] |
| |
| [[__qi_skip__`[a]`] [`A`] [Re-establish the skipper that got inhibited by lexeme or no_skip.]] |
| [[__qi_skip__`(p)[a]`] [`A`] [Use `p` as a skipper for parsing `a`]] |
| ] |
| |
| [endsect] |
| [section:operator Parser Operators] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[`!a`] [`Unused`] [Not predicate. If the predicate `a` matches, |
| fail. Otherwise, return a zero length match.]] |
| [[`&a`] [`Unused`] [And predicate. If the predicate `a` matches, |
| return a zero length match. Otherwise, fail.]] |
| [[`-a`] [`optional<A>`] [Optional. Parse `a` zero or one time]] |
| [[`*a`] [`vector<A>`] [Kleene. Parse `a` zero or more times]] |
| [[`+a`] [`vector<A>`] [Plus. Parse `a` one or more times]] |
| [[`a | b`] [`variant<A, B>`] [Alternative. Parse `a` or `b`]] |
| [[`a >> b`] [`tuple<A, B>`] [Sequence. Parse `a` followed by `b`]] |
| [[`a > b`] [`tuple<A, B>`] [Expect. Parse `a` followed by `b`. `b` is |
| expected to match when `a` matches, otherwise, |
| an `expectation_failure` is thrown.]] |
| [[`a - b`] [`A`] [Difference. Parse `a` but not `b`]] |
| [[`a || b`] [`tuple<` |
| `optional<A>,` |
| `optional<B> >` |
| ] [Sequential Or. Parse `a` or `b` or `a` followed by `b`]] |
| [[`a % b`] [`vector<A>`] [List. Parse `a` delimited `b` one or more times]] |
| [[`a ^ b`] [`tuple<` |
| `optional<A>,` |
| `optional<B> >` |
| ] [Permutation. Parse `a` or `b` or `a` followed by `b` or `b` followed by `a`.]] |
| ] |
| |
| [endsect] |
| [section:action Parser Semantic Actions] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[`p[fa]`] [Attribute of `p`] [Call semantic action, `fa` if p succeeds.]] |
| ] |
| |
| [endsect] |
| [endsect] |
| [section Compound Attribute Rules] |
| |
| [heading Notation] |
| |
| The notation we will use will be of the form: |
| |
| a: A, b: B, ... --> composite-expression: composite-attribute |
| |
| `a`, `b`, etc. are the operands. `A`, `B`, etc. are the operand's |
| attribute types. `composite-expression` is the expression involving the |
| operands and `composite-attribute` is the resulting attribute type of |
| the composite expression. |
| |
| For instance: |
| |
| a: A, b: B --> (a >> b): tuple<A, B> |
| |
| reads as: given, `a` and `b` are parsers, and `A` is the type of the |
| attribute of `a`, and `B` is the type of the attribute of `b`, then the |
| type of the attribute of `a >> b` will be `tuple<A, B>`. |
| |
| [important In the attribute tables, we will use `vector<A>` and |
| `tuple<A, B...>` as placeholders only. The notation of `vector<A>` |
| stands for ['any __stl__ container] holding elements of type `A` and the |
| notation `tuple<A, B...>` stands for ['any __fusion__ sequence] holding |
| `A`, `B`, ... etc. elements. Finally, `Unused` stands for |
| __unused_type__. ] |
| |
| [heading Compound Parser Attribute Types] |
| |
| [table |
| [[Expression] [Attribute]] |
| |
| [[`a >> b`] |
| [``a: A, b: B --> (a >> b): tuple<A, B> |
| a: A, b: Unused --> (a >> b): A |
| a: Unused, b: B --> (a >> b): B |
| a: Unused, b: Unused --> (a >> b): Unused |
| |
| a: A, b: A --> (a >> b): vector<A> |
| a: vector<A>, b: A --> (a >> b): vector<A> |
| a: A, b: vector<A> --> (a >> b): vector<A> |
| a: vector<A>, b: vector<A> --> (a >> b): vector<A>``]] |
| |
| [[`a > b`] |
| [``a: A, b: B --> (a > b): tuple<A, B> |
| a: A, b: Unused --> (a > b): A |
| a: Unused, b: B --> (a > b): B |
| a: Unused, b: Unused --> (a > b): Unused |
| |
| a: A, b: A --> (a > b): vector<A> |
| a: vector<A>, b: A --> (a > b): vector<A> |
| a: A, b: vector<A> --> (a > b): vector<A> |
| a: vector<A>, b: vector<A> --> (a > b): vector<A>``]] |
| |
| [[`a | b`] |
| [``a: A, b: B --> (a | b): variant<A, B> |
| a: A, b: Unused --> (a | b): optional<A> |
| a: A, b: B, c: Unused --> (a | b | c): optional<variant<A, B> > |
| a: Unused, b: B --> (a | b): optional<B> |
| a: Unused, b: Unused --> (a | b): Unused |
| a: A, b: A --> (a | b): A``]] |
| |
| [[`a - b`] |
| [``a: A, b: B --> (a - b): A |
| a: Unused, b: B --> (a - b): Unused``]] |
| |
| [[`*a`] |
| [``a: A --> *a: vector<A> |
| a: Unused --> *a: Unused``]] |
| [[`+a`] |
| [``a: A --> +a: vector<A> |
| a: Unused --> +a: Unused``]] |
| |
| [[`a % b`] |
| [``a: A, b: B --> (a % b): vector<A> |
| a: Unused, b: B --> (a % b): Unused``]] |
| |
| [[`repeat(...,...)[a]`] |
| [``a: A --> repeat(...,...)[a]: vector<A> |
| a: Unused --> repeat(...,...)[a]: Unused``]] |
| |
| [[`a || b`] |
| [``a: A, b: B --> (a || b): tuple<optional<A>, optional<B> > |
| a: A, b: Unused --> (a || b): optional<A> |
| a: Unused, b: B --> (a || b): optional<B> |
| a: Unused, b: Unused --> (a || b): Unused |
| |
| a: A, b: A --> (a || b): vector<optional<A> >``]] |
| |
| [[`-a`] |
| [``a: A --> -a: optional<A> |
| a: Unused --> -a: Unused``]] |
| |
| [[`&a`] [`a: A --> &a: Unused`]] |
| [[`!b`] [`a: A --> !a: Unused`]] |
| |
| [[`a ^ b`] |
| [``a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> > |
| a: A, b: Unused --> (a ^ b): optional<A> |
| a: Unused, b: B --> (a ^ b): optional<B> |
| a: Unused, b: Unused --> (a ^ b): Unused``]] |
| |
| ] |
| |
| [endsect] |
| |
| [section:non_terminals Nonterminals] |
| |
| [variablelist Notation |
| [[`RT`] [Synthesized attribute. The rule or grammar's return type.]] |
| [[`Arg1`, `Arg2`, `ArgN`] [Inherited attributes. Zero or more arguments.]] |
| [[`L1`, `L2`, `LN`] [Zero or more local variables.]] |
| [[`r, r2`] [Rules]] |
| [[`g`] [A grammar]] |
| [[`p`] [A parser expression]] |
| [[`my_grammar`] [A user defined grammar]] |
| ] |
| |
| [variablelist Terminology |
| [[Signature] [`RT(Arg1, Arg2 ... ,ArgN)`. The signature specifies |
| the synthesized (return value) and inherited (arguments) |
| attributes.]] |
| [[Locals] [`locals<L1, L2 ..., LN>`. The local variables.]] |
| [[Skipper] [The skip-parser type]] |
| ] |
| |
| [variablelist Template Arguments |
| [[`Iterator`] [The iterator type you will use for parsing.]] |
| [[`A1`, `A2`, `A3`] [Can be one of 1) Signature 2) Locals 3) Skipper.]] |
| ] |
| |
| [table |
| [[Expression] [Description]] |
| [[`rule<Iterator, A1, A2, A3> r(name);`] [Rule declaration. `Iterator` is required. |
| `A1, A2, A3` are optional and can be specified in any order. |
| `name` is an optional string that gives the rule |
| its name, useful for debugging and error handling.]] |
| [[`rule<Iterator, A1, A2, A3> r(r2);`] [Copy construct rule `r` from rule `r2`.]] |
| [[`r = r2;`] [Assign rule `r2` to `r`.]] |
| [[`r.alias()`] [return an alias of `r`. The alias is a parser that |
| holds a reference to `r`. Reference semantics.]] |
| [[`r.copy()`] [Get a copy of `r`.]] |
| [[`r.name(name)`] [Naming a rule]] |
| [[`r.name()`] [Getting the name of a rule]] |
| [[debug(r)] [Debug rule `r`]] |
| [[`r = p;`] [Rule definition]] |
| [[`r %= p;`] [Auto-rule definition. The attribute of `p` should be |
| compatible with the synthesized attribute of `r`. When `p` |
| is successful, its attribute is automatically propagated |
| to `r`'s synthesized attribute.]] |
| |
| [[ |
| `` |
| template <typename Iterator> |
| struct my_grammar : grammar<Iterator, A1, A2, A3> |
| { |
| my_grammar() : my_grammar::base_type(start, name) |
| { |
| // Rule definitions |
| start = /* ... */; |
| } |
| |
| rule<Iterator, A1, A2, A3> start; |
| // more rule declarations... |
| }; |
| `` |
| ] [Grammar definition. `name` is an optional string that gives the |
| grammar its name, useful for debugging and error handling.]] |
| [[`g.name(name)`] [Naming a grammar]] |
| [[`g.name()`] [Getting the name of a grammar]] |
| ] |
| |
| [endsect] |
| [section Semantic Actions] |
| |
| Has the form: |
| |
| p[f] |
| |
| where `f` is a function with the signatures: |
| |
| void f(Attrib const&); |
| void f(Attrib const&, Context&); |
| void f(Attrib const&, Context&, bool&); |
| |
| You can use __boost_bind__ to bind member functions. For function |
| objects, the allowed signatures are: |
| |
| void operator()(Attrib const&, unused_type, unused_type) const; |
| void operator()(Attrib const&, Context&, unused_type) const; |
| void operator()(Attrib const&, Context&, bool&) const; |
| |
| The `unused_type` is used in the signatures above to signify 'don't |
| care'. |
| |
| For more detailed information about semantic actions see: |
| [link spirit.qi.tutorials.semantic_actions here]. |
| |
| [endsect] |
| [section Phoenix] |
| |
| __boost_phoenix__ makes it easier to attach semantic actions. You just |
| inline your lambda expressions: |
| |
| p[phoenix-lambda-expression] |
| |
| Spirit.Qi provides some __boost_phoenix__ placeholders to important |
| information from the `Attrib` and `Context` that are otherwise fiddly to extract. |
| |
| [variablelist Spirit.Qi specific Phoenix placeholders |
| [[`_1, _2... , _N`] [Nth attribute of `p`]] |
| [[`_val`] [The enclosing rule's synthesized attribute.]] |
| [[`_r1, _r2... , _rN`] [The enclosing rule's Nth inherited attribute.]] |
| [[`_a, _b... , _j`] [The enclosing rule's local variables (`_a` refers to the first).]] |
| [[`_pass`] [Assign `false` to `_pass` to force a parser failure.]] |
| ] |
| |
| [important All placeholders mentioned above are defined in the namespace |
| `boost::spirit` and, for your convenience, are available in the |
| namespace `boost::spirit::qi` as well.] |
| |
| For more detailed information about semantic actions see: |
| [link spirit.qi.tutorials.semantic_actions here]. |
| |
| [endsect] |
