Vary processing control

The base model of stream processing implemented by PerlPoint::Backend is based on "events", which means that the token stream is processed by a loop which invokes user specified callback functions to handle certain token types. In this default model, the loop is in control. You can configure it, you can start it whenever you want, but once it is started it processes the entire stream before control is passed back to your code.

This works fine in stream translation, e.g. to produce slides/documents straight into a target format, and is done by invoking the method run(). Nevertheless, there are cases when converters need to be in full control, which means in fine grained control of token processing. In this model the calling program (the converter) initiates the processing of every single token. This is especially useful if a converter is not really a converter but a projector which uses the stream to present the slides on the fly.

This second model of fine grained control is supported as well. The appropriate method (used as an alternative of run()) is next(). next() processes exactly one stream entry and returns.

    # process next stream entry
  
    $backend->next;

After the next() call, you may move to another chapter, switch modes, perform intermediate tasks, allow a user to interact with your tool or something like that. Then, when it seems to be the right time to proceed, you may invoke next() for another entry. But if you prefer, you may as well decide to stop stream processing, without having handled all entries. It's entirely up to you this way.

Processing an entry works equally to run(), by type detection and handler invokation, there's absolutely no difference.

To make a backend object know of the stream to handle and enable it to store position hints between several next() calls, a stream must be bound to a backend object before next() can be used. This is done by I<bind()>.

    # bind the stream
  
    $backend->bind($streamData);
  
    # process next stream entry
  
    $backend->next;

After processing all data, I<unbind()> may be used to detach the stream.

    # detach the stream
  
    $backend->unbind;

Here's a complete example, emulating run() by next():

    $backend->bind($streamData);
    {redo while $backend->next;}
    $backend->unbind;

So emulation is easy, but mixing both approaches is impossible to avoid confusion. This especially means that next() cannot be called from a callback invoked by run().