Modes

  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.

Modes are switched by method mode(). 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.

Ways of stream processing

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 each 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().

Stream navigaton

Stream navigation works both in callbacks and if walking the stream via next().

The whole picture

new()

Parameters: All parameters except of the class parameter are named (pass them by hash).

class

The class name.

name

Because there can be more than exactly one backend object, your object should be named. This is not necessarily a need but helpful reading traces.

trace

This parameter is optional. It is intended to activate trace code while the object methods run. You may pass any of the "TRACE_..." constants declared in PerlPoint::Constants, combined by addition as in the following example:

  trace => TRACE_NOTHING+TRACE_BACKEND,
    

In fact, only TRACE_NOTHING and TRACE_BACKEND take effect to backend objects.

If you omit this parameter or pass TRACE_NOTHING, no traces will be displayed.

display

This parameter is optional. It controls the display of runtime messages like informations or warnings in all object methods. By default, all messages are displayed. You can suppress these informations partially or completely by passing one or more of the "DISPLAY_..." variables declared in PerlPoint::Constants.

Constants can be combined by addition.

vispro

activates "process visualization" which simply means that a user will see progress messages while the backend processes the stream. The numerical value of this setting determines how often the progress message shall be updated by a chapter interval:

  # inform every five chapters
  vispro => 5,
    

Process visualization is automatically suppressed unless STDERR is connected to a terminal, if this option is omitted, display was set to "DISPLAY_NOINFO" or backend traces are activated.

generator

This is an internal interface, to make backends work together with "PerlPoint::Generator" objects. If you build a backend manually, you do not have to care for this, just ignore it. If you build a "PerlPoint::Generator" application, just pass the generator object.

Note: Generator handling is in alpha state, so manual usage is standard and traditional.

Returns: the new object.

Example:

  my ($backend)=new PerlPoint::Backend(name=>'example');

register()

If the object walks through the data stream generated by PerlPoint::Parser, it will find several directives. A directive is a data struture flagging that a certain document part (or even formatting) starts or is completed. E.g. a headline is represented by headline start directive followed by tokens for the headline contents followed by a headline completion directive.

By using this method, you can register directive specific functions which should be called when the related directives are discovered. The idea is that such a function can produce a target language construct representing exactly the same document token that is modelled by the directive. E.g. if your target language is HTML and you register a headline handler and a headline start is found, this handler can generate a "<Hx>" tag. This is quite simple.

According to this design, the object will pass the following data to a registered function:

directive

the directive detected, this should be the same the function was registered for. See PerlPoint::Constants for a list of directives.

start/stop flag

The document stream generated by the parser is strictly synchronous. Everything except of plain strings is represented by an open directive and a close directive, which may embed other parts of the document. A headline begins, something is in, then it is complete. It's the same for every tag or paragraph and even for the whole document.

So well, because of this structure, a handler registered for a certain directive is called for opening directives as well as for closing directives. To decide which case is true, a callback receives this parameter. It's always one of the constants DIRECTIVE_START or DIRECTIVE_COMPLETED.

For simple strings (words, spaces etc.) and line number hints, the callback will always (and only) be called with DIRECTIVE_START.

directive values, if available

Certain directives provide additional data such as the headline level or the original documents name which are passed to their callbacks additionally. See the following list:

To express this by a prototype, all registered functions should have an interface of "$$:@".

Parameters:

object

a backend object as made by new();

directive

the directive this handler is registered for. See PerlPoint::Constants for a list of directives.

handler

the function to be called if a pointed directive is entered while the run() method walks through the document stream.

Returns: no certain value;

Example:

  $backend->register(DIRECTIVE_HEADLINE, \&handleHeadline);

where handleHeadline could be something like

  sub handleDocument
   {
    my ($directive, $startStop, $level)=@_;
    confess "Something is wrong\n"
      unless $directive==DIRECTIVE_HEADLINE;
    if ($startStop==DIRECTIVE_START)
      {print "<head$level>";}
    else
      {print "</head>";}
   }

If no handler is registered, detected items will be ignored by default except of plain strings, which will be printed by default.

mode()

"Inspecting tokens" means how the object reads stream data to invoke registered handlers.

Parameters:

