Cover string.Template in the tutorial's library tour.

1 files changed, 77 insertions, 0 deletions

diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 73222ff..102ffea 100644
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -4836,6 +4836,83 @@ with group separators:
 \end{verbatim}
 
 
+\section{Templating\label{templating}}
+
+The \ulink{\module{string}}{../lib/module-string.html} module includes a
+versatile \class{Template} class with a simplified syntax suitable for
+editing by end-users.  This allows users to customize their applications
+without having to alter the Python program.
+
+The format uses \samp{\$} for placeholder names that are valid Python
+identifiers (alphanumeric characters and underscores).  Surrounding the
+placeholder with braces allows it to be followed by more alphanumeric letters
+with no intervening spaces.  \samp{\$\$} is the way to create a single escaped
+\samp{\$}:
+
+\begin{verbatim}
+>>> from string import Template
+>>> t = Template('${village}folk send $$10 to $cause.')
+>>> t.substitute(village='nottingham', cause='the ditch fund')
+'nottinghamfolk send $10 to the ditch fund.'
+\end{verbatim}
+
+The \method{substitute} method raises a \exception{KeyError} when a
+placeholder is not supplied in a dictionary or a keyword argument.
+For mail-merge style applications, user supplied data may be incomplete
+and the \method{safe_substitute} method may be more appropriate --- it
+will leave placeholders unchanged if data is missing:
+
+\begin{verbatim}
+>>> t = Template('Return the $item to $owner.')
+>>> d = dict(item='unladen swallow')
+>>> t.substitute(d)
+Traceback (most recent call last):
+  . . .
+KeyError: 'owner'
+>>> t.safe_substitute(d)
+'Return the unladen swallow to $owner.'
+\end{verbatim}
+
+Template subclasses can specify a custom delimiter.  For example, a batch
+renaming utility for a photo browser may elect to use percent signs for
+metadata such as the current date, image sequence number, or file format:
+
+\begin{verbatim}
+>>> import time, os.path
+>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
+>>> class BatchRename(Template):
+...     delimiter = '%'
+>>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format):  ')
+Enter rename style (%d-date %n-seqnum %f-format):  Ashley_%n%f
+
+>>> rename = BatchRename(fmt)
+>>> date = time.strftime('%d%b%y')
+>>> for i, filename in enumerate(photofiles):
+...     base, ext = os.path.splitext(filename)
+...     newname = rename.substitute(d=date, n=i, f=ext)
+...     print '%s --> %s' % (filename, newname)
+
+img_1074.jpg --> Ashley_0.jpg
+img_1076.jpg --> Ashley_1.jpg
+img_1077.jpg --> Ashley_2.jpg
+\end{verbatim}
+
+For internationalization applications, it may be appropriate to coerce all
+templates to \class{unicode}.  This can be done with subclassing and
+overriding the \method{__init__} method:
+
+\begin{verbatim}
+>>> class UnicodeTemplate(unicode, Template):
+...     def __init__(self, template):
+...         self.template = unicode(template)
+>>> t = UnicodeTemplate('Knights who say $what')
+>>> t.substitute(what='Ni')
+u'Knights who say Ni'
+>>> t.capitalize()
+u'Knights who say $what'
+\end{verbatim}
+
+
 \section{Working with Binary Data Record Layouts\label{binary-formats}}
 
 The \ulink{\module{struct}}{../lib/module-struct.html} module provides