diff options
Diffstat (limited to 'docs/html/_sources/dev_guide/placeholders.rst.txt')
| -rw-r--r-- | docs/html/_sources/dev_guide/placeholders.rst.txt | 489 |
1 files changed, 0 insertions, 489 deletions
diff --git a/docs/html/_sources/dev_guide/placeholders.rst.txt b/docs/html/_sources/dev_guide/placeholders.rst.txt deleted file mode 100644 index 60aa0d2..0000000 --- a/docs/html/_sources/dev_guide/placeholders.rst.txt +++ /dev/null @@ -1,489 +0,0 @@ -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. - - |