Cheetah/Filters.py

   1 #!/usr/bin/env python
   2 # $Id: Filters.py,v 1.32 2007/03/29 19:31:15 tavis_rudd Exp $
   3 """Filters for the #filter directive; output filters Cheetah's $placeholders .
   4
   5 Meta-Data
   6 ================================================================================
   7 Author: Tavis Rudd <tavis@damnsimple.com>
   8 Version: $Revision: 1.32 $
   9 Start Date: 2001/08/01
  10 Last Revision Date: $Date: 2007/03/29 19:31:15 $
  11 """
  12 __author__ = "Tavis Rudd <tavis@damnsimple.com>"
  13 __revision__ = "$Revision: 1.32 $"[11:-2]
  14
  15 # Additional entities WebSafe knows how to transform.  No need to include
  16 # '<', '>' or '&' since those will have been done already.
  17 webSafeEntities = {' ': '&nbsp;', '"': '&quot;'}
  18
  19 class Error(Exception):
  20     pass
  21
  22 ##################################################
  23 ## BASE CLASS
  24
  25 class Filter(object):
  26     """A baseclass for the Cheetah Filters."""
  27
  28     def __init__(self, template=None):
  29         """Setup a reference to the template that is using the filter instance.
  30         This reference isn't used by any of the standard filters, but is
  31         available to Filter subclasses, should they need it.
  32
  33         Subclasses should call this method.
  34         """
  35         self.template = template
  36
  37     def filter(self, val,
  38                #encoding='utf8',
  39                encoding=None,
  40                str=str,
  41                **kw):
  42         """Pass Unicode strings through unmolested, unless an encoding is specified.
  43         """
  44         if isinstance(val, unicode):
  45             if encoding:
  46                 filtered = val.encode(encoding)
  47             else:
  48                 filtered = val
  49         elif val is None:
  50             filtered = ''
  51         else:
  52             filtered = str(val)
  53         return filtered
  54
  55 RawOrEncodedUnicode = Filter
  56
  57 ##################################################
  58 ## ENHANCED FILTERS
  59
  60 class EncodeUnicode(Filter):
  61     def filter(self, val,
  62                encoding='utf8',
  63                str=str,
  64                **kw):
  65         """Encode Unicode strings, by default in UTF-8.
  66
  67         >>> import Cheetah.Template
  68         >>> t = Cheetah.Template.Template('''
  69         ... $myvar
  70         ... ${myvar, encoding='utf16'}
  71         ... ''', searchList=[{'myvar': u'Asni\xe8res'}],
  72         ... filter='EncodeUnicode')
  73         >>> print t
  74         """
  75         if isinstance(val, unicode):
  76             filtered = val.encode(encoding)
  77         elif val is None:
  78             filtered = ''
  79         else:
  80             filtered = str(val)
  81         return filtered
  82
  83 class MaxLen(Filter):
  84     def filter(self, val, **kw):
  85         """Replace None with '' and cut off at maxlen."""
  86
  87         output = super(MaxLen, self).filter(val, **kw)
  88         if kw.has_key('maxlen') and len(output) > kw['maxlen']:
  89             return output[:kw['maxlen']]
  90         return output
  91
  92 class WebSafe(Filter):
  93     """Escape HTML entities in $placeholders.
  94     """
  95     def filter(self, val, **kw):
  96         s = super(WebSafe, self).filter(val, **kw)
  97         # These substitutions are copied from cgi.escape().
  98         s = s.replace("&", "&amp;") # Must be done first!
  99         s = s.replace("<", "&lt;")
 100         s = s.replace(">", "&gt;")
 101         # Process the additional transformations if any.
 102         if kw.has_key('also'):
 103             also = kw['also']
 104             entities = webSafeEntities   # Global variable.
 105             for k in also:
 106                 if entities.has_key(k):
 107                     v = entities[k]
 108                 else:
 109                     v = "&#%s;" % ord(k)
 110                 s = s.replace(k, v)
 111         # Return the puppy.
 112         return s
 113
 114
 115 class Strip(Filter):
 116     """Strip leading/trailing whitespace but preserve newlines.
 117
 118     This filter goes through the value line by line, removing leading and
 119     trailing whitespace on each line.  It does not strip newlines, so every
 120     input line corresponds to one output line, with its trailing newline intact.
 121
 122     We do not use val.split('\n') because that would squeeze out consecutive
 123     blank lines.  Instead, we search for each newline individually.  This
 124     makes us unable to use the fast C .split method, but it makes the filter
 125     much more widely useful.
 126
 127     This filter is intended to be usable both with the #filter directive and
 128     with the proposed #sed directive (which has not been ratified yet.)
 129     """
 130     def filter(self, val, **kw):
 131         s = super(Strip, self).filter(val, **kw)
 132         result = []
 133         start = 0   # The current line will be s[start:end].
 134         while 1: # Loop through each line.
 135             end = s.find('\n', start)  # Find next newline.
 136             if end == -1:  # If no more newlines.
 137                 break
 138             chunk = s[start:end].strip()
 139             result.append(chunk)
 140             result.append('\n')
 141             start = end + 1
 142         # Write the unfinished portion after the last newline, if any.
 143         chunk = s[start:].strip()
 144         result.append(chunk)
 145         return "".join(result)
 146
 147 class StripSqueeze(Filter):
 148     """Canonicalizes every chunk of whitespace to a single space.
 149
 150     Strips leading/trailing whitespace.  Removes all newlines, so multi-line
 151     input is joined into one ling line with NO trailing newline.
 152     """
 153     def filter(self, val, **kw):
 154         s = super(StripSqueeze, self).filter(val, **kw)
 155         s = s.split()
 156         return " ".join(s)
 157
 158 ##################################################
 159 ## MAIN ROUTINE -- testing
 160
 161 def test():
 162     s1 = "abc <=> &"
 163     s2 = "   asdf  \n\t  1  2    3\n"
 164     print "WebSafe INPUT:", `s1`
 165     print "      WebSafe:", `WebSafe().filter(s1)`
 166
 167     print
 168     print " Strip INPUT:", `s2`
 169     print "       Strip:", `Strip().filter(s2)`
 170     print "StripSqueeze:", `StripSqueeze().filter(s2)`
 171
 172     print "Unicode:", `EncodeUnicode().filter(u'aoeu12345\u1234')`
 173
 174 if __name__ == "__main__":  test()
 175
 176 # vim: shiftwidth=4 tabstop=4 expandtab