diff options
| -rw-r--r-- | docs/devel_guide_src/output.tex | 134 | ||||
| -rw-r--r-- | docs/devel_guide_src/placeholders.tex | 2 | ||||
| -rw-r--r-- | docs/devel_guide_src/pyModules.tex | 10 | ||||
| -rw-r--r-- | docs/users_guide_src/output.tex | 7 |
4 files changed, 142 insertions, 11 deletions
diff --git a/docs/devel_guide_src/output.tex b/docs/devel_guide_src/output.tex index ea2f5c3..d400584 100644 --- a/docs/devel_guide_src/output.tex +++ b/docs/devel_guide_src/output.tex @@ -1,6 +1,140 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Directives: Output} \label{output} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{\#echo} +\label{output.echo} + +The template: +\begin{verbatim} +Here is my #echo ', '.join(['silly']*5) # example +\end{verbatim} + +The output: +\begin{verbatim} +Here is my silly, silly, silly, silly, silly example +\end{verbatim} + +The generated code: +\begin{verbatim} +write('Here is my ') +write(filter(', '.join(['silly']*5) )) +write(' example\n') +\end{verbatim} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{\#silent} +\label{output.silent} + +The template: +\begin{verbatim} +Here is my #silent ', '.join(['silly']*5) # example +\end{verbatim} + +The output: +\begin{verbatim} +Here is my example +\end{verbatim} + +The generated code: +\begin{verbatim} + write('Here is my ') + ', '.join(['silly']*5) + write(' example\n') +\end{verbatim} + +OK, it's not quite covert because that extra space gives it away, but it +almost succeeds. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Caching placeholders and \#cache} +\label{output.cache} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Dynamic placeholder -- no cache} +\label{output.cache.dynamic} + +The template: +\begin{verbatim} +Dynamic variable: $voom +\end{verbatim} + +The output: +\begin{verbatim} +Dynamic variable: Voom! +\end{verbatim} + +The generated code: +\begin{verbatim} +write('Dynamic variable: ') +write(filter(VFS(SL,"voom",1))) # generated from '$voom' at line 1, col 20. +write('\n') +\end{verbatim} + +Just what we expected, like any other dynamic placeholder. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\subsection{Static placeholder} +\label{output.cache.static} + +The template: +\begin{verbatim} +Cached variable: $*voom +\end{verbatim} + +The output: +\begin{verbatim} +Cached variable: Voom! +\end{verbatim} + +The generated code, with line numbers: +\begin{verbatim} + 1 write('Cached variable: ') + 2 ## START CACHE REGION: at line, col (1, 19) in the source. + 3 RECACHE = True + 4 if not self._cacheData.has_key('19760169'): + 5 pass + 6 else: + 7 RECACHE = False + 8 if RECACHE: + 9 orig_trans = trans +10 trans = cacheCollector = DummyTransaction() +11 write = cacheCollector.response().write +12 write(filter(VFS(SL,"voom",1))) # generated from '$*voom' at line 1, + # col 19. +13 trans = orig_trans +14 write = trans.response().write +15 self._cacheData['19760169'] = cacheCollector.response().getvalue() +16 del cacheCollector +17 write(self._cacheData['19760169']) +18 ## END CACHE REGION + +19 write('\n') +\end{verbatim} + +That one little star generated a whole lotta code. First, instead of an +ordinary \code{VFS} lookup (searchList) lookup, it converted the +placeholder to a lookup in the \code{.\_cacheData} dictionary. Cheetah also +generated a unique key (\code{'19760169'}) for our cached item -- this is its +cache ID. + +Second, Cheetah put a pair of if-blocks before the \code{write}. The first +(lines 3-7) determine whether the cache value is missing or out of date, and +sets local variable \code{RECHARGE} true or false. +This stanza may look unnecessarily verbose -- lines 3-7 could be eliminated if +line 8 was changed to +\begin{verbatim} +if not self._cacheData.has_key('19760169'): +\end{verbatim} +-- but this model is expandable for some of the cache features we'll see below. + +The second if-block, lines 8-16, do the cache updating if necessary. +Clearly, the programmer is trying to stick as close to normal (dynamic) +workflow as possible. Remember that \code{write}, even though it looks like a +local function, is actually a method of a file-like object. So we create a +temporary file-like object to divert the \code{write} object into, then read +the result and stuff it into the cache. % Local Variables: % TeX-master: "devel_guide" diff --git a/docs/devel_guide_src/placeholders.tex b/docs/devel_guide_src/placeholders.tex index c2d7de9..44d325e 100644 --- a/docs/devel_guide_src/placeholders.tex +++ b/docs/devel_guide_src/placeholders.tex @@ -313,7 +313,7 @@ very complex slice: do And here -- tada! -- is the generated module. To save space, I've included only the lines containing the \code{write} calls. The rest of the module is the same as in the first example, chapter -\ref{pyModules.example}. I've truncated some of the lines to make them fit on +\ref{pyModules.example}. I've split some of the lines to make them fit on the page. \begin{verbatim} diff --git a/docs/devel_guide_src/pyModules.tex b/docs/devel_guide_src/pyModules.tex index 1a91b4c..f8ea009 100644 --- a/docs/devel_guide_src/pyModules.tex +++ b/docs/devel_guide_src/pyModules.tex @@ -11,20 +11,20 @@ placeholder and directive in terms of the changes it creates in the module. \subsection{An example} \label{pyModules.example} -Our first template, following a long noble tradition in computer tutorials, -produces a familiar, friendly greeting. Here's the template: +Our first template follows a long noble tradition in computer tutorials. +It produces a familiar, friendly greeting. Here's the template: \begin{verbatim} Hello, world! \end{verbatim} -... here's the output: +... the output: \begin{verbatim} Hello, world! \end{verbatim} -... and here's the .py template module cheetah-compile produced, with line +... and the .py template module cheetah-compile produced, with line numbers added: % @@MO: Is it possible to print the line numbers gray instead of black? @@ -210,7 +210,7 @@ a string or file object. The stanza recompiles the template if the source file has changed. Lines 70-74 seem to be redundant with 75-83: both fill the template and send the output. The reason the first set of lines exists is because the second set may become invalid when the template is -recompiled. (This is for \em{re}\ compilation only. The initial compilation +recompiled. (This is for {\em re}\ compilation only. The initial compilation happened in the \code{.\_\_init\_\_} method if the template wasn't precompiled.) diff --git a/docs/users_guide_src/output.tex b/docs/users_guide_src/output.tex index 63ac54c..f1da8cb 100644 --- a/docs/users_guide_src/output.tex +++ b/docs/users_guide_src/output.tex @@ -33,10 +33,6 @@ The \code{\#echo} directive is used to echo the output from expressions that can't be written as simple \$placeholders. It serves the same purpose as ASP's $<$\%=EXPR\%$>$ tag. -% @@MSO: The '<' and '>' on the previous line are showing up as Spanish -% inverted '?' and '!' in my gv. Backslashing them caused an error. Only -% placing them inside '$$' worked. - \begin{verbatim} Here is my #echo ', '.join(['silly']*5) # example \end{verbatim} @@ -111,7 +107,8 @@ whether the template is being filled that frequently or not. Keep this in mind when setting refresh times for CPU-intensive or I/O intensive operations. -% @@MO: Is it $*5*{var} or ${*5*var}? We should mention. +If you're using the long placeholder syntax, \verb+${}+, the braces go only +around the placeholder name: \verb+$*.5h*{var.func('arg')}+. Sometimes it's preferable to explicitly invalidate a cached item whenever you say so rather than at certain time intervals. You can't do this with |