m
%Gc @ sf d k l Z d k Z d Z d Z d e f d YZ d d Z d d Z d
Z d Z d S( ( s spyceModuleNs
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, data, tag).
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.
t roott tocc B s t Z d Z d Z d Z d Z d Z d Z d Z d Z d Z
d
Z d d d Z
d
Z d d d Z e d Z e
Z e Z e Z d d Z d d Z d d Z d d Z d d Z d d Z d d Z d d Z d d Z d d Z d Z d Z d d Z! d d Z" d d Z# d d Z$ d d Z% d d! Z& d d" Z' d d# Z( d$ Z) d% Z* RS(& Nc C sO | i i d i d p h | i i d d ( ( R t level s
c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l1 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l2
s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l3 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l4 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l5 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l6 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l7 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l8 s c C s | i d | | d S( Ni ( R R@ R5 R4 ( R R5 R4 ( ( R t l9 s c C s d | _ | i | i d S( Ni ( R R t
_tocHelperR ( R ( ( R t showTOC s c C sl | i | | i | i oK | i | | i x | i D] } | i | q: W| i | | i n d S( N( R R/ R R t childrenR t cRJ R ( R R RM ( ( R RJ s
c C s3 d | _ | p
| i } n | i \ } } } | S( Ni ( R R R R5 R4 R ( R R R5 R4 R ( ( R t getTag( s
c C sb d | _ y; | i } | o | i | } n | i \ } } } | SWn t j
o d Sn Xd S( Ni ( R R R R4 R R5 R R
R ( R R4 R R R5 ( ( R t getNumbering- s c C sb d | _ y; | i } | o | i | } n | i \ } } } | SWn t j
o d Sn Xd S( Ni ( R R R R4 R R5 R R
R ( R R4 R R R5 ( ( R t getData6 s c C sS d | _ y, | i } | o | i | } n | i SWn t j
o d Sn Xd S( Ni ( R R R R4 R R? R
R ( R R4 R ( ( R R= ? s c C st d | _ yM | p | i } n | i | i } | d j o d Sn | i | SWn t j
o d Sn Xd S( Ni ( R R R4 RN R R; R R
( R R4 ( ( R t
getNextTagG s
c C st d | _ yM | p | i } n | i | i } | d j o d Sn | i | SWn t j
o d Sn Xd S( Ni ( R R R4 RN R t prevR R R
( R R4 R ( ( R t
getPrevTagP s
c C st d | _ yM | p | i } n | i | i } | d j o d Sn | i | SWn t j
o d Sn Xd S( Ni ( R R R4 RN R R9 R R R
( R R4 R ( ( R t getParentTagY s
c C sb d | _ y; | p | i } n | i | i } t | i | SWn t j
o d Sn Xd S( Ni (
R R R4 RN R RL t nodest mapR
R ( R R4 RU ( ( R t getChildrenTagsb s c C s' d t | i } | i d | _ | S( Nt auto_i ( t strR R R4 ( R R4 ( ( R R6 l s c C s9 | i \ } } } | o | | i | | | } n d S( N( R R5 R4 R R' R? t s( R R R' R RZ R4 R5 ( ( R R/ p s (+ t __name__t
__module__R R R& R( R) R* R+ R, R- R. R R7 R: R; R
R< t bt et nR@ RA RB RC RD RE RF RG RH RI RK RJ RN RO RP R= RQ RS RT RW R6 R/ ( ( ( R R sN
i c C s | d | d | g S( Ni( R t inc( R R` ( ( R R2 u s i c C s | | g S( N( R R ( R R ( ( R R0 w s c C s | d S( Ni( R ( R ( ( R R8 y s c C s! t d | d d t | S( Nc C s d | | f S( Ns %s%d.( RZ t i( RZ Ra ( ( R t } s t t ( t reduceR RY R5 ( R4 R R5 ( ( R t
defaultOutput| s ( t spyceModuleR t __doc__R
R R2 R0 R8 Rf ( Rg R0 Rf R
R R2 R8 R Rh ( ( R t ? s