tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

maptemplate(n): String Map Templates -- quill(n)

SYNOPSIS
DESCRIPTION
Defining Templates
Initialization Bodies
Backslash Substitution
Two Caveats
Templates are Outdented
COMMANDS
AUTHOR
SEE ALSO

SYNOPSIS

package require quill 1.0
namespace import ::quill::*
maptemplate name arglist ?initbody? template
mapsubst template

DESCRIPTION

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.

Defining Templates

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}]
}

Initialization Bodies

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.

Backslash Substitution

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

Two Caveats

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.

Templates are Outdented

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.

COMMANDS

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.

AUTHOR

Will Duquette

SEE ALSO

quill(n).


Generated from maptemplate.manpage on Sat Nov 08 09:38:04 PST 2014