home     documentation     download

The transform module contains useful text transformation functions, commonly used during web-page generation.

• html_encode( string, [also] ):
  Returns a HTML-encoded string, with special characters replaced by entity references as defined in the HTML 3.2 and 4 specifications. The optional also parameter can be used to encode additional characters.
• url_encode( string, ):
  Returns an URL-encoded string, with special characters replaced with %XX equivalents as defined by the URI RFC document.

• static( [ fn ] ):
  Defines the processing performed on all static HTML strings from this point forwards. The fn parameter is explained below.
• expr( [ fn ] ):
  Defines the processing performed on all the results of all expression tags from this point forwards. The fn parameter is explained below.
• dynamic( [ fn ] ):
  Defines the processing performed on all dynamic content generated, i.e. content generated using response.write in the code tags. The fn parameter is explained below.

Each of the functions above take a single, optional parameter, which specifies the processing to be performed. The parameter can be one of the following types:

• None:
  If the paramter is None, or omitted, then no processing is performed other converting the output to a string.
• Function:
  If a parameter of function type is specified, then that function is called to process the output. The function input can be any Python type, and the function output may be any Python type. The result is then converted into a string and emitted. The first parameter to a filter will always be the object to be processed for output. However, the function should be properly defined so as to possibly accept other parameters. The details of how to define filters are explained below.
• String:
  If a paramter of string type is specified, then the string should be of the following format: "file:name", where file is the location where the function is defined and name is the name of the filter. The file component is optional, and is searched for using the standard module-finding rules. If only the function name is specified, then the default location (inside the transform module itself) is used, where the standard Spyce filters reside. The standard Spyce filters are described below.
• List / Tuple:
  If a parameter of list or tuple type is specified, its elements should be functions, strings, lists or tuples. The compound filter is recursively defined as f=fn(...f2(f1())...), for the parameter (f1,f2,...,fn).

Having explained how to install filters, we now list the standard Spyce filters and show how they are used:

• ignore_none( o ):
  Emits any input o except for None, which is converted into an empty string.
• truncate( o, [maxlen] ):
  If maxlen is specified, then only the first maxlen characters of input o are returned, otherwise the entire original.
• html_encode( o, [also] ):
  Converts any '&', '<' and '>' characters of input o into HTML entities for safe inclusion in among HTML. The optional also parameter can specify, additional characters that should be entity encoded.
• url_encode( o ):
  Converts input o into a URL-encoded string.
• nb_space( o ):
  Replaces all spaces in input o with "&nbsp;".
• silence( o ):
  Outputs nothing.

The optional parameters to some of these filters can be passed to the various write functions as named parameters. They can also be specified in an expression tag, as in the following example. (One should simply imagine that the entire expression tag is replaced with a call to response.writeExpr).

[[.import name=transform]]
[[ transform.expr(("truncate", "html_encode")) ]]
[[='This is an unsafe (< > &) string... '*100, maxlen=500]] 

In the example above, the unsafe string is repeated 100 times. It is then passed through a truncate filter that will accept only the first 500 characters. It is then passed through the html_encode filter that will convert the unsafe characters into their safe, equivalent HTML entities. The resulting string is emitted.

The parameters (specified by their names) are simply accepted by the appropriate write method (writeExpr() in the case above) and passed along to the installed filter. Note that in the case of compound filters, the parameters are passed to ALL the functions. The html_encode filter is written to ignore the maxlen parameter, and does not fail.

For those who would like to write their own filters, looking at the definition of the truncate filter will help. The other standard filters are in modules/transform.py.

def truncate(o, maxlen=None, **kwargs):

When writing a filter, any function will do, but it is strongly advised to follow the model above. The important points are:

• The input o can be of any type, not only a string.
• The function result does not have to be string either. It is automatically stringified at the end.
• The function can accept parameters that modify its behaviour, such as maxlen, above.
• It is recommended to provide convenient user defaults for all parameters.
• The last parameter should be **kwargs so that unneeded parameters are quietly passed along.

Lastly, one can retrieve filters. This can be useful when creating new functions that depend on existing filters, but can not be compounded using the tuple syntax above. For example, one might use one filter or another conditionally. For whatever purpose, the following module function is provided to retreive standard Spyce filters, if needed:

• create( [ fn ] ):
  Returns a filter. The fn parameter can be of type None, function, string, list or tuple and is handled as in the installation functions discussed above.

[[.import name=transform]]
[[\
def tag(o, tags=[], **kwargs):
  import string
  pre = string.join(map(lambda x: '<'+x+'>',tags))
  tags.reverse()
  post = string.join(map(lambda x: '</'+x+'>',tags))
  return pre+str(o)+post
def bold(o, _tag=tag, **kwargs):
  kwargs['tags'] = ['b']
  return apply(_tag, (o,), kwargs)
def bolditalic(o, _tag=tag, **kwargs):
  kwargs['tags'] = ['b','i']
  return apply(_tag, (o,), kwargs)
myfilter = transform.create(['html_encode', bolditalic])
mystring = 'bold and italic unsafe string: < > &'
def simpletable(o, **kwargs):
  s = '<table border=1>'
  for row in o:
    s=s+'<tr>'
    for cell in row:
      s=s+'<td>'+str(cell)+'</td>'
    s=s+'</tr>'
  s = s+'</table>'
  return s
]]
<html><body>
  install an expression filter:<br>
  [[transform.expr(['html_encode', tag])]]
  1.[[=mystring, tags=['b','i'] ]]
  <br>
  [[transform.expr(myfilter)]]
  2.[[=mystring]]
  [[transform.expr()]]
  <p>
  or use a filter directly:<br>
  1.[[=transform.create(['html_encode',tag])(mystring,tags=['b','i'])]]
  <br>
  2.[[=myfilter(mystring)]]
  <p>
  Formatting data in a table...<br>
  [[=simpletable([ [1,2,3], [4,5,6] ])]]
  <p>
  Though the transform module is flexible, <br>
  most users will probably only install the <br>
  <b>html_encode</b> filter.
</body></html>