Next: Stream navigation   Previous: Backend invokation: produce new code   Contents: Contents

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.

Next: Stream navigation   Previous: Backend invokation: produce new code   Contents: Contents