object

An object as built by new().

new mode

All modes are declared by STREAM_... constants in "PerlPoint::Constants" (import these constants by using the ":stream" tag).

Returns:

the new mode.

Example:

  $backend->mode(STREAM_HEADLINES);

run()

If all (mode according) stream data are handled <run()> finishs.

The model of this method is to perform stream data processing by an enclosing loop which is in control and knows of callbacks to handle "events" (occurences of certainly typed data). There is an alternative model using next() to give the caller control of when to process the next token.

Parameters:

object

An object as built by new().

stream data

A reference to the stream data produced by a "PerlPoint::Parser" call. Stream data are not stored in an object (yet?), but nevertheless nothing but a data structure as supplied by the parser will be accepted.

Returns:

nothing specific.

Example:

  $backend->run($streamData);

next()

Processing a token works equally to run() by type detection and handler invokation, see there for details.

Please note that different to run() a stream must be bound to a backend object before using "next()". This is necessary to store processing states between various "next()" calls and is done by bind(). After processing all data, unbind() may be used to detach the stream.

To avoid confusion, "next()" cannot be called from a callback invoked by run(). In other words, both approaches cannot be mixed.

Parameters:

object

An object as built by new().

Returns:

A true value if there is more to process, a false value otherwise. It is up to the caller to handle these cases appropriately.

Example:

  # This example emulates run() by next().
  $backend->bind($streamData);
  {redo while $backend->next;}
  $backend->unbind;

bind()

If there was already a stream connected to the backend object, the new connection will replace the old one.

Binding a stream resets stream processing (see reset()). Do not call this method from a handler unless you know exactly what is going on.

Parameters:

object

An object as built by new().

stream data

A reference to the stream data produced by a "PerlPoint::Parser" call. Stream data are not stored in an object (yet?), but nevertheless nothing but a data structure as supplied by the parser will be accepted.

Returns:

nothing significant.

Example:

  $backend->bind($streamData);

unbind()

Unbinding a stream resets stream processing (see reset()) - if the stream is rebound to the object and furtherly processed, it will be processed from its beginning.

Do not call this method from a handler unless you know exactly what is going on.

Parameters:

object

An object as built by new().

Returns:

nothing significant.

Example:

  $backend->unbind();

reset()

Parameters:

object

An object as built by new().

Returns:

nothing significant.

Example:

  $backend->reset;

move2chapter()

Parameters:

object

An object as built by new().

chapter

The number of the target chapter to process next. This is an absolute number - the first headline is headline 1, the second 2 etc., regardless of headline hierachies. The highest valid number is equal to the result of headlineNr().

Returns:

nothing significant.

Example:

  $backend->move2chapter(15);

headlineNr()

Parameters:

object

An object as built by new().

Returns:

The number of headlines in the stream if a stream is associated, an undefined value otherwise.

Example:

  $backend->headlineNr;

headlineIds2Data()

object

An object as built by new().

list of headline ids

A list of ids. An id is an absolute headline number, starting with 1.

Returns:

The number of headlines in the stream if a stream is associated, an undefined value otherwise.

Example:

  $backend->headlineIds2Data;

currentChapterNr()

Parameters:

object

An object as built by new().

Returns:

The number of the currently handled headline in the stream if a stream is associated, an undefined value otherwise.

Example:

  $backend->currentChapterNr;

toc()

Parameters:

object

An object as built by new().

chapter of interest

This is an absolute number as used in various other methods as well. The first headline in the document is number 1, the next headline number 2 and so on. (The number of the chapter currently processed is always provided by currentChapterNr().)

If this parameter is omitted or 0, the whole documents hierarchy will be reported.

result depth

There may be a deep hierarchy of subchapters. If only a certain depth is of interest, supply it here. If this parameter is omitted or set to 0, all subchapters will be reported.

Returns:

a reference to an array of arrays, where each entry describes a subchapter by its headline level and its title (as plain text - tags etc. are stripped off).

Example:

  $subchapters=$backend->toc(5, 2);

docstreams()

Parameters:

object

An object as built by new().

Returns:

A list of document stream titles in list context, the number of document streams in scalar context.

Example:

  @docstreams=$backend->docstreams;