| THE META-HTML LANGUAGE REFERENCE MANUAL

Relational Operators | [TOC] | Arrays

## Section Intro: Variables

Synopsis:

Meta-HTML provides a simple mechanism for the storage and retrieval of variables during a single (possibly recursive) processing pass. In addition to this, functions are provided which test the value of a variable, and conditionally execute other code based upon the result.

There is also a mechanism to group a set of variables using Packages.

Commands:

cgi-decode cgi-encode coerce-var copy-var | decrypt defvar encrypt | get-var get-var-once set-var | subst-in-var unset-var var-exists

Variables:

env::exec-path mhtml::cookie-compatible | mhtml::default-filenames mhtml::document-root | mhtml::remote-ident | mhtml::remote-user

More Information:

### Variable Types and Information

There are internal functions in Meta-HTML which create binary variables. Such variables cannot be used in the ordinary way, since the data contained within them may not retain integrity once printed out and read back in. You can check to see what the type of a particular variable is with the `symbol-info` function.

Many variables are predefined by Meta-HTML, and made available to the page writer. The Page Variables section of this manual documents those variables fully, while the Server Variables section contains more information on variables which control, or were specifically created by, the web server.

### Function Documentation

`<cgi-decode STRING [PACKAGE]>` | Simple

Decode STRING into PACKAGE.

If PACKAGE is not specified the current package is used.

STRING is a string that might have appeared in `QUERY_STRING` or the contents of the data that was posted to a document, such that it consists of name value pairs:

    FOO=bar&STRING=this+is+a+string%2C+other+chars

PACKAGE is the name of a package to bind the variables in. So, given the above example as the text in a variable called STRING, here is what you get:

    <set-var string="FOO=bar&STRING=a+string%2C+other+chars">
    <cgi-decode <get-var string> mypack>
    <get-var mypack::string>

produces:

    a string, other chars

Also see `cgi-encode`.

`<cgi-encode VAR1 [VAR2...] [PRESERVE-CASE=TRUE]>` | Simple

A CGI readable string is created from the names of VAR1 ... VARN and the associated values of those variables. For example, if the variable `FOO-VAR` has the value `"Foo & Value"`, then the invocation

    <cgi-encode FOO-VAR>

produces:

    FOO-VAR=Foo+%26+Value

Given the optional keyword argument of PRESERVE-CASE=TRUE, `cgi-encode` encodes the variables preserving the case of them as they were input.

Thus,

    <cgi-encode Foo-Var preserve-case=true>

produces:

    Foo-Var=Foo+%26+Value

`<coerce-var VARNAME [TYPE=(STRING|BINARY)]>` | Simple

Coerces VARNAME's data to have the type specified by the argument to TYPE. You can convert a binary object to a string object, and vice-versa.

A binary variable might be created as the result of a call to `stream-get-contents`, for example. Once the data is read, you might wish to perform some substitutions on it, or otherwise get its value. To do so, you call `coerce-var` on the value:

       <with-open-stream s /tmp/file mode=read>
         <stream-get-contents s foo>
       </with-open-stream>
       <coerce-var foo type=string>
       <subst-in-string <get-var foo> "Hello" "Goodbye">
       <get-var foo>

`<copy-var FROM-VAR [TO-VAR...]>` | Simple

Copies the variable FROM-VAR to each of the named TO-VARs.

Each TO-VAR becomes the repository of a copy of the information already stored under FROM-VAR. This is a true copy; not an alias to the original variable.

       <set-var foo=bar>
       <get-var foo>      --> bar
       <get-var new>      -->
       <copy-var foo new> -->
       <get-var new>      --> bar
       <copy-var *meta-html*::get-var *meta-html*::foo>
       <foo new>          --> bar

`<decrypt VARNAME PASSWORD>` | Simple

Decrypts the contents of the previously encrypted variable named by VARNAME using PASSWORD.

The contents of VARNAME are modified -- this function has no return value.

This function only does something if Meta-HTML has been configured with the `--with-des` option, currently only available to those sites which are physically located within the United States.

Also see `encrypt`.

`<defvar NAME VALUE>` | Simple

DEFault the value of the VARiable named by NAME to VALUE.

`defvar` assigns VALUE to NAME if, and only if, NAME has a non-empty value.

`defvar` could have been defined in Meta-HTML using `define-tag`:

    <define-tag defvar>
      <if <not <get-var %0>> <set-var %0=%1>>
    </define-tag>

`<encrypt VARNAME PASSWORD>` | Simple

Encrypts the contents of the variable named by VARNAME using PASSWORD.

The contents of VARNAME are modified -- this function has no return value.

This function only does something if Meta-HTML has been configured with the `--with-des` option, currently only available to those sites which are physically located within the United States.

Also see `decrypt`.

`<get-var [NAME...]>` | Simple

Returns (as a text string) the current value of the variables named by the NAMEs given.

`<get-var-once [NAME...]>` | Simple

Returns the current value of the variables named by the NAMEs given. The interpreter pointer is then moved to after the returned data, thus preventing further interpretation of the data.

`<set-var [NAME=VALUE...]>` | Simple

Gives the variable NAME the value of VALUE for the current processing run. Any number of name/value pairs may be given, and whitespace is not significant. Where =VALUE is omitted, the value is the empty string.

`<subst-in-var VARNAME [THIS] [WITH-THAT] ...>` | Simple

Replaces all occurrences of THIS with WITH-THAT in the contents of the variable named VARNAME. Both THIS and WITH-THAT are evaluated before the replacement is done. THIS can be any regular expression allowed by the POSIX extended regular expression matching. This command can be useful when parsing the output of `cgi-exec`.

`<unset-var [NAME...]>` | Simple

Make NAMEs be non-existent in the page environment.

`<var-exists VARNAME>` | Simple

`var-exists` checks for the existence of the variable named by VARNAME, and returns `true` if that variable exists.

The existence of a variable has nothing to do with its value -- a variable exists if it has been created with `set-var`, and doesn't exist after it has been unset with `unset-var`.

      <set-var foo=1 bar>
      <var-exists foo>       --> true
      <var-exists bar>       --> true
      <get-var bar>          -->
      <unset-var foo>
      <var-exists foo>       -->

Edit Section
Function Index
Variable Index

The META-HTML Reference Manual V1.4 Copyright © 1995, 1996, Brian J. Fox, 1996, 1997 Universal Access Inc.
Found a bug? Send mail to bug-manual@metahtml.com