maptemplate(n): String Map Templates -- quill(n)
SYNOPSIS
DESCRIPTION
Defining Templates
Initialization Bodies
Backslash Substitution
Two Caveats
Templates are Outdented
COMMANDS
AUTHOR
SEE ALSO
package require quill 1.0
namespace import ::quill::*
maptemplate name arglist ?initbody? template
mapsubst template
maptemplate(n) contains commands for creating text templates
based on Tcl's string map
command. These commands are similar
to those defined in template(n), but because they do not
use Tcl interpolation syntax they are much better suited to the
generation of Tcl code.
The maptemplate command define a template. A template is a
like a Tcl proc, but its body is a template string into which
values can be substituted. Replacement arguments are specified
by the arguments to the template, and are placed in the body string
with a "%" prefix. For example
% maptemplate greeting {name} {Hello, %name!}
::greeting
% greeting World
Hello, World!
%
The template shown is equivalent to this Tcl proc:
proc greeting {name} {
return [mapsubst {Hello, %name}]
}
Sometimes a maptemplate requires
some initialization of variables or other processing that can't
conveniently be done in the template string itself. Consequently,
maptemplate allows the caller to define an "initialization" body.
This is just a block of Tcl code that's called just before the
template is expanded. It usually defines variables that are then
substituted into the template.
Suppose, for example, a template argument should be converted to
upper case. Compare
maptemplate greeting {name} {Hello, [string toupper %name]}
with
maptemplate greeting {name} {
set name [string toupper $name]
} {Hello, %name!}
The second separates the data processing from the template string, and so
is clearer.
Templates for Tcl code will often contain backslashes as a line
continuation character. Tcl's parser does the line continuation
processing when the template is defined, meaning that the continued
lines will appear in the output all on one single line. For example,
the template string
list \
one \
two \
thre
will product the output
list one two three
This can be avoided by doubling the backslashes in the input:
list \\
one \\
two \\
three
First, only local scalar variables are available
for interpolation. Arrays and globals are not. Second, when generating
Tcl code, it is up to the caller to make sure that interpolated lists
and other values containing white space are quoted properly in the
template.
It's normal when using templates to indent the template string,
but the output code block should usually be at the left margin.
Consequently, mapsubst always passes the template through the
outdent command.
maptemplate(n) defines the following commands:
- maptemplate name arglist ?initbody? template
-
Defines a new command with the specified name and
arglist. The template argument is a string
which may contain "%var" conversions. When the new command
is called, the template is passed to mapsubst, and
the result is returned.
If the initbody is specified, it contains Tcl code to
be executed before the template is expanded.
Normally, the only variables which will be in scope when the
template string is expanded are the template command's
arguments; the initbody is used to initialize
other local scalar variables for inclusion in the template.
- mapsubst template
-
The mapsubst command interpolates local scalar variable values
into the template string. It retrieves the names and values
of all local variables in its caller's context and builds a
string map
dictionary, first prefixing the variable names
with "%". Then it calls string map
on the template using
the dictionary, replacing "%var" with the value of variable
var.
Double backslashes in the template are replaced with single
backslashes. See Backslash Substitution.
Note that only local (procedure arguments and local variables)
scalar variables are substituted.
Array variables could be supported, if necessary.
Will Duquette
quill(n).
Generated from maptemplate.manpage on Sat Nov 08 09:38:04 PST 2014