diff options
Diffstat (limited to 'docs/html/_sources/dev_guide/design.rst.txt')
-rw-r--r-- | docs/html/_sources/dev_guide/design.rst.txt | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/docs/html/_sources/dev_guide/design.rst.txt b/docs/html/_sources/dev_guide/design.rst.txt new file mode 100644 index 0000000..e144a46 --- /dev/null +++ b/docs/html/_sources/dev_guide/design.rst.txt @@ -0,0 +1,98 @@ +Design Decisions and Tradeoffs +============================== + + +Delimiters +---------- + + +One of the first decisions we encountered was which delimiter +syntax to use. We decided to follow Velocity's {$placeholder} and +{#directive} syntax because the former is widely used in other +languages for the same purpose, and the latter stands out in an +HTML or text document. We also implemented the +``${longPlaceholder}`` syntax like the shells for cases where +Cheetah or you might be confused where a placeholder ends. Tavis +went ahead and made ``${longPlaceholder}`` and +``$[longPlaceholder]`` interchangeable with it since it was trivial +to implement. Finally, the {#compiler} directive allows you to +change the delimiters if you don't like them or if they conflict +with the text in your document. (Obviously, if your document +contains a Perl program listing, you don't necessarily want to +backslash each and every {$} and {#}, do you?) + +The choice of comment delimiters was more arbitrary. {##} and {#\* +... \*#} doesn't match any language, but it's reminiscent of Python +and C while also being consistent with our "{#} is for directives" +convention. + +We specifically chose { not} to use pseudo HTML tags for +placeholders and directives, as described more thoroughly in the +Cheetah Users' Guide introduction. Pseudo HTML tags may be easier +to see in a visual editor (supposedly), but in text editors they're +hard to distinguish from "real" HTML tags unless you look closely, +and they're many more keystrokes to type. Also, if you make a +mistake, the tag will show up as literal text in the rendered HTML +page where it will be easy to notice and eradicate, rather than +disappearing as bogus HTML tags do in browsers. + +Late binding +------------ + + +One of Cheetah's unique features is the name mapper, which lets you +write {$a.b} without worrying much about the type of {a} or {b}. +Prior to version 0.9.7, Cheetah did the entire NameMapper lookup at +runtime. This provided maximum flexibility at the expense of speed. +Doing a NameMapper lookup is intrinsically more expensive than an +ordinary Python expression because Cheetah has to decide what type +of container {a} is, whether the the value is a function (autocall +it), issue the appropriate Python incantation to look up {b} in it, +autocall again if necessary, and then convert the result to a +string. + +To maximize run-time (filling-time) performance, Cheetah 0.9.7 +pushed much of this work back into the compiler. The compiler +looked up {a} in the searchList at compile time, noted its type, +and generated an eval'able Python expression based on that. + +This approach had two significant drawbacks. What if {a} later +changes type before a template filling? Answer: unpredictable +exceptions occur. What if {a} does not exist in the searchList at +compile time? Answer: the template can't compile. + +To prevent these catastrophes, users were required to prepopulate +the searchList before instantiating the template instance, and then +not to change {a}'s type. Static typing is repugnant in a dynamic +language like Python, and having to prepopulate the searchList made +certain usages impossible. For example, you couldn't instantiate +the template object without a searchList and then set {self} +attributes to specify the values. + +After significant user complaints about the fragility of this +system, Tavis rewrote placeholder handling, and in version 0.9.8a3 +(August 2001), Tavis moved the name mapper lookup back into +runtime. Performance wasn't crippled because he discovered that +writing a C version of the name mapper was easier than anticipated, +and the C version completed the lookup quickly. Now Cheetah had +"late binding", meaning the compiler does not look up {a} or care +whether it exists. This allows users to create {a} or change its +type anytime before a template filling. + +The lesson we learned is that it's better to decide what you want +and then figure out how to do it, rather than assuming that certain +goals are unattainable due to performance considerations. + +Caching framework +----------------- + + +Webware compatibility and the transaction framework +--------------------------------------------------- + + +Single inheritance +------------------ + + + |