Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Karma

Quick Reference
Common Notation
Predefined Primitive Generators
Compound Attribute Rules
Lazy Arguments
Non-terminals
Semantic Actions
Phoenix

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 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 and pages of reference doumentation.

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. 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_classtypes_)

ch

Character-class specific character (See __char_classtypes_)

ch2

Character-class specific character (See __char_classtypes_)

chset

Character-set specifier string (example: "a-z0-9")

str

Character-class specific string (See __char_classtypes_)

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

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]

vector<A>

Repeat a zero or more times

repeat(N)[a]

vector<A>

Repeat a N times

repeat(N, M)[a]

vector<A>

Repeat a N to M times

repeat(N, inf)[a]

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

optional<A>

Optional. Generate a zero or one time

*a

vector<A>

Kleene. Generate a zero or more times

+a

vector<A>

Plus. Generate a one or more times

a | b

variant<A, B>

Alternative. Generate a or b

a << b

tuple<A, B>

Sequence. Generate a followed by b

a % b

vector<A>

List. Generate a delimited b one or more times

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>.

Table 5. /Spirit.Karma/ compound generator attribute types

Expression

Attribute

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>

alternative (|)

a: A, b: B --> (a | b): variant<A, B>
a: A, b: Unused --> (a | b): variant<Unused, A>
a: Unused, b: B --> (a | b): variant<Unused, B>
a: Unused, b: Unused --> (a | b): Unused

a: A, b: A --> (a | b): A`

kleene (*)

a: A --> *a: vector<A>
a: Unused --> a: Unused

plus (+)

a: A --> +a: vector<A>
a: Unused --> a: Unused

list (%)

a: A, b: B --> (a % b): vector<A>
a: Unused, b: B --> (a % b): Unused

repetition

a: A --> repeat(...,...)[a]: vector<A>
a: Unused --> repeat(...,...)[a]: Unused

optional (-)

a: A --> -a: optional<A>
a: Unused --> -a: Unused

and predicate (&)

a: A --> &a: Unused

not predicate (!)

a: A --> !a: Unused

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.

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

my_grammar

A user defined grammar

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

Template Arguments

Iterator

The iterator type you will use for parsing.

A1, A2, A3

Can be one of 1)Signature 2)Locals 3)Skipper.

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. 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

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.

my_grammar<Iterator> g

Instantiating a grammar

g.name(name)

Naming a grammar

g.name()

Getting the name of a grammar

Has the form:

p[f]

where f is a function with the signatures:

void f(Attr const&);
void f(Attr const&, Context&);
void f(Attr const&, Context&, bool&);

You can use Boost.Bind to bind member functions. For function objects, the allowed signatures are:

void operator()(Attr const&, unused_type, unused_type) const;
void operator()(Attr const&, Context&, unused_type) const;
void operator()(Attr const&, Context&, bool&) const;

The unused_type is used in the signatures above to signify 'don't care'.

__boostphoenix_ makes it easier to attach semantic actions. You just inline your lambda expressions:

p[phoenix-lambda-expression]

Spirit.Qi provides some __boostphoenix_ placeholders to important information from the Attr and Context that are otherwise fiddly to extract.

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).

_val

The enclosing rule's synthesized attribute.

_pass

Assign false to _pass to force a parser failure.


PrevUpHomeNext