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

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

Prev: 2.2 - Spyce Comments Up: 2 - Language Next: 2.4 - Python Statements

2.3. Spyce Directives

Syntax: [[. directive ]]

Spyce directives directly affect the operation of the Spyce interpreter. There is a limited set of directives, listed and explained below:

  • [[.include file=file]] :
    Upon encountering this tag the Spyce compiler will insert the file referenced, treating its contents as if it had been typed inline. Statically included files are not checked for updates. Only an update to the primary file will invalidate the cache. For dynamic includes, please refer to the include module. Developers should also consider creating custom Python or Spyce modules, when the included file is primarily code, since there is no need to involve the Spyce compiler to convert primarily Python code to... Python code!
  • [[.compact mode=mode]] :
    Spyce can output the static HTML strings in various modes of compaction, which can both save bandwidth and improve download times without visibly affecting the output. Compaction of static HTML strings is performed once when the input Spyce file is compiled, and there is no additional run-time overhead beyond that. Dynamically generated content from Python code tags and expressions is not compacted nor altered in any way. Spyce can operate in one of the compaction modes listed below. One can use the compact tag to change the compaction mode from that point in the file forwards.

    • off: No compaction is performed. Every space and newline in the static HTML strings is preserved.
    • space: Space compaction involves reducing any consecutive runs of spaces or tabs down to a single space. Any spaces or tabs at the beginning of a line are eliminated. These transformations will not affect HTML output, barring the <pre> tag, but can considerably reduce the size of the emitted text.
    • line: Line compaction eliminates any (invisible) trailing whitespace at the end of lines. More significantly it improves the indented presentation of HTML, by ignoring any lines that do not contain any static text or expression tags. Namely, it removes all the whitespace, including the line break, surrounding the code or directives on that line. This compaction method usually "does the right thing", and produces nice HTML without requiring tricky indentation tricks by the developer. It is, therefore, the initial compaction mode.
    • full: Full compaction applies both space and line compaction. If the optional mode attribute is omitted, full compaction mode is the default value assumed.
  • [[.import name=name from=file as=name args=arguments]] :
    The import directive loads and defines a Spyce module into the global context. (The [[.module ... ]]directive is synonymous.) A Spyce module is a Python file, written specifically to interact with Spyce. The name parameter is required, specifying the name of the Python class to load. The file parameter is optional, specifying the file where the named class is to be found. If omitted, file will equal name.py. The file path can be absolute or relative. Relative paths are scanned in the Spyce home, user-configurable server path directories and current script directory, in that order. Users are encouraged to name or prefix their modules uniquely so as not to be masked by system modules or tag libraries. The as parameter is optional, and specifies the name under which the module will be installed in the global context. If omitted, this parameter defaults to the name parameter. Lastly, the optional args parameter provides arguments to be passed to the module initialization function. All Spyce modules are start()ed before Spyce processing begins, init()ed at the point where the directive is placed in the code, and finish()ed after Spyce processing terminates. It is convention to place modules at, or near, the very top of the file unless the location of initialization is relevant for the functioning of the specific module.

    [[.import names="name1,name2,..."]] :
    An alternative syntax allows convenient loading of multiple Spyce modules. One can not specify non-standard module file locations, nor rename the modules using this syntax.

  • [[.taglib name=name from=file as=name]] :
    The taglib directive loads a Spyce tag library. A Spyce tag library is a Python file, written specifically to interact with Spyce. The name parameter is required, specifying the name of the Python class to load. The file parameter is optional, specifying the file where the named class is to be found. If omitted, file will equal name.py. The file path can be absolute or relative. Relative paths are scanned in the Spyce home, user-configurable server path directories and current script directory, in that order. Users are encouraged to name or prefix their tag libraries uniquely so as not to be masked by system tag libraries and modules. The as parameter is optional, and specifies the unique tag prefix that will be used to identify the tags from this library. If omitted, this parameter defaults to the name parameter. It is convention to place tag library directives at, or near, the very top of the file. The tags only become active after the point of the tag library directive.

    [[.taglib names="name1,name2,..."]] :
    An alternative syntax allows convenient loading of multiple Spyce tag libraries. One can not specify non-standard tag library locations, nor specify a prefix of the tag libraries using this syntax.

It is important to note that Spyce directives are processed at compile time, not during the execution of the script, much like directives in C, and other languages. In other words, they are processed as the Python code for the Spyce script is being produced, not as it is being executed. Consequently, it is not possible to include runtime values as parameters to the various directives.


Prev: 2.2 - Spyce Comments Up: 2 - Language Next: 2.4 - Python Statements


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