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: |
568d7c208d3bba291bafb72e574c9009 |
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
Changes to docs/commands.md.
︙ | ︙ | |||
29 30 31 32 33 34 35 | 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 | | | | | | 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 "\[" 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 < and > characters. But the %html() substitution escapes these characters so that the generated HTML looks like this: > <p>Hello <y'all></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`". |