New TCL Commands

%if - Conditionally include HTML text.

Syntax: %if CONDITION HTML ...

There are really three commands with similar operation: %if, %ifdef and %ifndef. Each of these commands is designed to conditionally include some HTML text within dynamically generated content. The operation of %if is similar to the standard if command of TCL except that the body is returned as HTML (after being processed by hsubst) instead of being executed as a script.

The easiest way to describe the operation of these statements is by example. You can put the following kinds of text in an dynamic content file:

     <%%if {$value>10} {
         <p>The value <$value> is greater than 10!</p>
     } %else {
         <p>The value <$value> is less than 10!</p>
     }%>
 

The example above includes different text in the middle of the dynamically generated HTML depending on whether TCL variable $value is less than 10.

Notice that the keyword %else (with a percent sign in front) is used in place of the else keyword (without a percent sign.) You can also use %elseif, %elseifdef, and/or %elseifndef.

The %ifdef and %ifndef variants of this command use as their conditional a list of indices to the Q array variable. %ifdef is successful if all indices named exist in Q and %ifndef is successful if none of the named indices are present in Q. Thus, for example, the phrase

 <%%ifdef {a b} {Hello, World!}%>
 

is equivalent to

 <%%if {[info exists Q(a)] && [info exists Q(b)]} {Hello, World!}%>
 

The %elseifdef and %elseifndef keywords are similar extensions of %elseif.

debug - Add debugging output to the beginning of the returned HTML

Syntax: debug TEXT

This command is useful for debugging embedded scripts. The argument is HTML text which will be prepended to the HTML that the web server generates and returns.

A common use for this command is to put short message in embedded scripts to trace the generation of dynamic content. Or it can be used to dump the values of variables. For example, to view all the content of the D array variable, add this code anywhere in a dynamically generated document:

 <% ::tws::debug [::tws::parray D] %>
 

decode64 - Decode the input text from base-64 back to binary

Syntax: decode64 TEXT

This command treats its input as a base-64 string and returns the decoded value of that string. Characters of input that are not valid base-64 characters (such as spaces and newlines) are ignored.

dehttpize - Remove the special HTTP encodings on a URL or query string.

Syntax: dehttpize TEXT

This command removes the URL encodings from its input string and returns the result. URL encodings are the special codes used to escape syntactic within a URL or query string. For example, this command converts "+" into a space and "%2F" into a single "/" character.

encode64 - Encode the input text using base-64

Syntax: encode64 TEXT

This command converts the text of its input into a base-64 encoding. The encoding can be reversed using the decode64 command.

hsubst - Process TCL script embedded in HTML

Syntax: hsubst HTML

The sole argument to this command is HTML text that may contain embedded TCL script. The return value is the same as its input except that the embedded TCL script has been evaluated and evaluation result substituted in place of the embedded script.

In the input HTML, TCL script is contained within "<%...%>". Whenever such a script is encountered, the enclosing "<%" and "%>" markup is removed, the script is evaluated, and the result of the script is substituted in place of the entire "<%...%>" string. If the TCL script returns an error, then this command returns the same error. If the TCL script terminates with a break or continue command, then the result is substituted as it normally would be, but all text after the closing "%>" is discarded.

TCL variables may be substituted by enclosing them in "<$...>". The value of the variable replaces the entire <$...> string. If the named variable does not exist, no error is generated. A non-existant variable is treated like an empty string.

The hsubst may be nested. That is to say, the TCL script contained within some <%...%> markup of an hsubst command may contain nested calls to hsubst.

The TWS server uses the hsubst command to process all dynamic content. When the dispatcher determines that the content for a particular URL is dynamic, it reads the matching file into memory, passes the file's content as the argument to hsubst and returns the result to the web browser.

htmlize - Encode characters that have special meaning to HTML

Syntax: htmlize TEXT

This command encodes special characters in an arbitrary piece of input text according to the rules of HTML. The "<" character is converted to "&lt;", the "&" character is converted to "&amp;" and the ">" character is converted to "&gt;". (The last change is not strictly necessary but is done for symmetry.) In addition, the double-quote character is coded as "&quot;" so that result can be used as an argument to markup if desired.

httpize - Escape characters that have special meaning within URLs

Syntax: httpize TEXT

This command escapes special characters in an arbitrary piece of input text according to the rules of HTTP. Spaces are converted to "+" and other special characters are converted into a three-letter code consisting of a "%" followed by two hex digits that define the ASCII value of the character. The resulting string is safe to use as part of a URL.

ifanydef - Check to see if any named query parameter exists

Syntax: ifanydef LIST

This command returns non-zero (TRUE) if any one of the arguments are query parameters. The test looks at the Q array variable in the calling procedure.

For example, the command

 if {[ifanydef {a b c}]} break
 

is equivalent to

 if {[info exists Q(a)] || [info exists Q(b)] || [info exists Q(c)]} break
 

This command returns TRUE if one or more query parameters exists. Compare this to the ifdef command which returns TRUE if all named query parameters exist.

ifdef - Check to see if query parameters exist

Syntax: ifdef LIST

This command returns non-zero (TRUE) if all of the arguments are query parameters. The test looks at the Q array variable in the calling procedure.

For example, the command

 if {[ifdef {a b c}]} break
 

is equivalent to

 if {[info exists Q(a)] && [info exists Q(b)] && [info exists Q(c)]} break
 

This command returns TRUE if all named query parameters exists. Compare this to the ifanydef command which returns TRUE if one or more of the named query parameters exist.

include - Include the text of another file in the middle of an HTML document.

Syntax: include FILENAME

This routine reads all the text form a file, does an hsubst on that text, then returns the results. This is useful for including the body of one file inside of another.

parray - List the content of an array variable

Syntax: parray VARIABLE

This command is similar to the parray command that is built into TCL. The difference is that built-in version of parray writes the results to standard output whereas this version returns the result.

This command is intended to be used for debugging, such as in the following:

 <% ::tws::debug [::tws::parray D] %>
 

redirect - Cause the requesting web browser to jump to a different URL

Syntax: redirect URL

This command, when executed by an embedded TCL script of a dynamic content file, causes the generation of dynamic content to stop immediately. The web server then sends the requesting web browser a message telling it to try again at a different URL specified in the argument.

The URL argument may be either absolute or relative. If it is relative, the URL of the file that executed the redirect command is take as the base.

render - Add text to the first enclosing hsubst command.

Syntax: render TEXT

This command is intended for use by TCL script contained with <%...%> markup of the hsubst command. The argument to render is text that will be inserted in the output of the hsubst just before the "<%" that started the TCL script.

If there are multiple hsubst commands active when the render command is invoked, then the text is inserted into the inner most hsubst. If render is invoked outside of any hsubst then it does nothing.

Consider the following example hsubst command:

hsubst {one <% render "two"; return "three" %> four}

The result of the previous command is:

one twothree four

The "one" and "four" at the beginning and end of the result come directly from the input string. The "two" comes from the render command and the "three" is the return value of the embedded TCL script.

require - Source the named TCL script if it has not been sourced already

Syntax: require FILENAME

This command is available for use by embedded TCL scripts of dynamic content files. The purpose of this command is to make sure that a file of TCL code has been sourced and that all the procedures and variables defined by that file are available to the embedded TCL script.

The name of the TCL file to be sourced is given as an argument. The name may be either an absolute or a relative pathname. If it is a relative pathname, then the name is relative to the directory that contains the original dynamic content file.

The named file is sourced only once, the first time that the require command is executed. On subsequent executions, the require command is essentially a no-op.