| Home | Libraries | People | FAQ | More

##### Generator

###### Description

The Generator is the most fundamental concept. A Generator has a member function, `generate`, that accepts an `OutputIterator` and returns bool as its result. The iterator receives the data being generated. The Generator's `generate` member function returns `true` if the generator succeeds. Each Generator can represent a specific pattern or algorithm, or it can be a more complex generator formed as a composition of other Generators.

Notation

`g`

  A `Generator`.

`G`

  A `Generator` type.

`OutIter`

  An `OutputIterator` type.

`sink`

  An `OutputIterator` instance.

`Context`

  The generator's Context type.

`context`

  The generator's Context, or `unused`.

`delimit`

  A delimiter Generator, or `unused`.

`attrib`

  A Compatible Attributes, or `unused`.

###### Valid Expressions

In the expressions below, the behavior of the generator, `g`, as well as how `delimit` and `attrib` are handled by `g`, are left unspecified in the base `Generator` concept. These are specified in subsequent, more refined concepts and by the actual models thereof.

For any Generator the following expressions must be valid:

Expression | Semantics | Return type
--- | --- | ---
    g.generate(sink, context, delimit, attrib)
| Generate the output sequence by inserting the generated characters/tokens into `sink`. Use the `delimit` generator for delimiting. Return `true` if successful, otherwise return `false`. | `bool`
`g.what(context)` | Get information about a Generator. | `info`

###### Type Expressions

Expression | Description
--- | ---
`G::template attribute<Context>::type` | The Generator's attribute.
`traits::is_generator<G>::type` | Metafunction that evaluates to `mpl::true_` if a certain type, `G` is a Generator, `mpl::false_` otherwise (See MPL Boolean Constant).
`G::properties` | An `mpl::int_` (See MPL Integral Constant) holding a value from the `karma::generator_properties` enumeration. The default value is `generator_properties::no_properties`

###### Postcondition

Upon return from `g.generate` the following post conditions should hold:

- On successful generation, `sink` receives the generated characters/tokens sequence.
- No pre-delimits: `delimit` characters/tokens will not be emitted in front of any other output.
- The attribute `attrib` has not been modified.

###### Models

All generators in Spirit.Karma are models of the Generator concept.