Vary token selection

By default, a backend object inspects the token stream token by token. This way everything is handled in the original order, according to the input once parsed. But sometimes you want to know something about the documents structure which simply means about headlines only.

    For example, consider the case that you want to build
    a table of contents or a table of valid chapter references
    before the "real" slides are made. In the mentioned token
    mode this takes more time than it should, because a lot
    of additional tokens are processed besides the headlines.

In such cases, the backend can be enforced to work in "headline mode". This means that only headlines are processed which accelerates things significantly. The backend only deals with opening and closing headline directives and the tokens between them - usually very few.

Modes are switched by method mode(). The following code limits the usual stream processing to headlines.

    # switch to headline mode
  
    $backend->mode(STREAM_HEADLINES);

From now on, subsequent calls to run() (or next()) will take only headlines into account, ignoring anything else.

To switch back to the usual behaviour, mode() has to be called with another constant. (All STREAM_... constants are declared in PerlPoint::Constants and can be imported by the import tag :stream.)

    # switch to headline mode
  
    $backend->mode(STREAM_TOKENS);

Please note that a stream can be processed more than once, so one can process it in headline mode first, use the headline information, and then switch back to the usual token mode and process the entire document data.

You can even switch modes while processing the stream, which means from within a backend callback. The new mode will come into action when the next element will be searched. So, if you are running your backend in token mode and switch to headline mode, the next handled element will be the following headline - remaining elements in the current chapter will be ignored. On the other hand, if switched from headline mode to token processing from within a callback, the backend will begin to provide the contents of the chapter which headline was handled when the switch was performed.