spyce
home
license
community
download
examples
resources
wishlist
contrib (@sf)
documentation
intro
lang
runtime
modules
tags
install
exits
sourceforge
statistics
freshmeat

Documentation - Modules
[[ Spyce ]]
Python Server Pages
by Rimon Barr

Prev: 4.15 - Automaton Up: 4 - Modules Next: 4.17 - Writing Modules

4.16. TOC

The TOC module provides support for constructing a table contents for a lengthy document, such as this user documentation. The primary task of the TOC module is to maintain a document tree, and initiate callbacks at the appropriate points in the document. Note that this module may automatically force a secondary processing of the Spyce file to resolve forward references.

The module provides the following methods to segment the document:

  • begin( data, [tag] ):
    Increase the nesting level and add a new section. The data is stored in the document tree, and used for callbacks (see later). An optional tag may be associated with the node, otherwise one will automatically be generated. The function b() is equivalent.
  • next( data, [tag] ):
    Add a new section at the same nesting level. The data is stored in the document tree, and used for callbacks (see later). An optional tag may be associated with the node, or one will be automatically generated. The function n() is equivalent.
  • end():
    Decrease the nesting level. The function e() is equivalent.
  • anchor( data, [tag] ):
    Set data and optionally the tag associated with the root of the document tree. If the tag is omitted, it defaults to the string 'root'.
  • level( depth, data, [tag] ):
    Start a new section at given depth with given data and optional tag. The necessary begin(), next() and end() calls are automatically made, based on the current document depth, so both types of calls can be inter-mixed.
  • l1( data, [tag] ):
    Start a level 1 section. This function merely calls level(1, datatag). The functions, l2()...l9() are similarly defined.

The following methods provide access to document information:

  • getTag():
    Return the tag of the current document section.
  • getNumbering( [tag] )
    Return the numbering of some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. The numbering is an array of numbers. This function may return 'None' on the first pass through a document.
  • getData( [tag] )
    Return the data associated with some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. This function may return 'None' on the first pass through a document.
  • getDepth( [tag] )
    Return the depth of some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. This function may return 'None' on the first pass through a document.
  • getNextTag( [tag] )
    Return the tag of the section following some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. If this is the last section of the document, then this function will return 'None'. This function may return 'None' on the first pass through a document.
  • getPrevTag( [tag] )
    Return the tag of the section before some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. If this is the first section of the document, then this function will return 'None'. This function may return 'None' on the first pass through a document.
  • getParentTag( [tag] )
    Return the tag of the section above (or containing) some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. If this is the top-most section of the document, then this function will return 'None'. This function may return 'None' on the first pass through a document.
  • getChildrenTags( [tag] )
    Return a list (possibly empty) of tags of the sections directly contained within some section of the document identified by the given tag. If the tag is omitted, the current document section is assumed. This function may return a shorter list than anticipated or 'None', on the first pass through a document.

The TOC modules can make callbacks to handlers that format the document correctly. The handlers should be defined and registered before the first section break in the document. The following functions register handlers:

  • setDOC_PUSH( f ):
    Register a function f to be called when the nesting depth of the document increases.
  • setDOC_POP( f ):
    Register a function f to be called when the nesting depth of the document decreases.
  • setDOC_START( f ):
    Register a funtion f to be called at the beginning of a section.
  • setDOC_END( f ):
    Register a function f to be called at the end of a section.
  • setTOC_PUSH( f ):
    Register a function f to be called when the nesting depth of the table of contents increases.
  • setTOC_POP( f ):
    Register a function f to be called when the nesting depth of the table of contents decreases.
  • setTOC_ENTRY( f ):
    Register a function f to be called for each table of contents entry.

Each callback function should be of the form:

f(depth, tag, numbering, data),
where: depth is the nesting depth, tag is the associated tag, numbering is the position array, and data is the associated data of the section for which the callback was made.

The DOC callbacks are made as the sections are encountered. The TOC callbacks are made while printing the table of contents. If the modules detects that forward references exist in the document, the document will be processed twice, and only the second output will be sent. Note that buffering MUST be turned on for this to function correctly.

To display a table of contents, define the appropriate TOC callback functions and call:

  • showTOC(): Display the table of contents.
For an example of how to use the TOC module, please refer to the source Spyce file of this documentation.


Prev: 4.15 - Automaton Up: 4 - Modules Next: 4.17 - Writing Modules


© 2002-06 Rimon Barr
email: rimon@acm.org
Spyce Powered SourceForge Logo [[ Spyce ]]
Python Server Pages
version 1.3.13