| [/============================================================================== |
| 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 sort of a "cheat-sheet" on the most commonly used Karma |
| 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 upon pages of reference documentation. |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section Common Notation] |
| |
| [variablelist Notation |
| [[`G`] [Generator type]] |
| [[`g, a, b, c, d`] [Generator objects]] |
| [[`A, B, C, D`] [Attribute types of generators `a`, `b`, `c`, and `d`]] |
| [[`I`] [The iterator type used for generation]] |
| [[`Unused`] [An `unused_type`]] |
| [[`Context`] [The enclosing rule's `Context` type]] |
| [[`attrib`] [An attribute value]] |
| [[`Attrib`] [An attribute type]] |
| [[`b`] [A boolean expression]] |
| [[`B`] [A type to be interpreted in boolean expressions]] |
| [[`fg`] [A (lazy generator) function with signature `G(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 generator to fail. Both `Context` and the boolean flag are |
| optional.]] |
| [[`outiter`] [An output iterator to receive the generated output]] |
| [[`Ch`] [Character-class specific character type (See __char_class_types__)]] |
| [[`ch, 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`]] |
| [[`num`] [Numeric literal, any integer or real number type]] |
| [[`Num`] [Attribute of `num`: any integer or real number type]] |
| [[`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:primitive_generators Karma Generators] |
| |
| [section:char Character Generators] |
| |
| See here for more information about __karma_char__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_char `ch`]] [`Unused`] [Generate `ch`]] |
| [[[karma_char `lit(ch)`]] [`Unused`] [Generate `ch`]] |
| |
| [[[karma_char `char_`]] [`Ch`] [Generate character supplied as the attribute]] |
| [[[karma_char `char_(ch)`]] [`Ch`] [Generate `ch`, |
| if an attribute is supplied it must match]] |
| [[[karma_char `char_("c")`]] [`Ch`] [Generate a single char string literal, `c`, |
| if an attribute is supplied it must match]] |
| [[[karma_char `char_(ch, ch2)`]][`Ch`] [Generate the character supplied as the attribute, |
| if it belongs to the character range from |
| `ch` to `ch2`]] |
| [[[karma_char `char_(charset)`]][`Ch`] [Generate the character supplied as the attribute, |
| if it belongs to the character set `charset`]] |
| |
| [[[karma_char_class `alnum`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isalnum` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `alpha`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isalpha` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `blank`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isblank` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `cntrl`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::iscntrl` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `digit`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isdigit` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `graph`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isgraph` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `print`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isprint` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `punct`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::ispunct` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `space`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isspace`, or |
| a single space character in the character set |
| defined by `NS`]] |
| [[[karma_char_class `xdigit`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isxdigit` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `lower`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::islower` in |
| the character set defined by `NS`]] |
| [[[karma_char_class `upper`]] [`Ch`] [Generate the character supplied as the attribute |
| if it satisfies the concept of `std::isupper` in |
| the character set defined by `NS`]] |
| ] |
| |
| [endsect] |
| |
| [section:string String Generators] |
| |
| See here for more information about [karma_string String Generators]. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_string `str`]] [`Unused`] [Generate `str`]] |
| [[[karma_string `lit(str)`]] [`Unused`] [Generate `str`]] |
| [[[karma_string `string`]] [`Str`] [Generate string supplied as the attribute]] |
| [[[karma_string `string(str)`]] [`Str`] [Generate `str`, |
| if an attribute is supplied it must match]] |
| |
| [[__karma_symbols__`<Attr, T>`] [`Attr`] [Declare a symbol table, `sym`. `Attr` is the |
| The type of the original attribute to be used |
| as the key into the symbol generator. |
| `T` is the data type associated with each key.]] |
| [[ |
| `` |
| sym.add |
| (attr1, val1) |
| (attr2, 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`] [Emits entries in the symbol table, `sym`. If |
| attribute is found in the symbol table, |
| the corresponding value is emitted. If `sym` |
| does not store values, the original attribute |
| is emitted.]] |
| ] |
| |
| [endsect] |
| |
| [section:real_number Real Number Generators] |
| |
| See here for more information about __karma_numeric__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[real_number `lit(num)`]] [`Unused`] [Generate `num`]] |
| [[[real_number `float_`]] [`float`] [Generate a real number from a `float`]] |
| [[[real_number `float_(num)`]] [`float`] [Generate `num` as a real number from a `float`, |
| if an attribute is supplied it must match]] |
| [[[real_number `double_`]] [`double`] [Generate a real number from a `double`]] |
| [[[real_number `double_(num)`]] [`double`] [Generate a `num` as a real number from a `double`, |
| if an attribute is supplied it must match]] |
| [[[real_number `long_double`]] [`long double`] [Generate a real number from a `long double`]] |
| [[[real_number `long_double(num)`]] [`long double`] [Generate `num` as a real number from a `long double`, |
| if an attribute is supplied it must match]] |
| |
| [[[real_number ``real_generator< |
| Num, Policies |
| >()``]] |
| [`Num`] [Generate a real number `Num` using |
| the supplied real number formatting policies]] |
| [[[real_number ``real_generator< |
| Num, Policies |
| >()(num)``]] |
| [`Num`] [Generate real number `num` as a `Num` |
| using the supplied real number formatting |
| policies, if an attribute is supplied it must |
| match]] |
| ] |
| |
| [endsect] |
| |
| [section:signed_int Integer Generators] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[signed_int `lit(num)`]] [`Unused`] [Generate `num`]] |
| [[[signed_int `short_`]] [`short`] [Generate a short integer]] |
| [[[signed_int `short_(num)`]] [`short`] [Generate `num` as a short integer, |
| if an attribute is supplied it must match]] |
| [[[signed_int `int_`]] [`int`] [Generate an int]] |
| [[[signed_int `int_(num)`]] [`int`] [Generate `num` as an int, |
| if an attribute is supplied it must match]] |
| [[[signed_int `long_`]] [`long`] [Generate a long integer]] |
| [[[signed_int `long_(num)`]] [`long`] [Generate `num` as long integer, |
| if an attribute is supplied it must match]] |
| [[[signed_int `long_long`]] [`long long`] [Generate a long long]] |
| [[[signed_int `long_long(num)`]] [`long long`] [Generate `num` as a long long, |
| if an attribute is supplied it must match]] |
| |
| [[[signed_int ``int_generator< |
| Num, Radix, force_sign |
| >()``]] |
| [`Num`] [Generate a `Num`]] |
| [[[signed_int ``int_generator< |
| Num, Radix, force_sign |
| >()(num)``]] |
| [`Num`] [Generate a `num` as a `Num`, |
| if an attribute is supplied it must match]] |
| ] |
| |
| [endsect] |
| |
| [section:unsigned_int Unsigned Integer Generators] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[unsigned_int `lit(num)`]] [`Unused`] [Generate `num`]] |
| [[[unsigned_int `ushort_`]] [`unsigned short`] [Generate an unsigned short integer]] |
| [[[unsigned_int `ushort_(num)`]] [`unsigned short`] [Generate `num` as an unsigned short integer, |
| if an attribute is supplied it must match]] |
| [[[unsigned_int `uint_`]] [`unsigned int`] [Generate an unsigned int]] |
| [[[unsigned_int `uint_(num)`]] [`unsigned int`] [Generate `num` as an unsigned int, |
| if an attribute is supplied it must match]] |
| [[[unsigned_int `ulong_`]] [`unsigned long`] [Generate an unsigned long integer]] |
| [[[unsigned_int `ulong_(num)`]] [`unsigned long`] [Generate `num` as an unsigned long integer, |
| if an attribute is supplied it must match]] |
| [[[unsigned_int `ulong_long`]] [`unsigned long long`] [Generate an unsigned long long]] |
| [[[unsigned_int `ulong_long(num)`]] [`unsigned long long`] [Generate `num` as an unsigned long long, |
| if an attribute is supplied it must match]] |
| [[[unsigned_int `bin`]] [`unsigned int`] [Generate a binary integer from an `unsigned int`]] |
| [[[unsigned_int `oct`]] [`unsigned int`] [Generate an octal integer from an `unsigned int`]] |
| [[[unsigned_int `hex`]] [`unsigned int`] [Generate a hexadecimal integer from an `unsigned int`]] |
| |
| [[[unsigned_int ``uint_generator< |
| Num, Radix |
| >()``]] |
| [`Num`] [Generate an unsigned `Num`]] |
| [[[unsigned_int ``uint_generator< |
| Num, Radix |
| >()(num)``]] |
| [`Num`] [Generate an unsigned `num` as a `Num`, |
| if an attribute is supplied it must match]] |
| ] |
| |
| [endsect] |
| |
| [section:boolean Boolean Generators] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[boolean `lit(num)`]] [`Unused`] [Generate `num`]] |
| [[[boolean `bool_`]] [`bool`] [Generate a boolean]] |
| [[[boolean `bool_(b)`]] [`bool`] [Generate `b` as a boolean, |
| if an attribute is supplied it must match]] |
| [[[boolean ``bool_generator< |
| B, Policies |
| >()``]] |
| [`B`] [Generate a boolean of type `B`]] |
| [[[boolean ``bool_generator< |
| B, Policies |
| >()(b)``]] |
| [`B`] [Generate a boolean `b` as a `B`, |
| if an attribute is supplied it must match]] |
| ] |
| |
| [endsect] |
| |
| [section:stream Stream Generators] |
| |
| See here for more information about [karma_stream Stream Generators]. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_stream `stream`]] [`hold_any`] [Generate narrow character (`char`) based output |
| using the matching streaming `operator<<()`]] |
| [[[karma_stream `stream(s)`]] [`Unused`] [Generate narrow character (`char`) based output |
| from the immediate argument `s` using the matching |
| streaming `operator<<()`]] |
| [[[karma_stream `wstream`]] [`hold_any`] [Generate wide character (`wchar_t`) based output |
| using the matching streaming `operator<<()`]] |
| [[[karma_stream `wstream(s)`]] [`Unused`] [Generate wide character (`wchar_t`) based output |
| from the immediate argument `s` using the matching |
| streaming `operator<<()`]] |
| [ |
| [[karma_stream ``stream_generator< |
| Char |
| >()``]] [`hold_any`] [Generate output based on the given character type |
| (`Char`) using the matching streaming `operator<<()`]] |
| [ |
| [[karma_stream ``stream_generator< |
| Char |
| >()(s)``]] [`Unused`] [Generate output based on the given character type |
| `Char` from the immediate argument `s` using the |
| matching streaming `operator<<()`]] |
| ] |
| |
| [endsect] |
| |
| [section:binary Binary Generators] |
| |
| See here for more information about __karma_binary__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_native_binary `byte_`]] [8 bits native endian] [Generate an 8 bit binary]] |
| [[[karma_native_binary `word`]] [16 bits native endian] [Generate a 16 bit binary in native endian representation]] |
| [[[karma_big_binary `big_word`]] [16 bits big endian] [Generate a 16 bit binary in big endian representation]] |
| [[[karma_little_binary `little_word`]] [16 bits little endian] [Generate a 16 bit binary in little endian representation]] |
| [[[karma_native_binary `dword`]] [32 bits native endian] [Generate a 32 bit binary in native endian representation]] |
| [[[karma_big_binary `big_dword`]] [32 bits big endian] [Generate a 32 bit binary in big endian representation]] |
| [[[karma_little_binary `little_dword`]][32 bits little endian] [Generate a 32 bit binary in little endian representation]] |
| [[[karma_native_binary `qword`]] [64 bits native endian] [Generate a 64 bit binary in native endian representation]] |
| [[[karma_big_binary `big_qword`]] [64 bits big endian] [Generate a 64 bit binary in big endian representation]] |
| [[[karma_little_binary `little_qword`]][64 bits little endian] [Generate a 64 bit binary in little endian representation]] |
| [[`pad(num)`] [`Unused`] [Generate additional null bytes allowing to align generated |
| output with memory addresses divisible by `num`.]] |
| ] |
| |
| [endsect] |
| |
| [section:auxiliary Auxiliary Generators] |
| |
| See here for more information about __karma_auxiliary__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_attr_cast `attr_cast<Exposed>(a)`]] [`Exposed`] [Invoke `a` while supplying an attribute of type `Exposed`.]] |
| [[__karma_eol__] [`Unused`] [Generate the end of line (`\n`)]] |
| [[__karma_eps__] [`Unused`] [Generate an empty string]] |
| [[__karma_feps__] [`Unused`] [If `b` is true, generate an empty string]] |
| [[[karma_lazy `lazy(fg)`]] |
| [Attribute of `G` where `G` |
| is the return type of `fg`] [Invoke `fg` at generation time, returning a generator |
| `g` which is then called to generate.]] |
| [[[karma_lazy `fg`]] [see [karma_lazy `lazy(fg)`] above] [Equivalent to [karma_lazy `lazy(fg)`]]] |
| ] |
| |
| [endsect] |
| |
| [section:auto Auto Generators] |
| |
| See here for more information about [karma_auto Auto Generators]. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_auto `auto_`]] [`hold_any`] [Generate output using a generator |
| created from the supplied attribute type |
| using the __create_generator__ API function.]] |
| ] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:operators Generator Operators] |
| |
| See here for more information about __karma_operator__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[link spirit.karma.reference.operator.not_predicate `!a`]] |
| [`A`] [Not predicate. Ensure that `a` does not succeed |
| generating, but don't create any output]] |
| [[[link spirit.karma.reference.operator.not_predicate `&a`]] |
| [`A`] [And predicate. Ensure that `a` does succeed |
| generating, but don't create any output]] |
| [[[link spirit.karma.reference.operator.optional `-a`]] |
| [`optional<A>`] [Optional. Generate `a` zero or one time]] |
| [[[link spirit.karma.reference.operator.kleene `*a`]] |
| [`vector<A>`] [Kleene. Generate `a` zero or more times]] |
| [[[link spirit.karma.reference.operator.plus `+a`]] |
| [`vector<A>`] [Plus. Generate `a` one or more times]] |
| [[[link spirit.karma.reference.operator.alternative `a | b`]] |
| [`variant<A, B>`] [Alternative. Generate `a` or `b`]] |
| [[[link spirit.karma.reference.operator.sequence `a << b`]] |
| [`tuple<A, B>`] [Sequence. Generate `a` followed by `b`]] |
| [[[link spirit.karma.reference.operator.list `a % b`]] |
| [`vector<A>`] [List. Generate `a` delimited `b` one or more times]] |
| ] |
| |
| [:For more information about the attribute propagation rules implemented by the |
| compound generators please see __sec_karma_compound__.] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:directives Generator Directives] |
| |
| See here for more information about __karma_directive__. |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[[karma_upperlower `lower`]`[a]`] [`A`] [Generate `a` as lower case]] |
| [[[karma_upperlower `upper`]`[a]`] [`A`] [Generate `a` as upper case]] |
| |
| [[[karma_align `left_align`]`[a]`] [`A`] [Generate `a` left aligned in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]] |
| [[[karma_align `left_align`]`(num)[a]`] [`A`] [Generate `a` left aligned in column of width `num`]] |
| [[[karma_align `left_align`]`(g)[a]`] [`A`] [Generate `a` left aligned in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to |
| generate the necessary padding]] |
| [[[karma_align `left_align`]`(num, g)[a]`][`A`] [Generate `a` left aligned in column of width `num` |
| while using `g` to generate the necessary |
| padding]] |
| |
| [[[karma_align `center`]`[a]`] [`A`] [Generate `a` centered in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]] |
| [[[karma_align `center`]`(num)[a]`] [`A`] [Generate `a` centered in column of width `num`]] |
| [[[karma_align `center`]`(g)[a]`] [`A`] [Generate `a` centered in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to |
| generate the necessary padding]] |
| [[[karma_align `center`]`(num, g)[a]`] [`A`] [Generate `a` centered in column of width `num` |
| while using `g` to generate the necessary |
| padding]] |
| |
| [[[karma_align `right_align`]`[a]`] [`A`] [Generate `a` right aligned in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH`]] |
| [[[karma_align `right_align`]`(num)[a]`] [`A`] [Generate `a` right aligned in column of width `num`]] |
| [[[karma_align `right_align`]`(g)[a]`] [`A`] [Generate `a` right aligned in column of width |
| `BOOST_KARMA_DEFAULT_FIELD_LENGTH` while using `g` to |
| generate the necessary padding]] |
| [[[karma_align `right_align`]`(num, g)[a]`][`A`][Generate `a` right aligned in column of width `num` |
| while using `g` to generate the necessary |
| padding]] |
| |
| [[[karma_maxwidth `maxwidth`]`[a]`] [`A`] [Generate `a` truncated to column of width |
| `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`]] |
| [[[karma_maxwidth `maxwidth`]`(num)[a]`] [`A`] [Generate `a` truncated to column of width `num`]] |
| |
| [[[karma_repeat `repeat`]`[a]`] [`vector<A>`] [Repeat `a` zero or more times]] |
| [[[karma_repeat `repeat`]`(num)[a]`] [`vector<A>`] [Repeat `a` `num` times]] |
| [[[karma_repeat `repeat`]`(num1, num2)[a]`] [`vector<A>`] [Repeat `a` `num1` to `num2` times]] |
| [[[karma_repeat `repeat`]`(num, inf)[a]`] [`vector<A>`] [Repeat `a` `num` or more times]] |
| |
| [[__karma_verbatim__`[a]`][`A`] [Disable delimited generation for `a`. Performs post delimiting.]] |
| [[[karma_delimit `delimit`]`[a]`] [`A`] [Reestablish the delimiter that got inhibited by verbatim]] |
| [[[karma_delimit `delimit`]`(d)[a]`] [`A`] [Use `d` as a delimiter for generating `a`]] |
| [[[karma_no_delimit `no_delimit`]`[a]`] [`A`] [Disable delimited generation for `a`. No post-delimiting step performed.]] |
| |
| [[__karma_omit__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything. |
| The embedded generator will be always executed.]] |
| [[__karma_skip__`[a]`] [`A`] [Consume the attribute type of `a` without generating anything. |
| The embedded generator will never be executed.]] |
| |
| [[__karma_duplicate__`[a]`] [`A`] [The supplied attribute will be duplicated and passed unchanged to |
| all embedded elements of a sequence.]] |
| |
| [[__karma_buffer__`[a]`][`A`] [Temporarily intercept the output generated by `a`, |
| flushing it only after `a` succeeded]] |
| |
| [[[karma_columns `columns`]`[a]`] [`A`] [Generate `a` split into |
| `BOOST_KARMA_DEFAULT_COLUMNS` number of columns using |
| `karma::eol` as column delimiter]] |
| [[[karma_columns `columns`]`(num)[a]`] [`A`] [Generate `a` split into |
| `num` number of columns using |
| `karma::eol` as column delimiter]] |
| [[[karma_columns `columns`]`(g)[a]`] [`A`] [Generate `a` split into |
| `BOOST_KARMA_DEFAULT_COLUMNS` number of columns using |
| `g` as column delimiter]] |
| [[[karma_columns `columns`]`(num, g)[a]`][`A`][Generate `a` split into |
| `num` number of columns using |
| `g` as column delimiter]] |
| ] |
| |
| [endsect] |
| |
| [section:action Generator Semantic Actions] |
| |
| [table |
| [[Expression] [Attribute] [Description]] |
| [[`g[fa]`] [Attribute of `g`] [Call semantic action `fa` before invoking `g`]] |
| ] |
| |
| [endsect] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section Compound Attribute Rules] |
| |
| [heading Notation] |
| |
| The notation we use is 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> |
| |
| which reads as: given, `a` and `b` are generators, 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. The notation of `variant<A, B, ...>` stands for |
| ['a __boost_variant__] capable of holding `A`, `B`, ... etc. elements. Finally, |
| `Unused` stands for __unused_type__. ] |
| |
| [heading Compound Generator Attribute Types] |
| |
| [table |
| [[Expression] [Attribute]] |
| |
| [[__karma_sequence__] |
| [``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>``]] |
| |
| [[__karma_alternative__] |
| [``a: A, b: B --> (a | b): variant<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): A``]] |
| |
| [[[karma_kleene Kleene (unary `*`)]] |
| [``a: A --> *a: vector<A> |
| a: Unused --> *a: Unused``]] |
| [[__karma_plus__] |
| [``a: A --> +a: vector<A> |
| a: Unused --> +a: Unused``]] |
| |
| [[__karma_list__] |
| [``a: A, b: B --> (a % b): vector<A> |
| a: Unused, b: B --> (a % b): Unused``]] |
| |
| [[[karma_repeat Repetition]] |
| [``a: A --> repeat(...,...)[a]: vector<A> |
| a: Unused --> repeat(...,...)[a]: Unused``]] |
| |
| [[__karma_optional__] |
| [``a: A --> -a: optional<A> |
| a: Unused --> -a: Unused``]] |
| |
| [[__karma_and_predicate__] [`a: A --> &a: A`]] |
| [[__karma_not_predicate__] [`a: A --> !a: A`]] |
| ] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section:non_terminals Nonterminals] |
| |
| See here for more information about __karma_nonterminal__. |
| |
| [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 generator 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.]] |
| [[Delimiter] [The delimit-generator 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) Delimiter.]] |
| ] |
| |
| [table |
| [[Expression] [Description]] |
| [[`rule<OutputIterator, A1, A2, A3> r(name);`] [Rule declaration. `OutputIterator` 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.]] |
| [[`rule<OutputIterator, A1, A2, A3> r(r2);`] [Copy construct rule `r` from rule `r2`.]] |
| [[`r = r2;`] [Assign rule `r2` to `r`. `boost::shared_ptr` semantics.]] |
| [[`r.alias()`] [Return an alias of `r`. The alias is a generator that |
| holds a reference to `r`. Reference semantics.]] |
| [[`r.copy()`] [Get a copy of `r`.]] |
| [[`r.name(name)`] [Set the name of a rule]] |
| [[`r.name()`] [Get the name of a rule]] |
| [[debug(r)] [Debug rule `r`]] |
| [[`r = g;`] [Rule definition]] |
| [[`r %= g;`] [Auto-rule definition. The attribute of `g` should be |
| compatible with the synthesized attribute of `r`. When `g` |
| is successful, its attribute is automatically propagated |
| to `r`'s synthesized attribute.]] |
| |
| [[ |
| `` |
| template <typename OutputIterator> |
| struct my_grammar : grammar<OutputIterator, A1, A2, A3> |
| { |
| my_grammar() : my_grammar::base_type(start, name) |
| { |
| // Rule definitions |
| start = /* ... */; |
| } |
| |
| rule<OutputIterator, A1, A2, A3> start; |
| // more rule declarations... |
| }; |
| `` |
| ] [Grammar definition. `name` is an optional string that gives the |
| grammar its name, useful for debugging.]] |
| [[my_grammar<OutputIterator> g] [Instantiate a grammar]] |
| [[`g.name(name)`] [Set the name of a grammar]] |
| [[`g.name()`] [Get the name of a grammar]] |
| ] |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section Semantic Actions] |
| |
| Semantic Actions may be attached to any generator as follows: |
| |
| g[f] |
| |
| where `f` is a function with the signatures: |
| |
| void f(Attrib&); |
| void f(Attrib&, Context&); |
| void f(Attrib&, Context&, bool&); |
| |
| You can use __boost_bind__ to bind member functions. For function |
| objects, the allowed signatures are: |
| |
| void operator()(Attrib&, unused_type, unused_type) const; |
| void operator()(Attrib&, Context&, unused_type) const; |
| void operator()(Attrib&, Context&, bool&) const; |
| |
| The `unused_type` is used in the signatures above to signify 'don't |
| care'. |
| |
| For more information see __karma_actions__. |
| |
| [endsect] |
| |
| [/////////////////////////////////////////////////////////////////////////////] |
| [section Phoenix] |
| |
| __boost_phoenix__ makes it easier to attach semantic actions. You just |
| inline your lambda expressions: |
| |
| g[phoenix-lambda-expression] |
| |
| __karma__ provides some __boost_phoenix__ placeholders to access important |
| information from the `Attrib` and `Context` that are otherwise fiddly to extract. |
| |
| [variablelist Spirit.Karma specific Phoenix placeholders |
| [[`_1, _2, ... , _N`] [Nth attribute of `g`]] |
| [[`_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 generator failure.]] |
| ] |
| |
| [important All placeholders mentioned above are defined in the namespace |
| `boost::spirit` and, for your convenience, are available in the |
| namespace `boost::spirit::karma` as well.] |
| |
| For more information see __karma_actions__. |
| |
| [endsect] |
| |
| |
