Wapp

     after setting up all necessary file events.

  +  <a name='wapp-subst'></a>**wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent 
     accidental substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  Command and variable substitutions occur within
     "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and
     "%unsafe(...)".  The substitutions are escaped (except in the case of
     "%unsafe(...)") so that the result is safe for inclusion within the
     body of an HTML document, a URL, a query parameter, or a javascript or
     JSON string literal, respectively. 

> >  <b>Caution #1:</b> When using Tcl 8.6 or
     earlier, command substitution, but not variable substitution, occurs
................................................................................
> >  <b>Caution #2:</b> The %html() and similar %-substitutions are parsed
     using a regexp, which means that they cannot do matching parentheses.
     The %-substitution is terminated by the first close parenthesis, not the
     first matching close-parenthesis.

  +  <a name='wapp-trim'></a>**wapp-trim** _TEXT_  
     Just like wapp-subst, this routine appends _TEXT_ to the web page
     under construction, using the %html, %url, %qp, %string, and %unsafe
     substitutions.  The difference is that this routine also removes
     surplus whitespace from the left margin, so that if the _TEXT_
     argument is indented in the source script, it will appear at the
     left margin in the generated output.

  +  <a name='wapp-param'></a>**wapp-param** _NAME_ _DEFAULT_  
     Return the value of the [Wapp parameter](params.md) _NAME_,
     or return _DEFAULT_ if there is no such query parameter or environment

     after setting up all necessary file events.

  +  <a name='wapp-subst'></a>**wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent 
     accidental substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  [Command and variable substitutions](./subst.md) occur
     within "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and
     "%unsafe(...)".  The substitutions are escaped (except in the case of
     "%unsafe(...)") so that the result is safe for inclusion within the
     body of an HTML document, a URL, a query parameter, or a javascript or
     JSON string literal, respectively. 

> >  <b>Caution #1:</b> When using Tcl 8.6 or
     earlier, command substitution, but not variable substitution, occurs
................................................................................
> >  <b>Caution #2:</b> The %html() and similar %-substitutions are parsed
     using a regexp, which means that they cannot do matching parentheses.
     The %-substitution is terminated by the first close parenthesis, not the
     first matching close-parenthesis.

  +  <a name='wapp-trim'></a>**wapp-trim** _TEXT_  
     Just like wapp-subst, this routine appends _TEXT_ to the web page
     under construction. The same [substitution functions](./subst.md)
     are supported.  The difference is that this routine also removes
     surplus whitespace from the left margin, so that if the _TEXT_
     argument is indented in the source script, it will appear at the
     left margin in the generated output.

  +  <a name='wapp-param'></a>**wapp-param** _NAME_ _DEFAULT_  
     Return the value of the [Wapp parameter](params.md) _NAME_,
     or return _DEFAULT_ if there is no such query parameter or environment

Inserting Generated Text Into A Document
========================================

The [wapp-subst](./commands.md#wapp-subst) and 
[wapp-trim](./commands.md#wapp-trim) commands accept various substitution
functions so that generated content can be inserted into the webpage
<i>safely</i>. "Safely" in this context means that characters
having special meaning to HTML or Javascript are escaped.

<center>
<table border="0">
<tr>
<td style='padding-right:5ex;' valign='top'>%html(...)</td>
<td>Excape text for inclusion in HTML</td>
</tr>
<tr>
<td style='padding-right:5ex;' valign='top'>%url(...)</td>
<td>Excape text for use as a URL</td>
</tr>
<tr>
<td style='padding-right:5ex;' valign='top'>%qp(...)</td>
<td>Excape text for use as a URL query parameter</td>
</tr>
<tr>
<td style='padding-right:5ex;' valign='top'>%string(...)</td>
<td>Excape text for use within a JSON string</td>
</tr>
<tr>
<td style='padding-right:5ex;' valign='top'>%unsafe(...)</td>
<td>No transformations of the text</td>
</tr>
</table>
</center>

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:

<center>
<table border="0">
<tr><td>%html%(...)%</td></tr>
<tr><td>%url%(...)%</td></tr>
<tr><td>%qp%(...)%</td></tr>
<tr><td>%string%(...)%</td></tr>
<tr><td>%unsafe%(...)%</td></tr>
</table>
</center>

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 &lt; and &gt; 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`".