expander - Procedures to process templates and expand text.
package require Tcl 8.2
package require textutil::expander ?1.2.1?
The Tcl subst command is often used to support a kind of template processing. Given a string with embedded variables or function calls, subst will interpolate the variable and function values, returning the new string:
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% subst {$greeting, [place]!}
Howdy, World!
%
|
By defining a suitable set of Tcl commands, subst can be used to implement a markup language similar to HTML.
The subst command is efficient, but it has three drawbacks for this kind of template processing:
At present, expander solves the first two problems; eventually it will solve the third problem as well.
The following section describes the command API to the expander; this is followed by the tutorial sections, beginning at TUTORIAL: Basics.
The textutil::expander package provides only one command, described below. The rest of the section is taken by a description of the methods for the expander objects created by this command.
expanderName option ?arg arg ...? |
The following commands are possible for expander objects:
To begin, create an expander object:
% package require expander 1.2 % ::expander::expander myexp ::myexp % |
The created ::myexp object can be used to expand text strings containing embedded Tcl commands. By default, embedded commands are delimited by square brackets. Note that expander doesn't attempt to interpolate variables, since variables can be referenced by embedded commands:
% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% ::myexp expand {[set greeting], [place]!}
Howdy, World!
%
|
An expander macro is simply a Tcl script embedded within a text string. Expander evaluates the script in the global context, and replaces it with its result string. For example,
% set greetings {Howdy Hi "What's up"}
Howdy Hi "What's up"
% ::myexp expand {There are many ways to say "Hello, World!":
[set result {}
foreach greeting $greetings {
append result "$greeting, World!\\n"
}
set result]
And that's just a small sample!}
There are many ways to say "Hello, World!":
Howdy, World!
Hi, World!
What's up, World!
And that's just a small sample!
%
|
More typically, macro commands are used to create a markup language. A macro command is just a Tcl command that returns an output string. For example, expand can be used to implement a generic document markup language that can be retargeted to HTML or any other output format:
% proc bold {} {return "<b>"}
% proc /bold {} {return "</b>"}
% ::myexp expand {Some of this text is in [bold]boldface[/bold]}
Some of this text is in <b>boldface</b>
%
|
The above definitions of bold and /bold returns HTML, but such commands can be as complicated as needed; they could, for example, decide what to return based on the desired output format.
By default, embedded macros are enclosed in square brackets, [ and ]. If square brackets need to be included in the output, the input can contain the lb and rb commands. Alternatively, or if square brackets are objectionable for some other reason, the macro expansion brackets can be changed to any pair of non-empty strings.
The setbrackets command changes the brackets permanently. For example, you can write pseudo-html by change them to < and >:
% ::myexp setbrackets < >
% ::myexp expand {<bold>This is boldface</bold>}
<b>This is boldface</b>
|
Alternatively, you can change the expansion brackets temporarily by passing the desired brackets to the expand command:
% ::myexp setbrackets "\\[" "\\]"
% ::myexp expand {<bold>This is boldface</bold>} {< >}
<b>This is boldface</b>
%
|
By default, macros are evaluated using the Tcl uplevel #0 command, so that the embedded code executes in the global context. The application can provide a different evaluation command using evalcmd; this allows the application to use a safe interpreter, for example, or even to evaluated something other than Tcl code. There is one caveat: to be recognized as valid, a macro must return 1 when passed to Tcl's "info complete" command.
For example, the following code "evaluates" each macro by returning the macro text itself.
proc identity {macro} {return $macro}
::myexp evalcmd identity
|
Often it's desirable to define a pair of macros which operate in some way on the plain text between them. Consider a set of macros for adding footnotes to a web page: one could have implement something like this:
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote "See Candide, by Voltaire"]
|
The footnote macro would, presumably, assign a number to this footnote and save the text to be formatted later on. However, this solution is ugly if the footnote text is long or should contain additional markup. Consider the following instead:
Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote]See [bookTitle "Candide"], by
[authorsName "Voltaire"], for more information.[/footnote]
|
Here the footnote text is contained between footnote and /footnote macros, continues onto a second line, and contains several macros of its own. This is both clearer and more flexible; however, with the features presented so far there's no easy way to do it. That's the purpose of the context stack.
All macro expansion takes place in a particular context. Here, the footnote macro pushes a new context onto the context stack. Then, all expanded text gets placed in that new context. /footnote retrieves it by popping the context. Here's a skeleton implementation of these two macros:
proc footnote {} {
::myexp cpush footnote
}
proc /footnote {} {
set footnoteText [::myexp cpop footnote]
# Save the footnote text, and return an appropriate footnote
# number and link.
}
|
The cpush command pushes a new context onto the stack; the argument is the context's name. It can be any string, but would typically be the name of the macro itself. Then, cpop verifies that the current context has the expected name, pops it off of the stack, and returns the accumulated text.
Expand provides several other tools related to the context stack. Suppose the first macro in a context pair takes arguments or computes values which the second macro in the pair needs. After calling cpush, the first macro can define one or more context variables; the second macro can retrieve their values any time before calling cpop. For example, suppose the document must specify the footnote number explicitly:
proc footnote {footnoteNumber} {
::myexp cpush footnote
::myexp csave num $footnoteNumber
# Return an appropriate link
}
proc /footnote {} {
set footnoteNumber [::myexp cget num]
set footnoteText [::myexp cpop footnote]
# Save the footnote text and its footnoteNumber for future
# output.
}
|
At times, it might be desirable to define macros that are valid only within a particular context pair; such macros should verify that they are only called within the correct context using either cis or cname.
expander was written by William H. Duquette; it is a repackaging of the central algorithm of the expand macro processing tool.
http://www.wjduquette.com/expand, regexp, split, string
string, template processing, text expansion
Copyright © William H. Duquette, http://www.wjduquette.com/expand