diff options
Diffstat (limited to 'docs/users_guide_src/glossary.tex')
-rw-r--r-- | docs/users_guide_src/glossary.tex | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/docs/users_guide_src/glossary.tex b/docs/users_guide_src/glossary.tex new file mode 100644 index 0000000..4ee2d9b --- /dev/null +++ b/docs/users_guide_src/glossary.tex @@ -0,0 +1,96 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\section{Vocabulary} +\label{glossary} +\label{vocabulary} + +{\bf Template} is an informal term meaning a template definition, a +template instance or a template class. A {\bf template definition} is what +the human {\bf template maintainer} writes: a string consisting of text, +placeholders and directives. {\bf Placeholders} are variables that will be +looked up when the template is filled. {\bf Directives} are commands to be +executed when the template is filled, or instructions to the Cheetah compiler. +The conventional suffix for a file containing a template definition is +{\bf .tmpl}. + +There are two things you can do with a template: compile it or fill it. +{\bf Filling} is the reason you have a template in the first place: +to get a finished string out of it. Compiling is a necessary prerequisite: the +{\bf Cheetah compiler} takes a template definition and produces Python code +to create the finished string. Cheetah provides several ways to compile +and fill templates, either as one step or two. + +Cheetah's compiler produces a subclass of \code{Cheetah.Template} +specific to that template definition; this is called the {\bf generated +class}. A {\bf template instance} is an instance of a generated class. + +If the user calls the \code{Template} constructor directly (rather than a +subclass constructor), s/he will get what appears to be an instance of +\code{Template} but is actually a subclass created on-the-fly. + +The user can make the subclass explicit by using the ``cheetah compile'' +command to write the template class to a Python module. Such a module is +called a {\bf .py template module}. + +The {\bf Template Definition Language} -- or the ``Cheetah language'' for short +-- is the syntax rules governing placeholders and directives. These are +discussed in sections \ref{language} and following in this Guide. + +To fill a template, you call its {\bf main method}. This is normally +\code{.respond()}, but it may be something else, and you can use the +\code{\#implements} directive to choose the method name. (Section +\ref{inheritanceEtc.implements}. + +A {\bf template-servlet} is a .py template module in a Webware servlet +directory. Such templates can be filled directly through the web by requesting +the URL. ``Template-servlet'' can also refer to the instance being filled by +a particular web request. If a Webware servlet that is not a +template-servlet invokes a template, that template is not a template-servlet +either. + +A {\bf placeholder tag} is the substring in the template +definition that is the placeholder, including the start and end delimeters (if +there is an end delimeter). The {\bf placeholder name} is the same but without +the delimeters. + +Placeholders consist of one or more {\bf identifiers} separated by periods +(e.g., \code{a.b}). Each identifier must follow the same rules as Python +identifiers; that is, a letter or underscore followed by one or more letters, +digits or underscores. (This is the regular expression +\verb+[A-Za-z_][A-Za-z0-9_]*+.) + +The first (or only) identifier of a placeholder name represents a {\bf +variable} to be looked up. Cheetah looks up variables in various {\bf +namespaces}: the searchList, local variables, and certain other places. The +searchList is a list of objects ({\bf containers}) with attributes +and/or keys: each container is a namespace. Every template instance has +exactly one searchList. Identifiers after the first are looked up only in +the parent object. The final value after all lookups have been performed is +the {\bf placeholder value}. + +Placeholders may occur in three positions: top-level, expression and LVALUE. +{\bf Top-level} placeholders are those in ordinary text (``top-level text''). +{\bf Expression} placeholders are those in Python expressions. +{\bf LVALUE} placeholders are those naming a variable to receive a value. +(LVALUE is computerese for ``the left side of the equal sign''.) Section +\ref{language.placeholders.positions} explains the differences between these +three positions. + +The routine that does the placeholder lookups is called the {\bf NameMapper}. +Cheetah's NameMapper supports universal dotted notation and autocalling. +{\bf Universal dotted notation} means that keys may be written as if they were +attributes: \code{a.b} instead of \code{a['b']}. {\bf Autocalling} means that +if any identifier's value is found to be a function or method, Cheetah will +call it without arguments if there is no \verb+()+ following. More about the +NameMapper is in section \ref{language.namemapper}. + +Some directives are multi-line, meaning they have a matching {\bf \#end} tag. +The lines of text between the start and end tags is the {\bf body} of the +directive. Arguments on the same line as the start tag, in contrast, are +considered part of the directive tag. More details are in section +\ref{language.directives.syntax} (Directive Syntax Rules). + +% Local Variables: +% TeX-master: "users_guide" +% End: + +% # vim: sw=4 ts=4 expandtab |