\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:      
