Stream navigation

Usually a stream is processed from the beginning to its end, but it is possible to set up an arbitrary sequence of chapters as well. (This is mostly intended for use in projectors - imagine how a speaker switches slides back and forth.) Two methods are provided to do this: reset() moves back to the beginning of the entire stream, while move2chapter() chooses a certain chapter to continue the processing with.

    # back to start
  
    $backend->reset;
  
    # proceed with 2nd chapter
  
    $backend->move2chapter(2);

All navigation methods take affect in the next subsequent stream entry handling. That's why navigation can be performed both from backend callbacks (invoked by run() or next()) or before a next() call.

The chapter number passed to move2chapter() is an absolute number - the first headline is headline 1, the second is headline 2 etc. - regardless of headline hierachies. The current headline number is always provided by currentChapterNr().

    # Which chapter are we reading?
  
    $backend->currentChapterNr;

This information could then be used to skip a chapter, for example.

    # skip a chapter
  
    $backend->move2chapter($backend->currentChapterNr+2);

But - are there two more chapters, really? The highest valid headline number is provided by the method headlineNr(), which replies the number of headlines in the stream associated with the backend object. (If no stream is associated, an undefined value is supplied.)

    # How many chapters to read through?
  
    $backend->headlineNr;

So, using this information we can avoid that mode2chapter() dies because of an invalid chapter number, which would cause a fatal error otherwise.

    # move two chapters, if possible
  
    $backend->move2chapter($backend->currentChapterNr+2)
      unless $backend->currentChapterNr+2>$backend->headlineNr;