Section Intro: Variables

THE META-HTML LANGUAGE REFERENCE MANUAL

[TOC]

Section Intro: Variables

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:

binary-concat
cgi-decode
cgi-encode
coerce-var
content-length
contents-to-hex
copy-var

decrement
defvar
get-var
get-var-eval
get-var-once
hex-to-contents
increment

set-var
set-var-readonly
set-var-verbatim
symbol-info
unset-var
var-exists

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.

<binary-concat COLLECTOR &rest binary-vars> Simple

Concatenate the contents of COLLECTOR and the supplied BINARY-VARs into a single binary variable, and store the results back in COLLECTOR.

<cgi-decode STRING &optional [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=this+is+a+string%2C+other+chars">
<cgi-decode <get-var string> mypack>
<get-var mypack::string>

this is a string, other chars

Also see cgi-encode.

<cgi-encode &rest vars &key preserve-case=true strip=true> Simple

A CGI readable string is created from the names of the VARs given, and the associated values of those variables. For example, if the variable FOO-VAR has the value "Foo & Value", then the invocation 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.

Foo-Var=Foo+%26+Value

Finally, the keyword flag STRIP=TRUE, when present, says to strip off the package name of each variable before placing it in an assignment statement (also see package-vars).

<set-var FOO::BAR=value>
<cgi-encode Foo::Bar preserve-case=true strip=true>

Bar=value

<coerce-var VARNAME &key [TYPE=(STRING|BINARY|ARRAY)] 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>
<p>
<coerce-var foo type=string>
<subst-in-string <get-var-once foo> "Hello" "Goodbye">

<content-length VARNAME Simple

Return the length of the contents of VAR. If VAR is an array or string, returns the number of elements in the array. If VAR is a binary variable, returns the amount of data stored within. If VAR is a function, returns the empty string.

 <dir::read-file /etc/passwd myvar> ==> true
 <content-length myvar>             ==> 864

<contents-to-hex VARNAME Simple

Convert the contents of the binary variable named by VARNAME to be a sequence of hex characters.

<copy-var FROM-VAR &optional [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
<p>
<copy-var *meta-html*::get-var *meta-html*::foo>
<foo new>          ==> bar

<decrement NAME &key [BY=AMOUNT] Simple

Subtract AMOUNT (default 1) from the contents of the variable named by VARNAME.

   <set-var foo=1>
   <get-var foo> ==> 1
   <decrement foo>
   <get-var foo> ==> 0

Also see increment.

<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 empty value.

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

<define-tag defvar var &optional val>
  <if <not <get-var <get-var-once var>>>
      <set-var <get-var-once var>=<get-var-once val>>>
</define-tag>

<get-var &optional [NAME] [...] Simple

Synonym for <get-var-eval>

<get-var-eval &optional [NAME...] Simple

Return the value of the NAMEs given. Each NAME is a variable name which has had a value assigned to it with set-var, set-var-readonly, or was created implicity via alist-to-package or coerce-var.

The values are returned in the order in which the NAMEs appear.

Examples:

<set-var foo=Var-1 bar=Var-2>
<get-var-eval foo>, <get-var bar>

Var-1, Var-2

When multiple NAMEs are given:

<set-var foo=Var-1 bar=Var-2>
<get-var foo bar foo>

Var-1Var-2Var-1

<get-var-once &optional [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.

Example:

<set-var bar=HELLO>
<set-var-verbatim foo=<get-var bar>>
<get-var-once foo>   ==> &lt;get-var bar&gt;

<get-var foo>        ==> HELLO

<hex-to-contents STRING VARNAME Simple

Convert the string of hexadecimal digits passed in STRING to their binary contents, placing the result in VARNAME.

<increment NAME &key [BY=AMOUNT] Simple

Add AMOUNT (default 1) to the contents of the variable named by VARNAME.

<set-var foo=1>
<get-var foo> ==> 1
<increment foo>
<get-var foo> ==> 2

Also see decrement.

<set-var &optional [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.

<set-var foo=bar bar=baz>
<get-var foo>              ==> bar
<get-var bar>              ==> baz
<get-var <get-var foo>>    ==> baz

<set-var-readonly &optional [NAME=VALUE...] Simple

For each NAME specified, if that name is not already assigned a value with set-var-readonly, assigns the associated VALUE to it, exactly in the way that set-var would.

Once NAME has had a value assigned to it with set-var-readonly, then that variable is immutable, i.e., its value cannot be changed using any Meta-HTML commands.

A useful construct for setting various site specific variables in your engine.conf or mhttpd.conf file, this allows one to create globally defined variables which cannot be changed by the execution of Meta-HTML statements in a page.

Variables which can usefully benefit from this type of setting include mhtml::include-prefix and mhtml::relative-prefix among others.

<set-var-verbatim &optional [NAME=VALUE...] Simple

Gives the variable NAME the value of VALUE for the current processing run. The difference between set-var-verbatim and set-var is that in set-var-verbatim the right-hand side of assignments are not evaluated.

Example:

<set-var-verbatim foo=<get-var bar>>
<get-var-once foo>

<symbol-info SYMBOL Simple

Returns information about the symbol SYMBOL.

The information is returned in an alist containing:

The type of the symbol (TYPE), which is one of:
1. STRING,
2. BINARY,
3. USER DEFUN,
4. USER SUBST,
5. USER MACRO,
6. PRIM DEFUN, or
7. PRIM MACRO.
The "size" of the symbol.
The symbol's flags, including:
1. READONLY
2. INVISIBLE
3. NOEXPAND
4. MODIFIED
5. MACH_RES
6. FLAGGED

For STRING. variables, the size value is the number of elements in the array.
For BINARY variables, the size value is the number of bytes of binary data stored within.

The size value is zero for all other variable types.

<unset-var &optional [NAME...] Simple

Make NAMEs be non-existent in the page environment.

This is different than <set-var foo=""> because the variable actually ceases to exist, rather than is given no value.

Example:

<set-var foo="">
<var-exists foo>      ==> true
<get-var foo>         ==>
<unset-var foo>
<var-exists foo>      ==>

<var-exists NAME 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