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