Wapp

Check-in [568d7c208d]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More details in the explanation of how %-subsitutions work.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 568d7c208d3bba291bafb72e574c9009023edbd3edadc82c2a0cab70a854e9ae
User & Date: drh 2019-07-30 17:47:47.200
Context
2019-07-30
23:12
Serialize the evaluation of the wappInt-handle-request proc. Fix for ticket [207094dd9de1343a] (check-in: 80f25418a1 user: drh tags: trunk)
17:47
More details in the explanation of how %-subsitutions work. (check-in: 568d7c208d user: drh tags: trunk)
15:35
Documentation updates. No changes to code. (check-in: c366208c59 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to docs/commands.md.
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
     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
     outside of the quoted regions. This problem is fixed using the new
     "-command" option to the regsub command in Tcl 8.7.  Nevertheless, 
     it is suggested that you avoid using the "[" character outside of
     the %-quotes.  Use "\&#91;" instead.

> >  <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







|
|



















|
|







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
     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
     outside of the quoted regions. This problem is fixed using the new
     "-command" option to the regsub command in Tcl 8.7.  Nevertheless, 
     it is suggested that you avoid using the "[" character outside of
     the %-quotes.  Use "\&#91;" instead.

> >  <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
Added docs/subst.md.






























































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
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`".