Section Intro: Alists

THE META-HTML LANGUAGE REFERENCE MANUAL

Server Variables

[TOC]

Moddate Module

Section Intro: Alists

Alists

Synopsis:

Meta-HTML provides a textual way to manipulate complex data structures which would (in normal use) be stored in packages.

The textual representation of a package is called an alist, which is short for association list, and which is a construct well known to Lisp and Scheme programmers.

An alist consists of name and value pairs, surrounded by parentheses, with the entire set of name and value pairs also parenthesized.

Functions exist to create alists from scratch, to modify the variable settings within an alist, to create an alist from the contents of a package, and to populate a package with the contents of an alist.

Commands:

alist-defvar
alist-get-var
alist-merge
alist-package-delete
alist-package-names

alist-package-vars
alist-set-var
alist-to-package
alist-unset-var

alist-var-exists
alist?
make-alist
package-to-alist

More Information:

Association lists are an efficient and extensible way to hold on to complex data structure across invocations of Meta-HTML, akin to printing out and reading back in complex C structure. Fortunately, you don't have to do the parsing of the association list yourself, since Meta-HTML provides that functionality for you.

<alist-defvar ALISTVAR NAME VALUE Simple

DEFault the value of the VARiable named by NAME to VALUE, in the association list referenced by ALISTVAR.

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

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

Return the value of the NAMEs given from the association list specified by ALISTVAR. Each NAME is a variable name which has had a value assigned to it with alist-set-var, or was created implicity via alist-to-package.

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

<alist-merge &rest alist-vars &key strip append> Simple

Merge the alists stored in the passed variable names into a single alist, and return that new alist.

By default, each ALIST-VAR encountered overrides values set in previous alists that were encountered -- the values do not "pile up" -- they instead replace each other.

Passing the keyword argument APPEND=TRUE changes this behavior; in this case values seen in subsequent alists are appended to the values in previous alists, creating array variables in the output.

<set-var a1=<make-alist foo=foo1 bar=bar1>
         a2=<make-alist foo=foo2 newvar=newval>>
<alist-merge a1 a2>
<alist-merge a1 a2 append=true>

(("BAR" . "bar1")("FOO" . "foo2")("NEWVAR" . "newval"))
(("BAR" . "bar1")("FOO" "foo1" "foo2")("NEWVAR" . "newval"))

<alist-package-delete ALISTVAR &rest packages[]> Simple

For each variable in the association list within ALISTVAR, remove the variable from the association list if it is prefixed with one of the specifed package names. For example, given that the variable ALIST contained the alist:

(("FOO::BAR" . "bar") ("FOO::BAZ" . "baz") ("BAR::X" . "val"))

then calling:

<alist-package-delete alist foo>
<get-var-once alist>

produces:

(("BAR::X" . "val"))

<alist-package-names ALISTVAR Simple

Return a newline separated list of all of the packages which are defined within the association list stored within ALISTVAR. Because the list is newline separated, the result can easily be assigned to an array variable:

<alist-package-vars ALISTVAR &key [STRIP=TRUE] Simple

Returns a newline separated list of the fully qualified variable names found in the alist named by ALISTVAR

When STRIP=TRUE is supplied, the returned variable names have the package prefix stripped off, making them not fully qualified. The names are not returned in any significant order. Because the list is newline separated, the results can easily be assigned to an array variable:

<set-var alist=<make-alist this::foo=bar this::bar=baz>>
<set-var names[]=<alist-package-vars alist>>
<get-var-once names[1]> is <alist-get-var alist <get-var-once names[1]>>

THIS::FOO is bar

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

Gives the variable NAME the value of VALUE in the association list specified by ALISTVAR. Any number of name/value pairs may be given, and whitespace is not significant. Where =VALUE is omitted, the value is the empty string.

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

<alist-to-package ALIST &optional [PACKAGE] Simple

Takes the textual list representation of a package, and creates (or modifies) the package named by PACKAGE-NAME.

alist-to-package is the inverse of the package-to-alist function -- given an "alist" (short for `association list') you can create a package, and vice-versa. The following expression is one way to copy all of the variables from the package FOO into the package BAR:

<alist-to-package <package-to-alist foo> bar>

But don't use that, of course. Use copy-package instead.

<alist-unset-var ALISTVAR &rest names...> Simple

Make NAMEs be non-existent in the association list specified by ALISTVAR.

<alist-var-exists ALISTVAR NAME Simple

var-exists checks for the existence of the variable named by VARNAME, in the association list specified by ALISTVAR, and returns true if that variable does in fact exist.

The existence of a variable has nothing to do with its value -- a variable exists if it is present within the list, whether or not it has a value.

<alist? STRING Simple

Return "t" if STRING is a representation of an association list.

<make-alist &rest name-value-pairs> Simple

Return an alist from the NAME-VALUE pairs passed.

 <make-alist foo=bar baz=this>

(("BAZ" . "this")("FOO" . "bar"))

<package-to-alist &optional [PACKAGE] &key [STRIP] Simple

Returns a Lisp readable string containing the names and values of the variables in PACKAGE. If STRIP=TRUE is supplied, the package name is removed from the variables before placing them in the list. See the following code sequence:

<set-var
  foo::bar=baz
  foo::array[0]=Elt-0
  foo::array[1]=Elt-1>
<p>
  The contents of Foo: <package-to-alist foo>
The stripped contents: <package-to-alist foo strip=true>


  The contents of Foo: (("FOO::BAR" . "baz")("FOO::ARRAY" "Elt-0" "Elt-1"))
The stripped contents: (("BAR" . "baz")("ARRAY" "Elt-0" "Elt-1"))

Edit Section
Function Index
Variable Index