1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
|
<html><head>
<title>expander</title>
</head>
<BODY>
<h1>expander</h1>
<h2><a name="synopsis">SYNOPSIS</a></h2>
<pre>
package require expander 1.0
</pre><p>
<h2><a name="description">DESCRIPTION</a></h2>
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:<p>
<pre>% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% subst {$greeting, [place]!}
Howdy, World!
%</pre>
By defining a suitable set of Tcl commands, "subst" can be used to
implement a markup language similar to HTML.<p>
The "subst" command is efficient, but it has three drawbacks for this
kind of template processing:<p>
<ul>
<li> There's no way to identify and process the plain text between two
embedded Tcl commands; that makes it difficult to handle plain
text in a context-sensitive way.<p>
<li> Embedded commands are necessarily bracketed by "[" and
"]"; it's convenient to be able to choose different brackets
in special cases. Someone producing web pages that include a
large quantity of Tcl code examples might easily prefer to use
"<<" and ">>" as the embedded code delimiters instead.<p>
<li> There's no easy way to handle incremental input, as one might
wish to do when reading data from a socket.<p>
</ul>
At present, expander solves the first two problems; eventually it will
solve the third problem as well.<p>
To begin, create an expander object:<p>
<pre>% package require textutil::expander
1.0
% ::textutil::expander myexp
::myexp
%</pre>
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:<p>
<pre>% set greeting "Howdy"
Howdy
% proc place {} {return "World"}
% ::myexp expand {[set greeting], [place]!}
Howdy, World!
%</pre>
<h3><a name="embedding_macros">Embedding Macros</a></h3>
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,
<pre>% 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!
%</pre>
<h3><a name="writing_macro_commands">Writing Macro Commands</a></h3>
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:
<pre>% 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>
%</pre>
The above definition 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.<p>
<h3><a name="changing_the_expansion_brackets">Changing the Expansion Brackets</a></h3>
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 <code><a href="#lb">lb</a></code> and <code><a href="#rb">rb</a></code>
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.<p>
The <code><a href="#setbrackets">setbrackets</a></code> command changes the brackets permanently.
For example, you can write pseudo-html by change them to "<" and ">":<p>
<pre>% ::myexp setbrackets < >
% ::myexp expand {<bold>This is boldface</bold>}
<b>This is boldface</b></pre>
Alternatively, you can change the expansion brackets temporarily by
passing the desired brackets to the <code><a href="#expand">expand</a></code> command:<p>
<pre>% ::myexp setbrackets "\[" "\]"
% ::myexp expand {<bold>This is boldface</bold>} {< >}
<b>This is boldface</b>
%</pre>
<h3><a name="customized_macro_expansion">Customized Macro Expansion</a></h3>
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
<code><a href="#evalcmd">evalcmd</a></code>; 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.<p>
For example, the following code "evaluates" each macro by returning
the macro text itself.<p>
<pre>proc identity {macro} {return $macro}
::myexp evalcmd identity</pre>
<h3><a name="using_the_context_stack">Using the Context Stack</a></h3>
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:<p>
<pre> Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote "See Candide, by Voltaire"]</pre>
The <code>footnote</code> 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:<p>
<pre> Dr. Pangloss, however, thinks that this is the best of all
possible worlds.[footnote]See [bookTitle "Candide"], by
[authorsName "Voltaire"], for more information.[/footnote]</pre>
Here the footnote text is contained between <code>footnote</code> and
<code>/footnote</code> 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.<p>
All macro expansion takes place in a particular context.
Here, the <code>footnote</code> macro pushes a new
context onto the context stack. Then, all expanded text gets placed
in that new context. <code>/footnote</code> retrieves it by popping
the context. Here's a skeleton implementation of these two macros:<p>
<pre> proc footnote {} {
::myexp cpush footnote
}
proc /footnote {} {
set footnoteText [::myexp cpop footnote]
# Save the footnote text, and return an appropriate footnote
# number and link.
} </pre>
The <code><a href="#cpush">cpush</a></code> 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, <code><a href="#cpop">cpop</a></code>
verifies that the current context has the expected name, pops it off
of the stack, and returns the accumulated text.<p>
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
<code><a href="#cpush">cpush</a></code>, the first macro can define one or more context
variables; the second macro can retrieve their values any time before
calling <code><a href="#cpop">cpop</a></code>. For example, suppose the document must
specify the footnote number explicitly:<p>
<pre> 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.
} </pre>
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
<code><a href="#cis">cis</a></code> or <code><a href="#cname">cname</a></code>.<p>
<h2><a name="tcl_commands">TCL COMMANDS</a></h2>
The package defines the following Tcl commands:<p>
<dl>
<dt> <code><a name="expander">expander <i>name</i></a></code>
<dd> This command creates a new expander object;
name is the name of the object, and becomes a new
command. By default, if the name isn't fully qualified, i.e.,
if it doesn't completely specify the namespace in which to
create the new command, the command is created in the caller's
current namespace.<p>
</dl>
<h2><a name="expander_object_commands">EXPANDER OBJECT COMMANDS</a></h2>
Every expander object will accept the following
subcommands:<p>
<dl>
<dt> <code><a name="cappend">cappend <i>text</i></a></code>
<dd> Appends a string to the output in the current context. This
command should rarely be used by macros or application code.<p>
<dt> <code><a name="cget">cget <i>varname</i></a></code>
<dd> Retrieves the value of variable <i>varname</i>, defined in the
current context.<p>
<dt> <code><a name="cis">cis <i>cname</i></a></code>
<dd> Determines whether or not the name of the current context
is <i>cname</i>.<p>
<dt> <code><a name="cname">cname</a></code>
<dd> Returns the name of the current context.<p>
<dt> <code><a name="cpop">cpop <i>cname</i></a></code>
<dd> Pops a context from the context stack, returning all accumulated
output in that context. The context must be named <i>cname</i>, or
an error results.<p>
<dt> <code><a name="cpush">cpush <i>cname</i></a></code>
<dd> Pushes a context named <i>cname</i> onto the context stack.
The context must be popped by <code><a href="#cpop">cpop</a></code> before expansion
ends or an error results.<p>
<dt> <code><a name="cset">cset <i>varname</i> <i>value</i></a></code>
<dd> Sets variable <i>varname</i> to <i>value</i> in the current context.<p>
<dt> <code><a name="cvar">cvar <i>varname</i></a></code>
<dd> Retrieves the internal variable name of context variable
<i>varname</i>; this allows the variable to be passed to
commands like <b>lappend</b>.<p>
<dt> <code><a name="errmode">errmode ?<i>newErrmode</i>?</a></code>
<dd> Sets the macro expansion error mode to one of "nothing",
"macro", "error", or "fail"; the default value is "fail". The
value determines what the expander does if an error is detected
during expansion of a macro.<p>
If the error mode is "fail", the error propagates normally and
can be caught or ignored by the application.<p>
If the error mode is "error", the macro expands into a detailed
error message, and expansion continues.<p>
If the error mode is "macro", the macro expands to itself; that
is, it is passed along to the output unchanged.<p>
If the error mode is "nothing", the macro expands to the empty
string, and is effectively ignored.<p>
<dt> <code><a name="evalcmd">evalcmd ?<i>newEvalCmd</i>?</a></code>
<dd> Returns the current evaluation command, which defaults to
"uplevel #0". If specified, <i>newEvalCmd</i> will be saved
for future use and then returned; it must be a Tcl
command expecting one additional argument: the macro to evaluate.<p>
<dt> <code><a name="expand">expand <i>inputString</i> ?<i>brackets</i>?</a></code>
<dd> Expands the input string, replacing embedded macros with their
expanded values, and returns the expanded string.<p>
If <i>brackets</i> is given, it must be a list of two strings;
the items will be used as the left and right macro expansion
bracket sequences for this expansion only.<p>
<dt> <code><a name="lb">lb ?<i>newbracket</i>?</a></code>
<dd> Returns the current value of the right macro expansion
bracket; this is for use as or within a macro, when the bracket
needs to be included in the output text. If <i>newbracket</i> is
specified, it becomes the new bracket, and is returned.<p>
<dt> <code><a name="rb">rb ?<i>newbracket</i>?</a></code>
<dd> Returns the current value of the right macro expansion
bracket; this is for use as or within a macro, when the bracket
needs to be included in the output text. If <i>newbracket</i> is
specified, it becomes the new bracket, and is returned.<p>
<dt> <code><a name="reset">reset</a></code>
<dd> Resets all expander settings to their initial values. Unusual
results are likely if this command is called from within a call
to <code><a href="#expand">expand</a></code>.<p>
<dt> <code><a name="setbrackets">setbrackets <i>lbrack</i> <i>rbrack</i></a></code>
<dd> Sets the left and right macro expansion brackets. This command
is for use as or within a macro, or to permanently change the
bracket definitions. By default, the brackets are "[" and
"]", but any non-empty string can be used; for example,
"<" and ">" or "(*" and "*)" or even "Hello," and "World!".<p>
<dt> <code><a name="textcmd">textcmd ?<i>newTextCmd</i>?]</a></code>
<dd> Returns the current command for processing polain text, which
defaults to the empty string, meaning <i>identity</i>. If
specified, <i>newTextCmd</i> will be saved for future use and
then returned; it must be a Tcl command expecting one
additional argument: the text to process. The expander object
will this command for all plain text it encounters, giving the
user of the object the ability to process all plain text in
some standard way before writing it to the output. The object
expects that the command returns the processed plain text.<p>
<b>Note</b> that the combination of <i>textcmd plaintext</i> is
run through the <i>evalcmd</i> for the actual evaluation. In
other words, the <i>textcmd</i> is treated as a special macro
implicitly surrounding all plain text in the template.<p>
</dl>
<h2><a name="history">HISTORY</a></h2>
expander was written by William H. Duquette; it is a repackaging of
the central algorithm of the
<a href="http://www.wjduquette.com/expand">expand</a> macro processing tool.<p>
<p><hr><p>
Copyright © 2001, by William H. Duquette. All rights reserved.<p>
</body>
</html>
|
