Wapp: Inserting Generated Text Into A Document

The wapp-subst and wapp-trim commands accept various substitution functions so that generated content can be inserted into the webpage safely. "Safely" in this context means that characters having special meaning to HTML or Javascript are escaped.

%html(...)	Excape text for inclusion in HTML
%url(...)	Excape text for use as a URL
%qp(...)	Excape text for use as a URL query parameter
%string(...)	Excape text for use within a JSON string
%unsafe(...)	No transformations of the text

The arguments to these substitution functions can be any valid TCL expression. Except, the substitutions are recognized using a regular expression which terminates at the first ")" it sees in the argument. That means that the argument cannot use TCL expressions that include a ")" character. To work around that limitation, the following variants are also supported:

%html%(...)%

%url%(...)%

%qp%(...)%

%string%(...)%

%unsafe%(...)%

In other words, the "(...)" argument is replaced with "%(...)%" - parentheses surrounded by "%" characters. In these cases, the regular expression terminates at the first ")%" that it sees, rather than the first ")". The ")%" character sequence is is less likely to appear as TCL in the argument and hence these routines provide added flexibility for complex TCL expressions.

Examples

Consider this simple Wapp program:

package require wapp
proc wapp-default {} {
  set var1 {Hello <y'all>}
  wapp-subst {<p>%html($var1)</p>}
}
wapp-start $argv

The "var1" variable contains text that cannot be inserted directly into HTML due to the < and > characters. But the %html() substitution escapes these characters so that the generated HTML looks like this:

<p>Hello &lt;y'all&gt;</p>

Here is an example of a more complex TCL expression used in the argument:

package require wapp
proc wapp-default {} {
  set a 123
  set b 345
  set c 678
  wapp-subst {<p>expr = %html%([expr {($a+$b)*$c}])%</p>}
}
wapp-start $argv

In this case the argument contains a ")" character and so it is necessary to use the %html%(...)% form of the substitution to prevent the regular expression stopping at the first ")" and thus truncating the TCL expression as just "[expr {($a+$b1".