|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r53089 - trunk/libs/spirit/doc/qi_and_karma
From: hartmut.kaiser_at_[hidden]
Date: 2009-05-18 11:46:06
Author: hkaiser
Date: 2009-05-18 11:46:06 EDT (Mon, 18 May 2009)
New Revision: 53089
URL: http://svn.boost.org/trac/boost/changeset/53089
Log:
Spirit: updated quick reference in docs
Text files modified:
trunk/libs/spirit/doc/qi_and_karma/quick_reference.qbk | 378 ++++++++++++++++++++++++++++++++++++---
1 files changed, 349 insertions(+), 29 deletions(-)
Modified: trunk/libs/spirit/doc/qi_and_karma/quick_reference.qbk
==============================================================================
--- trunk/libs/spirit/doc/qi_and_karma/quick_reference.qbk (original)
+++ trunk/libs/spirit/doc/qi_and_karma/quick_reference.qbk 2009-05-18 11:46:06 EDT (Mon, 18 May 2009)
@@ -8,36 +8,356 @@
[section Quick Reference]
-The following tables use some conventions to encode the attribute type exposed
-by a component
+[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]]
+ [[`Attr`] 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(Attr, Context, bool&)`.
+ The third parameter is a boolean flag that can be set to false to
+ force the parse to fail.]]
+ [[`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__)]]
+ [[`chset`] 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`]]
+]
+
+[table Predefined __qi__ primitive parsers
+ [[Expression] [Attribute] [Description]]
+ [[`eol`] [`Unused`] [Matches the end of line (\r or \n or \r\n)]]
+ [[`eoi`] [`Unused`] [Matches the end of input (first == last)]]
+ [[`eps`] [`Unused`] [Match an empty string]]
+ [[`eps(b)`] [`Unused`] [If `b` is true, match an empty string]]
+ [[`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]`]]
+ [[`p[fa]`] [Attribute of `p`] [Call semantic action, `fa` if p succeeds.]]
+
+ [[`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]]
+
+ [[`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_(chset)`] [`Ch`] [Matches a character set `chset`]]
+
+ [[`ch`] [`Unused`] [Matches `ch`]]
+ [[`str`] [`Unused`] [Matches `str`]]
+ [[`lit(ch)`] [`Unused`] [Matches `ch`]]
+ [[`lit(str)`] [`Unused`] [Matches `str`]]
+ [[`string(str)`] [`Str`] [Matches `str`]]
+
+ [[`lexeme[a]`] [`A`] [Disable skip parsing for `a`]]
+ [[`nocase[a]`] [`A`] [Inhibits case-sensitivity for `a`]]
+ [[`omit[a]`] [`Unused`] [Ignores the attribute type of `a`]]
+ [[`raw[a]`] [`boost::iterator_range<I>`][Presents the transduction of `a` as an iterator range]]
+
+ [[`repeat[a]`] [`std::vector<A>`] [Repeat `a` zero or more times]]
+ [[`repeat(N)[a]`] [`std::vector<A>`] [Repeat `a` `N` times]]
+ [[`repeat(N, M)[a]`] [`std::vector<A>`] [Repeat `a` `N` to `M` times]]
+ [[`repeat(N, inf)[a]`] [`std::vector<A>`] [Repeat `a` `N` or more times]]
+
+ [[`skip[a]`] [`A`] [Reestablish the skipper that got inhibited by lexeme]]
+ [[`skip(p)[a]`] [`A`] [Use `p` as a skipper for parsing `a`]]
+
+ [[`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]]
+
+ [[`!a`] [`Unused`] [Not predicate. Ensure that `a` does not match
+ but don't move the iterator position]]
+ [[`&a`] [`Unused`] [And predicate. Ensure that `a` matches
+ but don't move the iterator position]]
+ [[`-a`] [`boost::optional<A>`] [Optional. Parse `a` zero or one time]]
+ [[`*a`] [`std::vector<A>`] [Kleene. Parse `a` zero or more times]]
+ [[`+a`] [`std::vector<A>`] [Plus. Parse `a` one or more times]]
+ [[`a | b`] [`boost::variant<A, B>`] [Alternative. Parse `a` or `b`]]
+ [[`a >> b`] [`fusion::vector<A, B>`] [Sequence. Parse `a` followed by `b`]]
+ [[`a > b`] [`fusion::vector<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`] [`fusion::vector<A, B>`] [Sequential Or. Parse `a` or `b` or `a` followed by `b`]]
+ [[`a % b`] [`std::vector<A>`] [List. Parse `a` delimited `b` one or more times]]
+ [[`a ^ b`] [`fusion::vector<`
+ `boost::optional<A>,`
+ `boost::optional<B> >`
+ ] [Permutation. Parse `a` and `b` in any order]]
+]
+
+[table Predefined __karma__ primitive generators
+ [[Expression] [Attribute] [Description]]
+ [[`eol`] [`Unused`] [Generates the end of line (\n)]]
+ [[`eps`] [`Unused`] [Generate an empty string]]
+ [[`eps(b)`] [`Unused`] [If `b` is true, generate an empty string]]
+ [[`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.]
+ [[`fg`] [see `lazy(fg)` above] [Equivalent to `lazy[fp]`]]
+ [[`g[fa]`] [Attribute of `g`] [Call semantic action `fa` (before executing `g`).]]
+
+ [[`byte_`] [8 bits native endian] [Generates an 8 bit binary]]
+ [[`word`] [16 bits native endian] [Generates a 16 bit binary]]
+ [[`big_word`] [16 bits big endian] [Generates a 16 bit binary]]
+ [[`little_word`] [16 bits little endian] [Generates a 16 bit binary]]
+ [[`dword`] [32 bits native endian] [Generates a 32 bit binary]]
+ [[`big_dword`] [32 bits big endian] [Generates a 32 bit binary]]
+ [[`little_dword`] [32 bits little endian] [Generates a 32 bit binary]]
+ [[`qword`] [64 bits native endian] [Generates a 64 bit binary]]
+ [[`big_qword`] [64 bits big endian] [Generates a 64 bit binary]]
+ [[`little_qword`] [64 bits little endian] [Generates a 64 bit binary]]
+
+ [[`char_(ch)`] [`Ch`] [Generates `ch`]]
+ [[`char_("c")`] [`Ch`] [Generates a single char string literal, `c`]]
+
+ [[`ch`] [`Unused`] [Generates `ch`]]
+ [[`str`] [`Unused`] [Generates `str`]]
+ [[`lit(ch)`] [`Unused`] [Generates `ch`]]
+ [[`lit(str)`] [`Unused`] [Generates `str`]]
+ [[`string(str)`] [`Str`] [Generates `str`]]
+
+ [[`lower[a]`] [`A`] [Generate `a` as lower case]]
+ [[`upper[a]`] [`A`] [Generate `a` as upper case]]
+
+ [[`left_align[a]`] [`A`] [Generate `a` left aligned in column of width
+ BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+ [[`left_align(N)[a]`] [`A`] [Generate `a` left aligned in column of width `N`]]
+ [[`left_align(N, g)[a]`][`A`] [Generate `a` left aligned in column of width `N`
+ while using `g` to generate the necesssary
+ padding]]
+ [[`right_align[a]`] [`A`] [Generate `a` right aligned in column of width
+ BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+ [[`right_align(N)[a]`] [`A`] [Generate `a` right aligned in column of width `N`]]
+ [[`right_align(N, g)[a]`][`A`] [Generate `a` right aligned in column of width `N`
+ while using `g` to generate the necesssary
+ padding]]
+ [[`center[a]`] [`A`] [Generate `a` centered in column of width
+ BOOST_KARMA_DEFAULT_FIELD_LENGTH]]
+ [[`center(N)[a]`] [`A`] [Generate `a` centered in column of width `N`]]
+ [[`center(N, g)[a]`] [`A`] [Generate `a` centered in column of width `N`
+ while using `g` to generate the necesssary
+ padding]]
+
+ [[`maxwidth[a]`] [`A`] [Generate `a` truncated to column of width
+ BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH]]
+ [[`maxwidth(N)[a]`] [`A`] [Generate `a` truncated to column of width `N`]]
+
+ [[`repeat[a]`] [`std::vector<A>`] [Repeat `a` zero or more times]]
+ [[`repeat(N)[a]`] [`std::vector<A>`] [Repeat `a` `N` times]]
+ [[`repeat(N, M)[a]`] [`std::vector<A>`] [Repeat `a` `N` to `M` times]]
+ [[`repeat(N, inf)[a]`] [`std::vector<A>`] [Repeat `a` `N` or more times]]
+
+ [[`verbatim[a]`] [`A`] [Disable delimited generation for `a`]]
+ [[`delimit[a]`] [`A`] [Reestablish the delimiter that got inhibited by verbatim]]
+ [[`delimit(g)[a]`] [`A`] [Use `g` as a skipper for generating `a`]]
+
+ [[`float_`] [`float`] [Generate a floating point number from a `float`]]
+ [[`double_`] [`double`] [Generate a floating point number from a `double`]]
+ [[`long_double`] [`long double`] [Generate a floating point number from a `long double`]]
+
+ [[`bin`] [`unsigned`] [Generate a binary integer from an `unsigned`]]
+ [[`oct`] [`unsigned`] [Generate an octal integer from an `unsigned`]]
+ [[`hex`] [`unsigned`] [Generate a hexadecimal integer from an `unsigned`]]
+ [[`ushort_`] [`unsigned short`] [Generate an unsigned short integer]]
+ [[`ulong_`] [`unsigned long`] [Generate an unsigned long integer]]
+ [[`uint_`] [`unsigned int`] [Generate an unsigned int]]
+ [[`ulong_long`] [`unsigned long long`] [Generate an unsigned long long]]
+ [[`short_`] [`short`] [Generate a short integer]]
+ [[`long_`] [`long`] [Generate a long integer]]
+ [[`int_`] [`int`] [Generate an int]]
+ [[`long_long`] [`long long`] [Generate a long long]]
+
+ [[`!a`] [`Unused`] [Not predicate. Ensure that `a` does not succeed
+ generating but don't create any output]]
+ [[`&a`] [`Unused`] [And predicate. Ensure that `a` does succeed
+ generating but don't create any output]]
+ [[`-a`] [`boost::optional<A>`] [Optional. Generate `a` zero or one time]]
+ [[`*a`] [`std::vector<A>`] [Kleene. Generate `a` zero or more times]]
+ [[`+a`] [`std::vector<A>`] [Plus. Generate `a` one or more times]]
+ [[`a | b`] [`boost::variant<A, B>`] [Alternative. Generate `a` or `b`]]
+ [[`a << b`] [`fusion::vector<A, B>`] [Sequence. Generate `a` followed by `b`]]
+ [[`a % b`] [`std::vector<A>`] [List. Generate `a` delimited `b` one or more times]]
+]
+
+[heading Compound Attribute Rules]
+
+The notation will be for instance:
+
+ a: A, b: B --> (a >> b): tuple<A, B>
+
+which reads as: given, `a` and `b` are parsers/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>`.
+
+Note: `tuple<>` is used as a placeholder for a fusion sequence
+ `vector<>` is used as a placeholder for a STL container
+ `none` stands for not having any attribute (attribute type is `unused`)
+
+
+[table __qi__ compound parser attribute types
+ [[Expression] [Attribute]]
+ [[sequence (`>>`)] [`a: A, b: B --> (a >> b): tuple<A, B>`
+ `a: A, b: none --> (a >> b): A`
+ `a: none, b: B --> (a >> b): B`
+ `a: none, b: none --> (a >> b): none`
+ `a: A, b: A --> (a >> b): vector<A>`]]
+ [[expect (`>`)] [`a: A, b: B --> (a > b): tuple<A, B>`
+ `a: A, b: none --> (a > b): A`
+ `a: none, b: B --> (a > b): B`
+ `a: none, b: none --> (a > b): none`
+ `a: A, b: A --> (a > b): vector<A>`]]
+ [[alternative (`|`)] [`a: A, b: B --> (a | b): variant<A, B>`
+ `a: A, b: none --> (a | b): variant<none, A>`
+ `a: none, b: B --> (a | b): variant<none, B>`
+ `a: none, b: none --> (a | b): none`
+ `a: A, b: A --> (a | b): A`]]
+ [[difference (`-`)] [`a: A, b: B --> (a - b): A`]]
+ [[kleene (`*`)] [`a: A --> *a: vector<A>`
+ `a: none --> a: none`]]
+ [[plus (`+`)] [`a: A --> +a: vector<A>`
+ `a: none --> a: none`]]
+ [[list (`%`)] [`a: A, b: B --> (a % b): vector<A>`
+ `a: none, b: B --> (a % b): none`]]
+ [[repetition] [`a: A --> repeat(...,...)[a]: vector<A>`
+ `a: none --> repeat(...,...)[a]: none`]]
+ [[sequential or (`||`)] [`a: A, b: B --> (a || b): tuple<optional<A>, optional<B> >`
+ `a: A, b: none --> (a || b): optional<A>`
+ `a: none, b: B --> (a || b): optional<B>`
+ `a: none, b: none --> (a || b): none`]]
+ [[optional (`-`)] [`a: A --> -a: optional<A>`
+ `a: none --> -a: none`]]
+ [[and predicate (`&`)] [`a: A --> &a: none`]]
+ [[not predicate (`!`)] [`a: A --> !a: none`]]
+ [[permutation (`^`)] [`a: A, b: B --> (a ^ b): tuple<optional<A>, optional<B> >`
+ `a: A, b: none --> (a ^ b): optional<A>`
+ `a: none, b: B --> (a ^ b): optional<B>`
+ `a: none, b: none --> (a ^ b): none`]]
+]
+
+[table __karma__ compound generator attribute types
+ [[Expression] [Attribute]]
+ [[sequence (`<<`)] [`a: A, b: B --> (a << b): tuple<A, B>`
+ `a: A, b: none --> (a << b): A`
+ `a: none, b: B --> (a << b): B`
+ `a: none, b: none --> (a << b): none`
+ `a: A, b: A --> (a << b): vector<A>`]]
+ [[alternative (`|`)] [`a: A, b: B --> (a | b): variant<A, B>`
+ `a: A, b: none --> (a | b): variant<none, A>`
+ `a: none, b: B --> (a | b): variant<none, B>`
+ `a: none, b: none --> (a | b): none`
+ `a: A, b: A --> (a | b): A`]]
+ [[kleene (`*`)] [`a: A --> *a: vector<A>`
+ `a: none --> a: none`]]
+ [[plus (`+`)] [`a: A --> +a: vector<A>`
+ `a: none --> a: none`]]
+ [[list (`%`)] [`a: A, b: B --> (a % b): vector<A>`
+ `a: none, b: B --> (a % b): none`]]
+ [[repetition] [`a: A --> repeat(...,...)[a]: vector<A>`
+ `a: none --> repeat(...,...)[a]: none`]]
+ [[optional (`-`)] [`a: A --> -a: optional<A>`
+ `a: none --> -a: none`]]
+ [[and predicate (`&`)] [`a: A --> &a: none`]]
+ [[not predicate (`!`)] [`a: A --> !a: none`]]
+]
+
+
+[heading Lazy Arguments]
+
+For all expressions of the form:
+
+ p(a1, a2,... aN)
+
+where `p` is a parser, each of the arguments (a1...aN) can either be
+an immediate value, or a lazy function with signature:
+
+ T(Unused, Context)
+
+where `T`, the function's return value, is compatible with the argument
+type expected. For example, this is a valid expression:
+
+ eps(false) // this will always fail
+
+And so is this:
+
+ bool flag = true;
+ eps(phoenix::var(flag)) // success or fail depending on the value
+ // of flag at parse time
+
+since `phoenix::ref(f)` is a function that returns a `bool`.
+
+[heading Non-terminals]
+
+[variablelist Notation
+ [[`RT`] Synthesized attribute. The rule or grammar's return type.]]
+ [[`Arg1`, `Arg2`, `ArgN`] Inherited attributes. Zero or more or arguments.]]
+ [[`L1`, `L2`, `LN`] Zero or more local variables.]]
+ [[`r, r2`] Rules]]
+ [[`g`] A grammar]]
+ [[`p`] A parser expression]]
+]
+
+[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.]]
+]
-[variablelist
- [[`attribute_of(P)`] [The component exposes the same attribute as the
- component 'P' used as part of the overall
- construct]]
- [[`value_type(I)`] [The component exposes the value_type of the
- underlying iterator 'I' as its attribute type]]
-]
-
-[table Character Parsers
- [[Component] [Description] [Attribute]]
- [[`char_`] [] [`char`]]
- [[`wchar`] [] [`wchar_t`]]
- [[`lit`] [] [`unused`]]
- [[`wlit`] [] [`unused`]]
- [[`'x'`] [] [`unused`]]
- [[`L'x'`] [] [`unused`]]
- [[`alnum`] [] [`Char`]]
- [[`alpha`] [] [`Char`]]
- [[`blank`] [] [`Char`]]
- [[`cntrl`] [] [`Char`]]
- [[`digit`] [] [`Char`]]
- [[`graph`] [] [`Char`]]
- [[`print`] [] [`Char`]]
- [[`punct`] [] [`Char`]]
- [[`space`] [] [`Char`]]
- [[`xdigit`] [] [`Char`]]
- [[`~P`] [] [`attribute_of(P)`]]
+[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 nonterminal
+ its name, useful for debugging and error handling.]]
+ [[`rule<Iterator, A1, A2, A3> r(r2);`] [Copy construct rule `r` from rule `r2`. `boost::shared_ptr` semantics.]]
+ [[`r = r2;`] [Assign rule `r2` to `r`. `boost::shared_ptr` semantics.]]
+ [[`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`. `boost::shared_ptr` semantics.]]
+ [[`r.name(name)`] [Naming 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.]]
]
[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk