summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorRaymond Hettinger <python@rcn.com>2004-09-14 05:21:42 (GMT)
committerRaymond Hettinger <python@rcn.com>2004-09-14 05:21:42 (GMT)
commit29c6a79b7d33d9fd8a7ed44886e6aad782c2c1b9 (patch)
tree4d4d1b7692fca40d06c3ed1fef0a509f156070cb /Doc
parent6d191113a6c24c5a5c1cd8ade63f5a8f7027b1f4 (diff)
downloadcpython-29c6a79b7d33d9fd8a7ed44886e6aad782c2c1b9.zip
cpython-29c6a79b7d33d9fd8a7ed44886e6aad782c2c1b9.tar.gz
cpython-29c6a79b7d33d9fd8a7ed44886e6aad782c2c1b9.tar.bz2
Cover string.Template in the tutorial's library tour.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/tut/tut.tex77
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