Next:   Previous: Documentation   Contents: Contents

Appendix A: Stream directives

The following table describes the backends callback interfaces. The very first parameters passed are a directive constant describing the detected items type, and a state constant expressing the item either begins (DIRECTIVE_START) or is completed (DIRECTIVE_COMPLETE).

Although in the first design it was intended to make everything being enclosed by a start and a completion directive, it turned out to be more pragmatic to let several very simple tokens (and therefore stream elements) being represented by a DIRECTIVE_START flag only. The table mentions all used flags.

If start and completion are flagged, tokens of various other types may be embedded. A headline, for example, starts by a startup directive, embeds plain string tokens and possibly flags, and is finally closed by completion directive. On the other hand, tokens that only provide a startup flag are completely represented by the token element containing the flag. That means that plain string directives, for example, contain the string as well - nothing more will follow. (That's easier to understand than to describe, hm.)

All parameters beginning with the third one are absolutely type specific.

If there are beginning and completing elements, all parameters will be provided at both places except where noted.

1: type directive2: used flags (modes)3...: more parameters
DIRECTIVE_BLOCKDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_COMMENTDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_DLISTDIRECTIVE_START, DIRECTIVE_COMPLETEa reserved parameter, two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
DIRECTIVE_DOCUMENTDIRECTIVE_START, DIRECTIVE_COMPLETE(base)name of source file
DIRECTIVE_DPOINTDIRECTIVE_START, DIRECTIVE_COMPLETEa reserved parameter, two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
DIRECTIVE_DPOINT_ITEMDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_HEADLINEDIRECTIVE_START, DIRECTIVE_COMPLETEHeadline level. The full headline title (tags stripped off) is provided additionally in the startup directive only.
DIRECTIVE_LIST_LSHIFTDIRECTIVE_STARTnumber of levels to shift
DIRECTIVE_LIST_RSHIFTDIRECTIVE_STARTnumber of levels to shift
DIRECTIVE_NEW_LINEDIRECTIVE_STARTa hash reference: key "file" provides the current source file name, key "line" the new line number
DIRECTIVE_OLISTDIRECTIVE_START, DIRECTIVE_COMPLETEA prefered startup number (defaults to 1). Two parameters describing type and level of a preceeding list shift if any (0 otherwise, only provided in start directives), two parameters describing type and level of a following list shift if any (0 otherwise, only provided in completion directives)
DIRECTIVE_OPOINTDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_SIMPLEDIRECTIVE_STARTa list of strings
DIRECTIVE_TAGDIRECTIVE_START, DIRECTIVE_COMPLETEFirst, the tag name, then a reference to a hash of tag options taken from the source. Tag options in the open directive might have been modified by a tag finish hook and therefore differ from the options provided in the closing directive, which reflects the original options (before finish hook invokation).
DIRECTIVE_TEXTDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_ULISTDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_UPOINTDIRECTIVE_START, DIRECTIVE_COMPLETE-
DIRECTIVE_VARRESETDIRECTIVE_START-
DIRECTIVE_VARSETDIRECTIVE_STARTa hash reference: key "var" provides the variables name, key "value" the new value
DIRECTIVE_VERBATIMDIRECTIVE_START, DIRECTIVE_COMPLETE-

And here is how these directives correspond to the PerlPoint source elements. To make reading (and writing ;-) simpler, the string DIRECTIVE_ and the type specific parameters passed to appropriate callbacks are omitted. See the table above fo those details. A directive is illustrated by enclosing brackets.

Block:


  [BLOCK, START]

    block contents

  [BLOCK, COMPLETED]

Comment:


  [COMMENT, START]

    comment text

  [COMMENT, COMPLETED]

Description list: The "description point item" is the described thing, marked in PerlPoint by enclosing colons.


  [DLIST, START]

    [DPOINT, START]

       [DPOINT_ITEM, START]

         item elements (text, tags, ...)

       [DPOINT_ITEM, COMPLETED]

       description elements (text, tags, ...)

    [DPOINT, COMPLETED]

    there may be more points

  [DLIST, COMPLETED]

Document:


  [DOCUMENT, START]

    main stream

  [DOCUMENT, COMPLETED]

Headline:


  [HEADLINE, START]

    headline text, tags etc.

  [HEADLINE, COMPLETED]

List shifts: Because these directives are extremely simple, there are no completion directives.


  [LIST_LSHIFT, START]

  [LIST_RSHIFT, START]

Ordered list:


  [OLIST, START]

    [OPOINT, START]

      point contents

    [OPOINT, COMPLETED]

    there may be more points

  [OLIST, COMPLETED]

Plain text: the parser tries to provide as much text together as possible. Nevertheless, there's no guarantee that a certain string sequence will be provided by a certain stream sequence of simple token directives. Whatever way a simple token sequence is provided, joining their contents by empty strings will result in the original string sequence.


  [SIMPLE, START]

Tag:


  [TAG, START]

    tagged things

  [TAG, COMPLETED]

Text:


  [TEXT, START]

    text

  [TEXT, COMPLETED]

Unordered list:


  [ULIST, START]

    [UPOINT, START]

      point contents

    [UPOINT, COMPLETED]

    there may be more points

  [ULIST, COMPLETED]

Verbatim block:


  [VERBATIM, START]

    block contents

  [VERBATIM, COMPLETED]
Next:   Previous: Documentation   Contents: Contents