123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372 |
- [/==============================================================================
- Copyright (C) 2001-2011 Joel de Guzman
- Copyright (C) 2001-2011 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 X3
- 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(Context&)`.]]
- [[`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:char Character Parsers]
- [table
- [[Expression] [Attribute] [Description]]
- [[[x3_char `ch`]] [`Unused`] [Matches `ch`]]
- [[[x3_char `lit(ch)`]] [`Unused`] [Matches `ch`]]
- [[[x3_char `char_`]] [`Ch`] [Matches any character]]
- [[[x3_char `char_(ch)`]] [`Ch`] [Matches `ch`]]
- [[[x3_char `char_("c")`]] [`Ch`] [Matches a single char string literal, `c`]]
- [[[x3_char `char_(ch, ch2)`]][`Ch`] [Matches a range of chars from `ch` to `ch2` (inclusive)]]
- [[[x3_char `char_(charset)`]][`Ch`] [Matches a character set `charset`]]
- [[[x3_char_class `alnum`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isalnum` in the current character set]]
- [[[x3_char_class `alpha`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isalpha` in the current character set]]
- [[[x3_char_class `blank`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isblank` in the current character set]]
- [[[x3_char_class `cntrl`]] [`Ch`] [Matches a character based on the equivalent of
- `std::iscntrl` in the current character set]]
- [[[x3_char_class `digit`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isdigit` in the current character set]]
- [[[x3_char_class `graph`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isgraph` in the current character set]]
- [[[x3_char_class `print`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isprint` in the current character set]]
- [[[x3_char_class `punct`]] [`Ch`] [Matches a character based on the equivalent of
- `std::ispunct` in the current character set]]
- [[[x3_char_class `space`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isspace` in the current character set]]
- [[[x3_char_class `xdigit`]] [`Ch`] [Matches a character based on the equivalent of
- `std::isxdigit` in the current character set]]
- [[[x3_char_class `lower`]] [`Ch`] [Matches a character based on the equivalent of
- `std::islower` in the current character set]]
- [[[x3_char_class `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]]
- [[[x3_real_number `float_`]] [`float`] [Parse a floating point number into a `float`]]
- [[[x3_real_number `float_(num)`]] [`float`] [Parse a floating point number into a `float`,
- a number is matched only if it's `num`]]
- [[[x3_real_number `double_`]] [`double`] [Parse a floating point number into a `double`]]
- [[[x3_real_number `double_(num)`]] [`double`] [Parse a floating point number into a `double`,
- a number is matched only if it's `num`]]
- [[[x3_real_number `long_double`]] [`long double`] [Parse a floating point number into a `long double`]]
- [[[x3_real_number `long_double(num)`]] [`long double`] [Parse a floating point number into a `long double`,
- a number is matched only if it's `num`]]
- [[[x3_unsigned_int `bin`]] [`unsigned`] [Parse a binary integer into an `unsigned`]]
- [[[x3_unsigned_int `oct`]] [`unsigned`] [Parse an octal integer into an `unsigned`]]
- [[[x3_unsigned_int `hex`]] [`unsigned`] [Parse a hexadecimal integer into an `unsigned`]]
- [[[x3_unsigned_int `ushort_`]] [`unsigned short`] [Parse an unsigned short integer]]
- [[[x3_unsigned_int `ushort_(num)`]] [`unsigned short`] [Parse an unsigned short integer,
- a number is matched only if it's `num`]]
- [[[x3_unsigned_int `ulong_`]] [`unsigned long`] [Parse an unsigned long integer]]
- [[[x3_unsigned_int `ulong_(num)`]] [`unsigned long`] [Parse an unsigned long integer,
- a number is matched only if it's `num`]]
- [[[x3_unsigned_int `uint_`]] [`unsigned int`] [Parse an unsigned int]]
- [[[x3_unsigned_int `uint_(num)`]] [`unsigned int`] [Parse an unsigned int,
- a number is matched only if it's `num`]]
- [[[x3_unsigned_int `ulong_long`]] [`unsigned long long`] [Parse an unsigned long long]]
- [[[x3_unsigned_int `ulong_long(num)`]] [`unsigned long long`] [Parse an unsigned long long,
- a number is matched only if it's `num`]]
- [[[x3_signed_int `short_`]] [`short`] [Parse a short integer]]
- [[[x3_signed_int `short_(num)`]] [`short`] [Parse a short integer,
- a number is matched only if it's `num`]]
- [[[x3_signed_int `long_`]] [`long`] [Parse a long integer]]
- [[[x3_signed_int `long_(num)`]] [`long`] [Parse a long integer,
- a number is matched only if it's `num`]]
- [[[x3_signed_int `int_`]] [`int`] [Parse an int]]
- [[[x3_signed_int `int_(num)`]] [`int`] [Parse an int,
- a number is matched only if it's `num`]]
- [[[x3_signed_int `long_long`]] [`long long`] [Parse a long long]]
- [[[x3_signed_int `long_long(num)`]] [`long long`] [Parse a long long,
- a number is matched only if it's `num`]]
- ]
- [endsect]
- [section:string String Parsers]
- [table
- [[Expression] [Attribute] [Description]]
- [[[x3_lit_string `str`]] [`Unused`] [Matches `str`]]
- [[[x3_lit_string `lit(str)`]] [`Unused`] [Matches `str`]]
- [[[x3_lit_string `string(str)`]] [`Str`] [Matches `str`]]
- [[__x3_symbols__] [N/A] [Declare a symbol table, `sym`. `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]]
- [[__x3_eol__] [`Unused`] [Matches the end of line (`\r` or `\n` or `\r\n`)]]
- [[__x3_eoi__] [`Unused`] [Matches the end of input (first == last)]]
- [[__x3_eps__] [`Unused`] [Match an empty string]]
- [[__x3_eps__`(b)`] [`Unused`] [If `b` is true, match an empty string]]
- [[__x3_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)`]]
- [[__x3_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]]
- [[[x3_native_binary `byte_`]] [8 bits native endian] [Matches an 8 bit binary in native endian representation]]
- [[[x3_native_binary `word`]] [16 bits native endian] [Matches a 16 bit binary in native endian representation]]
- [[[x3_big_binary `big_word`]] [16 bits big endian] [Matches a 16 bit binary in big endian representation]]
- [[[x3_little_binary `little_word`]] [16 bits little endian][Matches a 16 bit binary in little endian representation]]
- [[[x3_native_binary `dword`]] [32 bits native endian] [Matches a 32 bit binary in native endian representation]]
- [[[x3_big_binary `big_dword`]] [32 bits big endian] [Matches a 32 bit binary in big endian representation]]
- [[[x3_little_binary `little_dword`]] [32 bits little endian][Matches a 32 bit binary in little endian representation]]
- [[[x3_native_binary `qword`]] [64 bits native endian] [Matches a 64 bit binary in native endian representation]]
- [[[x3_big_binary `big_qword`]] [64 bits big endian] [Matches a 64 bit binary in big endian representation]]
- [[[x3_little_binary `little_qword`]] [64 bits little endian][Matches a 64 bit binary in little endian representation]]
- ]
- [endsect]
- [section:directive Parser Directives]
- [table
- [[Expression] [Attribute] [Description]]
- [[__x3_lexeme__`[a]`] [`A`] [Disable skip parsing for `a`, does pre-skipping]]
- [[[x3_no_skip `no_skip[a]`]] [`A`] [Disable skip parsing for `a`, no pre-skipping]]
- [[__x3_no_case__`[a]`] [`A`] [Inhibits case-sensitivity for `a`]]
- [[__x3_omit__`[a]`] [`Unused`] [Ignores the attribute type of `a`]]
- [[__x3_matches__`[a]`] [`bool`] [Return if the embedded parser `a` matched its input]]
- [[__x3_raw__`[a]`] [__boost_iterator_range__`<I>`] [Presents the transduction of `a` as an iterator range]]
- [[__x3_expectd__`[a]`] [`A`] [Throw an exception if parsing `a` fails]]
- [[[x3_repeat `repeat[a]`]] [`vector<A>`] [Repeat `a` zero or more times]]
- [[[x3_repeat `repeat(N)[a]`]] [`vector<A>`] [Repeat `a` `N` times]]
- [[[x3_repeat `repeat(N, M)[a]`]] [`vector<A>`] [Repeat `a` `N` to `M` times]]
- [[[x3_repeat `repeat(N, inf)[a]`]] [`vector<A>`] [Repeat `a` `N` or more times]]
- [[__x3_skip__`[a]`] [`A`] [Re-establish the skipper that got inhibited by lexeme or no_skip.]]
- [[__x3_skip__`(p)[a]`] [`A`] [Use `p` as a skipper for parsing `a`]]
- ]
- [endsect]
- [section:operator Parser Operators]
- [table
- [[Expression] [Attribute] [Description]]
- [[__x3_not_predicate__] [`Unused`] [Not predicate. If the predicate `a` matches,
- fail. Otherwise, return a zero length match.]]
- [[__x3_and_predicate__] [`Unused`] [And predicate. If the predicate `a` matches,
- return a zero length match. Otherwise, fail.]]
- [[__x3_optional__] [`optional<A>`] [Optional. Parse `a` zero or one time]]
- [[__x3_kleene__] [`vector<A>`] [Kleene. Parse `a` zero or more times]]
- [[__x3_plus__] [`vector<A>`] [Plus. Parse `a` one or more times]]
- [[__x3_alternative__] [`variant<A, B>`] [Alternative. Parse `a` or `b`]]
- [[__x3_sequence__] [`tuple<A, B>`] [Sequence. Parse `a` followed by `b`]]
- [[__x3_expect__] [`tuple<A, B>`] [Expect. Parse `a` followed by `b`. `b` is
- expected to match when `a` matches, otherwise,
- an `expectation_failure` is thrown.]]
- [[__x3_difference__] [`A`] [Difference. Parse `a` but not `b`]]
- [[__x3_list__] [`vector<A>`] [List. Parse `a` delimited `b` one or more times]]
- ]
- [endsect]
- [section:action Parser Semantic Actions]
- [table
- [[Expression] [Attribute] [Description]]
- [[`p[fa]`] [Attribute of `p`] [Call semantic action, `fa` if p succeeds.]]
- ]
- [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]]
- [[__x3_sequence__ (`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>``]]
- [[__x3_expect__ (`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>``]]
- [[__x3_alternative__ (`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``]]
- [[__x3_difference__ (`a - b`)]
- [``a: A, b: B --> (a - b): A
- a: Unused, b: B --> (a - b): Unused``]]
- [[__x3_kleene__ (`*a`)]
- [``a: A --> *a: vector<A>
- a: Unused --> *a: Unused``]]
- [[__x3_plus__ (`+a`)]
- [``a: A --> +a: vector<A>
- a: Unused --> +a: Unused``]]
- [[__x3_list__ (`a % b`)]
- [``a: A, b: B --> (a % b): vector<A>
- a: Unused, b: B --> (a % b): Unused``]]
- [[[/ $$$ FIXME $$$ link spirit.x3.reference.directive.repeat] `repeat(...,...)[a]`]
- [``a: A --> repeat(...,...)[a]: vector<A>
- a: Unused --> repeat(...,...)[a]: Unused``]]
- [[__x3_optional__ (`-a`)]
- [``a: A --> -a: optional<A>
- a: Unused --> -a: Unused``]]
- [[`&a`] [`a: A --> &a: Unused`]]
- [[`!b`] [`a: A --> !a: Unused`]]
- ]
- [endsect]
- [section:non_terminals Nonterminals]
- [variablelist Notation
- [[`Attr`] [Synthesized attribute. The rule return type.]]
- [[`ID`] [The rule ID]]
- [[`r, r2`] [Rules]]
- [[`r_def, r2_def`] [A rule definition. By convention a rule named `r` should
- have corresponding rule definition named `r_def`]]
- [[`p`] [A parser expression]]
- ]
- [table
- [[Expression] [Description]]
- [[`rule<ID, Attr> const r = name;`] [Rule declaration. `ID` is required.
- `Attr` is optional and defaults to __unused_type__.
- `name` is an optional string that gives the rule
- its name, useful for debugging and error handling.]]
- [[`r.name()`] [Getting the name of a rule]]
- [[`auto const r_def = p;`] [Rule definition]]
- [[`BOOST_SPIRIT_DEFINE(r, r2, ...)`] [Links one or more rules (`r, r2, ...`) with
- their definitions (`r_def, r2_def, ...`)]]
- ]
- [endsect]
- [section:semantic_actions Parser Semantic Actions]
- Has the form:
- p[f]
- where `f` is a function with the signatures:
- void f(Context&);
- [/ $$$ TODO $$$ Fix this link: For more detailed information about semantic actions see:]
- [endsect]
|