Interface

All formatters receive the object, page data and an item structure.

The object and its attributes were described above.

The page data ...

The item structure is a hash with the following slots:

key	value
context	A reference to an array of embedding entities, entities are represented by their DIRECTIVE_... codes (see PerlPoint::Constants ). This allows a converter to determine the entities location in a hierarchy of entities, e.g. that a list is a nested list on 45th level.
parts	A reference to an array of elements, usually the embedded parts (or the "body" part), e.g. the headline text for a headline entity, or the tag body for a tag entity.
cfg	A reference to a configuration hash, see below.

The entries of the configuration hash:

key	value
type	the original directive type of the entity - usually unused by a formatter
mode	the original state of an entity - should not be used by a formatter
data	this is the interesting part, as it holds various attributes which are formatter specific

A formatter can supply a result. This is appropriate in most cases, as the results are made part of an embedding entity and provided to thats formatter when the entity is complete. Higher level formatters receive results of lower level formatters in the parts slot of their item parameter, see above.

    Imagine two nested tags. The body of the
    innermost tag is simple text, formatted
    by the simple text formatter. The formatter
    of the innermost tag receives the result
    of the simple text formatter in $item->{parts}.
    The formatter of the outer tag receives the
    result of the inner tag formatter in its
    $item->{parts} parameter slot.

A result can be of any type, except for pure (unblessed) hash references which are reserved for internal purposes. As the results are only passed through to outer formatters, the formatter class can organize its own data flow.

    The SDF formatter classes in the distribution
    in most cases use simple strings to transfer
    formatted results.
  
    They use array references to deal with document
    streams.
  
    The XML formatter classes in the distribution
    use XML::Generator objects as the intermediate
    data format between formatters.

In case you subclass an existing formatter class, take care which formats are used there.