summaryrefslogtreecommitdiff
path: root/docs/dev_guide/placeholders.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/dev_guide/placeholders.rst')
-rw-r--r--docs/dev_guide/placeholders.rst489
1 files changed, 489 insertions, 0 deletions
diff --git a/docs/dev_guide/placeholders.rst b/docs/dev_guide/placeholders.rst
new file mode 100644
index 0000000..60aa0d2
--- /dev/null
+++ b/docs/dev_guide/placeholders.rst
@@ -0,0 +1,489 @@
+Placeholders
+============
+
+(placeholders)
+
+Simple placeholders
+-------------------
+
+(placeholders.simple)
+
+Let's add a few $placeholders to our template:
+
+::
+
+ >>> from Cheetah.Template import Template
+ >>> values = {'what': 'surreal', 'punctuation': '?'}
+ >>> t = Template("""\
+ ... Hello, $what world$punctuation
+ ... One of Python's least-used functions is $xrange.
+ ... """, [values])
+ >>> print t
+ Hello, surreal world?
+ One of Python's least-used functions is <built-in function xrange>.
+
+ >>> print t.generatedModuleCode()
+ 1 #!/usr/bin/env python
+
+ 2 """
+ 3 Autogenerated by CHEETAH: The Python-Powered Template Engine
+ 4 CHEETAH VERSION: 0.9.12
+ 5 Generation time: Sun Apr 21 00:53:01 2002
+ 6 """
+
+ 7 __CHEETAH_genTime__ = 'Sun Apr 21 00:53:01 2002'
+ 8 __CHEETAH_version__ = '0.9.12'
+
+ 9 ##################################################
+ 10 ## DEPENDENCIES
+
+ 11 import sys
+ 12 import os
+ 13 import os.path
+ 14 from os.path import getmtime, exists
+ 15 import time
+ 16 import types
+ 17 from Cheetah.Template import Template
+ 18 from Cheetah.DummyTransaction import DummyTransaction
+ 19 from Cheetah.NameMapper import NotFound, valueForName,
+ valueFromSearchList
+ 20 import Cheetah.Filters as Filters
+ 21 import Cheetah.ErrorCatchers as ErrorCatchers
+
+ 22 ##################################################
+ 23 ## MODULE CONSTANTS
+
+ 24 try:
+ 25 True, False
+ 26 except NameError:
+ 27 True, False = (1==1), (1==0)
+
+ 28 ##################################################
+ 29 ## CLASSES
+
+ 30 class GenTemplate(Template):
+ 31 """
+ 32
+ 33 Autogenerated by CHEETAH: The Python-Powered Template Engine
+ 34 """
+
+ 35 ##################################################
+ 36 ## GENERATED METHODS
+
+
+::
+
+ 37 def __init__(self, *args, **KWs):
+ 38 """
+ 39
+ 40 """
+
+ 41 Template.__init__(self, *args, **KWs)
+
+ 42 def respond(self,
+ 43 trans=None,
+ 44 dummyTrans=False,
+ 45 VFS=valueFromSearchList,
+ 46 VFN=valueForName,
+ 47 getmtime=getmtime,
+ 48 currentTime=time.time):
+
+
+ 49 """
+ 50 This is the main method generated by Cheetah
+ 51 """
+
+ 52 if not trans:
+ 53 trans = DummyTransaction()
+ 54 dummyTrans = True
+ 55 write = trans.response().write
+ 56 SL = self._searchList
+ 57 filter = self._currentFilter
+ 58 globalSetVars = self._globalSetVars
+ 59
+ 60 ########################################
+ 61 ## START - generated method body
+ 62
+ 63 write('Hello, ')
+ 64 write(filter(VFS(SL,"what",1))) # generated from '$what' at
+ # line 1, col 8.
+ 65 write(' world')
+ 66 write(filter(VFS(SL,"punctuation",1))) # generated from
+ # '$punctuation' at line 1, col 19.
+ 67 write("\nOne of Python's least-used methods is ")
+ 68 write(filter(xrange)) # generated from '$xrange' at line 2,
+ # col 39.
+ 69 write('.\n')
+ 70
+ 71 ########################################
+ 72 ## END - generated method body
+ 73
+ 74 if dummyTrans:
+ 75 return trans.response().getvalue()
+ 76 else:
+ 77 return ""
+
+::
+
+ 78
+ 79 ##################################################
+ 80 ## GENERATED ATTRIBUTES
+
+ 81 __str__ = respond
+ 82 _mainCheetahMethod_for_GenTemplate= 'respond'
+
+ 83 # CHEETAH was developed by Tavis Rudd, Chuck Esterbrook, Ian Bicking
+ # and Mike Orr;
+ 84 # with code, advice and input from many other volunteers.
+ 85 # For more information visit http://cheetahtemplate.org/
+
+ 86 ##################################################
+ 87 ## if run from command line:
+ 88 if __name__ == '__main__':
+ 89 GenTemplate().runAsMainProgram()
+
+
+(Again, I have added line numbers and split the lines as in the
+previous chapter.)
+
+This generated template module is different from the previous one
+in several trivial respects and one important respect. Trivially,
+{.\_filePath} and {.\_fileMtime} are not updated in
+{.\_\_init\_\_}, so they inherit the value {None} from {Template}.
+Also, that if-stanza in {.respond} that recompiles the template if
+the source file changes is missing - because there is no source
+file. So this module is several lines shorter than the other one.
+
+But the important way this module is different is that instead of
+the one {write} call outputting a string literal, this module has a
+series of {write} calls (lines 63-69) outputting successive chunks
+of the template. Regular text has been translated into a string
+literal, and placeholders into function calls. Every placeholder is
+wrapped inside a {filter} call to apply the current output filter.
+(The default output filter converts all objects to strings, and
+{None} to {""}.)
+
+Placeholders referring to a Python builtin like {xrange} (line 68)
+generate a bare variable name. Placeholders to be looked up in the
+searchList have a nested function call; e.g.,
+
+::
+
+ write(filter(VFS(SL,"what",1))) # generated from '$what' at line 1, col 8.
+
+{VFS}, remember, is a function imported from {Cheetah.NameMapper}
+that looks up a value in a searchList. So we pass it the
+searchList, the name to look up, and a boolean (1) indicating we
+want autocalling. (It's {1} rather than {True} because it's
+generated from an {and} expression, and that's what Python 2.2
+outputs for true {and} expressions.)
+
+Complex placeholders
+--------------------
+
+(placeholders.complex)
+
+Placeholders can get far more complicated than that. This example
+shows what kind of code the various NameMapper features produce.
+The formulas are taken from Cheetah's test suite, in the
+{Cheetah.Tests.SyntaxAndOutput.Placeholders} class.
+
+::
+
+ 1 placeholder: $aStr
+ 2 placeholders: $aStr $anInt
+ 2 placeholders, back-to-back: $aStr$anInt
+ 1 placeholder enclosed in {}: ${aStr}
+ 1 escaped placeholder: \$var
+ func placeholder - with (): $aFunc()
+ func placeholder - with (int): $aFunc(1234)
+ func placeholder - with (string): $aFunc('aoeu')
+ func placeholder - with ('''\nstring'\n'''): $aFunc('''\naoeu'\n''')
+ func placeholder - with (string*int): $aFunc('aoeu'*2)
+ func placeholder - with (int*float): $aFunc(2*2.0)
+ Python builtin values: $None $True $False
+ func placeholder - with ($arg=float): $aFunc($arg=4.0)
+ deeply nested argstring: $aFunc( $arg = $aMeth( $arg = $aFunc( 1 ) ) ):
+ function with None: $aFunc(None)
+ autocalling: $aFunc! $aFunc().
+ nested autocalling: $aFunc($aFunc).
+ list subscription: $aList[0]
+ list slicing: $aList[:2]
+ list slicing and subcription combined: $aList[:2][0]
+ dict - NameMapper style: $aDict.one
+ dict - Python style: $aDict['one']
+ dict combined with autocalled string method: $aDict.one.upper
+ dict combined with string method: $aDict.one.upper()
+ nested dict - NameMapper style: $aDict.nestedDict.two
+ nested dict - Python style: $aDict['nestedDict']['two']
+ nested dict - alternating style: $aDict['nestedDict'].two
+ nested dict - NameMapper style + method: $aDict.nestedDict.two.upper
+ nested dict - alternating style + method: $aDict['nestedDict'].two.upper
+ nested dict - NameMapper style + method + slice: $aDict.nestedDict.two.upper[:4]
+ nested dict - Python style, variable key: $aDict[$anObj.meth('nestedDict')].two
+ object method: $anObj.meth1
+ object method + complex slice: $anObj.meth1[0: ((4/4*2)*2)/$anObj.meth1(2) ]
+ very complex slice: $( anObj.meth1[0: ((4/4*2)*2)/$anObj.meth1(2) ] )
+ $_('a call to gettext')
+
+We'll need a big program to set up the placeholder values. Here it
+is:
+
+::
+
+ #!/usr/bin/env python
+ from ComplexExample import ComplexExample
+
+ try: # Python >= 2.2.1
+ True, False
+ except NameError: # Older Python
+ True, False = (1==1), (1==0)
+
+ class DummyClass:
+ _called = False
+ def __str__(self):
+ return 'object'
+
+ def meth(self, arg="arff"):
+ return str(arg)
+
+ def meth1(self, arg="doo"):
+ return arg
+
+ def meth2(self, arg1="a1", arg2="a2"):
+ return str(arg1) + str(arg2)
+
+ def callIt(self, arg=1234):
+ self._called = True
+ self._callArg = arg
+
+ def dummyFunc(arg="Scooby"):
+ return arg
+
+ defaultTestNameSpace = {
+ 'aStr':'blarg',
+ 'anInt':1,
+ 'aFloat':1.5,
+ 'aList': ['item0','item1','item2'],
+ 'aDict': {'one':'item1',
+ 'two':'item2',
+ 'nestedDict':{1:'nestedItem1',
+ 'two':'nestedItem2'
+ },
+ 'nestedFunc':dummyFunc,
+ },
+ 'aFunc': dummyFunc,
+ 'anObj': DummyClass(),
+ 'aMeth': DummyClass().meth1,
+ '_': lambda x: 'translated ' + x
+ }
+
+ print ComplexExample( searchList=[defaultTestNameSpace] )
+
+Here's the output:
+
+::
+
+ 1 placeholder: blarg
+ 2 placeholders: blarg 1
+ 2 placeholders, back-to-back: blarg1
+ 1 placeholder enclosed in {}: blarg
+ 1 escaped placeholder: $var
+ func placeholder - with (): Scooby
+ func placeholder - with (int): 1234
+ func placeholder - with (string): aoeu
+ func placeholder - with ('''\nstring'\n'''):
+ aoeu'
+
+ func placeholder - with (string*int): aoeuaoeu
+ func placeholder - with (int*float): 4.0
+ Python builtin values: 1 0
+ func placeholder - with ($arg=float): 4.0
+ deeply nested argstring: 1:
+ function with None:
+ autocalling: Scooby! Scooby.
+ nested autocalling: Scooby.
+ list subscription: item0
+ list slicing: ['item0', 'item1']
+ list slicing and subcription combined: item0
+ dict - NameMapper style: item1
+ dict - Python style: item1
+ dict combined with autocalled string method: ITEM1
+ dict combined with string method: ITEM1
+ nested dict - NameMapper style: nestedItem2
+ nested dict - Python style: nestedItem2
+ nested dict - alternating style: nestedItem2
+ nested dict - NameMapper style + method: NESTEDITEM2
+ nested dict - alternating style + method: NESTEDITEM2
+ nested dict - NameMapper style + method + slice: NEST
+ nested dict - Python style, variable key: nestedItem2
+ object method: doo
+ object method + complex slice: do
+ very complex slice: do
+ translated a call to gettext
+
+And here - tada! - is the generated module. To save space, I've
+included only the lines containing the {write} calls. The rest of
+the module is the same as in the first example, chapter
+pyModules.example. I've split some of the lines to make them fit on
+the page.
+
+::
+
+ 1 write('1 placeholder: ')
+ 2 write(filter(VFS(SL,"aStr",1))) # generated from '$aStr' at line 1, col 16.
+ 3 write('\n2 placeholders: ')
+ 4 write(filter(VFS(SL,"aStr",1))) # generated from '$aStr' at line 2, col 17.
+ 5 write(' ')
+ 6 write(filter(VFS(SL,"anInt",1)))
+ # generated from '$anInt' at line 2, col 23.
+ 7 write('\n2 placeholders, back-to-back: ')
+ 8 write(filter(VFS(SL,"aStr",1))) # generated from '$aStr' at line 3, col 31.
+ 9 write(filter(VFS(SL,"anInt",1)))
+ # generated from '$anInt' at line 3, col 36.
+ 10 write('\n1 placeholder enclosed in {}: ')
+ 11 write(filter(VFS(SL,"aStr",1))) # generated from '${aStr}' at line 4,
+ # col 31.
+ 12 write('\n1 escaped placeholder: $var\nfunc placeholder - with (): ')
+ 13 write(filter(VFS(SL,"aFunc",0)())) # generated from '$aFunc()' at line 6,
+ # col 29.
+ 14 write('\nfunc placeholder - with (int): ')
+ 15 write(filter(VFS(SL,"aFunc",0)(1234))) # generated from '$aFunc(1234)' at
+ # line 7, col 32.
+ 16 write('\nfunc placeholder - with (string): ')
+ 17 write(filter(VFS(SL,"aFunc",0)('aoeu'))) # generated from "$aFunc('aoeu')"
+ # at line 8, col 35.
+ 18 write("\nfunc placeholder - with ('''\\nstring'\\n'''): ")
+ 19 write(filter(VFS(SL,"aFunc",0)('''\naoeu'\n'''))) # generated from
+ # "$aFunc('''\\naoeu'\\n''')" at line 9, col 46.
+ 20 write('\nfunc placeholder - with (string*int): ')
+ 21 write(filter(VFS(SL,"aFunc",0)('aoeu'*2))) # generated from
+ # "$aFunc('aoeu'*2)" at line 10, col 39.
+ 22 write('\nfunc placeholder - with (int*float): ')
+ 23 write(filter(VFS(SL,"aFunc",0)(2*2.0))) # generated from '$aFunc(2*2.0)'
+ # at line 11, col 38.
+ 24 write('\nPython builtin values: ')
+ 25 write(filter(None)) # generated from '$None' at line 12, col 24.
+ 26 write(' ')
+ 27 write(filter(True)) # generated from '$True' at line 12, col 30.
+ 28 write(' ')
+ 29 write(filter(False)) # generated from '$False' at line 12, col 36.
+ 30 write('\nfunc placeholder - with ($arg=float): ')
+ 31 write(filter(VFS(SL,"aFunc",0)(arg=4.0))) # generated from
+ # '$aFunc($arg=4.0)' at line 13, col 40.
+ 32 write('\ndeeply nested argstring: ')
+ 33 write(filter(VFS(SL,"aFunc",0)(
+ arg = VFS(SL,"aMeth",0)( arg = VFS(SL,"aFunc",0)( 1 ) ) )))
+ # generated from '$aFunc( $arg = $aMeth( $arg = $aFunc( 1 ) ) )'
+ # at line 14, col 26.
+ 34 write(':\nfunction with None: ')
+ 35 write(filter(VFS(SL,"aFunc",0)(None))) # generated from '$aFunc(None)' at
+ # line 15, col 21.
+ 36 write('\nautocalling: ')
+ 37 write(filter(VFS(SL,"aFunc",1))) # generated from '$aFunc' at line 16,
+ # col 14.
+ 38 write('! ')
+ 39 write(filter(VFS(SL,"aFunc",0)())) # generated from '$aFunc()' at line 16,
+ # col 22.
+
+::
+
+ 40 write('.\nnested autocalling: ')
+ 41 write(filter(VFS(SL,"aFunc",0)(VFS(SL,"aFunc",1)))) # generated from
+ # '$aFunc($aFunc)' at line 17, col 21.
+ 42 write('.\nlist subscription: ')
+ 43 write(filter(VFS(SL,"aList",1)[0])) # generated from '$aList[0]' at line
+ # 18, col 20.
+ 44 write('\nlist slicing: ')
+ 45 write(filter(VFS(SL,"aList",1)[:2])) # generated from '$aList[:2]' at
+ # line 19, col 15.
+ 46 write('\nlist slicing and subcription combined: ')
+ 47 write(filter(VFS(SL,"aList",1)[:2][0])) # generated from '$aList[:2][0]'
+ # at line 20, col 40.
+ 48 write('\ndict - NameMapper style: ')
+ 49 write(filter(VFS(SL,"aDict.one",1))) # generated from '$aDict.one' at line
+ # 21, col 26.
+ 50 write('\ndict - Python style: ')
+ 51 write(filter(VFS(SL,"aDict",1)['one'])) # generated from "$aDict['one']"
+ # at line 22, col 22.
+ 52 write('\ndict combined with autocalled string method: ')
+ 53 write(filter(VFS(SL,"aDict.one.upper",1))) # generated from
+ # '$aDict.one.upper' at line 23, col 46.
+ 54 write('\ndict combined with string method: ')
+ 55 write(filter(VFN(VFS(SL,"aDict.one",1),"upper",0)())) # generated from
+ # '$aDict.one.upper()' at line 24, col 35.
+ 56 write('\nnested dict - NameMapper style: ')
+ 57 write(filter(VFS(SL,"aDict.nestedDict.two",1))) # generated from
+ # '$aDict.nestedDict.two' at line 25, col 33.
+ 58 write('\nnested dict - Python style: ')
+ 59 write(filter(VFS(SL,"aDict",1)['nestedDict']['two'])) # generated from
+ # "$aDict['nestedDict']['two']" at line 26, col 29.
+ 60 write('\nnested dict - alternating style: ')
+ 61 write(filter(VFN(VFS(SL,"aDict",1)['nestedDict'],"two",1))) # generated
+ # from "$aDict['nestedDict'].two" at line 27, col 34.
+ 62 write('\nnested dict - NameMapper style + method: ')
+ 63 write(filter(VFS(SL,"aDict.nestedDict.two.upper",1))) # generated from
+ # '$aDict.nestedDict.two.upper' at line 28, col 42.
+ 64 write('\nnested dict - alternating style + method: ')
+ 65 write(filter(VFN(VFS(SL,"aDict",1)['nestedDict'],"two.upper",1)))
+ # generated from "$aDict['nestedDict'].two.upper" at line 29, col 43.
+ 66 write('\nnested dict - NameMapper style + method + slice: ')
+
+::
+
+ 67 write(filter(VFN(VFS(SL,"aDict.nestedDict.two",1),"upper",1)[:4]))
+ # generated from '$aDict.nestedDict.two.upper[:4]' at line 30, col 50.
+ 68 write('\nnested dict - Python style, variable key: ')
+ 69 write(filter(VFN(VFS(SL,"aDict",1)
+ [VFN(VFS(SL,"anObj",1),"meth",0)('nestedDict')],"two",1)))
+ # generated from "$aDict[$anObj.meth('nestedDict')].two" at line 31,
+ # col 43.
+ 70 write('\nobject method: ')
+ 71 write(filter(VFS(SL,"anObj.meth1",1))) # generated from '$anObj.meth1' at
+ # line 32, col 16.
+ 72 write('\nobject method + complex slice: ')
+ 73 write(filter(VFN(VFS(SL,"anObj",1),"meth1",1)
+ [0: ((4/4*2)*2)/VFN(VFS(SL,"anObj",1),"meth1",0)(2) ]))
+ # generated from '$anObj.meth1[0: ((4/4*2)*2)/$anObj.meth1(2) ]'
+ # at line 33, col 32.
+ 74 write('\nvery complex slice: ')
+ 75 write(filter(VFN(VFS(SL,"anObj",1),"meth1",1)
+ [0: ((4/4*2)*2)/VFN(VFS(SL,"anObj",1),"meth1",0)(2) ] ))
+ # generated from '$( anObj.meth1[0: ((4/4*2)*2)/$anObj.meth1(2) ] )'
+ # at line 34, col 21.
+ 76 if False:
+ 77 _('foo')
+ 78 write(filter(VFS(SL,"_",0)("a call to gettext")))
+ # generated from "$_('a call to gettext')"
+ # at line 35, col 1.
+ 79 write('\n')
+
+For each placeholder lookup, the the innermost level of nesting is
+a {VFS} call, which looks up the first (leftmost) placeholder
+component in the searchList. This is wrapped by zero or more {VFN}
+calls, which perform Universal Dotted Notation lookup on the next
+dotted component of the placeholder, looking for an attribute or
+key by that name within the previous object (not in the
+searchList). Autocalling is performed by {VFS} and {VFN}: that's
+the reason for their third argument.
+
+Explicit function/method arguments, subscripts and keys (which are
+all expressions) are left unchanged, besides expanding any embedded
+$placeholders in them. This means they must result in valid Python
+expressions, following the standard Python quoting rules.
+
+Built-in Python values ({None}, {True} and {False}) are converted
+to {filter(None)}, etc. They use normal Python variable lookup
+rather than {VFS}. (Cheetah emulates {True} and {False} using
+global variables for Python < 2.2.1, when they weren't builtins
+yet.)
+
+Notice the last line is a call to {\_} (i.e. {gettext}) which is
+used for internationalization (see
+http://docs.python.org/lib/module-gettext.html). The code is
+converted normally, but an {if False} block is used so that gettext
+can successfully mark the string for translation when parsing the
+generated Python. Otherwise, the NameMapper syntax would get in the
+way of this.
+
+
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-29 09:07:20 +0000