diff options
Diffstat (limited to 'docs/devel_guide_src/design.tex')
-rwxr-xr-x | docs/devel_guide_src/design.tex | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/docs/devel_guide_src/design.tex b/docs/devel_guide_src/design.tex new file mode 100755 index 0000000..3008a63 --- /dev/null +++ b/docs/devel_guide_src/design.tex @@ -0,0 +1,102 @@ +\section{Design Decisions and Tradeoffs} +\label{design} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Delimiters} +\label{design.Delimiters} + +One of the first decisions we encountered was which delimiter syntax to use. +We decided to follow Velocity's \code{\$placeholder} and \code{\#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 \verb+${longPlaceholder}+ syntax like the shells for cases +where Cheetah or you might be confused where a placeholder ends. Tavis went +ahead and made \verb+${longPlaceholder}+ and \verb+$[longPlaceholder]+ +interchangeable with it since it was trivial to implement. Finally, +the \code{\#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 \code{\$} and \code{\#}, do you?) + +The choice of comment delimiters was more arbitrary. \code{\#\#} and +\code{\#* \ldots *\#} doesn't match any language, but it's reminiscent of +Python and C while also being consistent with our ``\code{\#} is for +directives'' convention. + +We specifically chose {\em 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. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Late binding} +\label{design.lateBinding} + +One of Cheetah's unique features is the name mapper, which lets you write +\code{\$a.b} without worrying much about the type of \code{a} or \code{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 \code{a} is, whether the +the value is a function (autocall it), issue the appropriate Python incantation +to look up \code{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 \code{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 \code{a} later changes +type before a template filling? Answer: unpredictable exceptions occur. What +if \code{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 +\code{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 \code{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 \code{a} or care +whether it exists. This allows users to create \code{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. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Caching framework} +\label{design.cache} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Webware compatibility and the transaction framework} +\label{design.webware} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Single inheritance} +\label{design.singleInheritance} + + + + + +% Local Variables: +% TeX-master: "devel_guide" +% End: |