Backend callbacks

A backend is used to translate stream elements into appropriate expressions of the target format. Because of this, backends need to work very format (or converter) specific. The only common task is to read the stream and to ignore all parts which the converter doesn't wish to support. These requirements are solved by a callback architecture.

When a backend is started, it (usually) runs through the stream. Every stream element is checked for its type, and then it is checked if a callback was specified to handle it. If so, the callback will be invoked to handle the element found, if not, the element is ignored. Simple but powerful!

To make this work, callbacks need to be registered before the backend starts its stream run. This is done by the backend method register().

    # register backend handlers
  
    $backend->register(DIRECTIVE_BLOCK, \&handleBlock);
    ...

register() takes an element type and a code reference. All possible stream element types are declared by constants, which are defined and documented in PerlPoint::Constants. The code reference, on the other hand, points to a function which shall be invoked when an element of the described type is detected, which means that it begins or ends.

Consider, for example, the statement in the last recent example: DIRECTIVE_BLOCK describes a code block element. The stream does not store blocks by large objects, but by a begin and end flag which show the "edges" of the block construction. Therefore the specified callback handleBlock() will be invoked twice: it will be called both when the block begins and when it is completed.

The callback interface is simple. It has a common part which is equal for all elements, and a special part which depends on the element type. The common part includes the element type ( DIRECTIVE_BLOCK, DIRECTIVE_TEXT, ...) and the mode which is either DIRECTIVE_START or DIRECTIVE_COMPLETE, flagging if the element is starting or completed.

The special part contains things like the name of a source file ( DIRECTIVE_DOCUMENT), tag options ( DIRECTIVE_TAG) or a headline level ( DIRECTIVE_HEADLINE). See Appendix A for a complete list of all callback interfaces.

There is no common way how callbacks should work. It strongly depends on the target format, the converter features and the tags. You may build another data structure which is finally made a file, or print immediately, or mix both approaches, and there are several more choices like this. But the frameset helps to begin coding this individual part quickly.