Section Intro: Packages

THE META-HTML LANGUAGE REFERENCE MANUAL

Arrays

[TOC]

Flow Control

Section Intro: Packages

Packages

Synopsis:

Packages are repositories which contain symbols and their values.

Each time a symbol is referenced, a package must first be found, and then the symbol may be found within that package. You indicate which package to look the symbol up in by supplying a package prefix. When the prefix is not supplied, the symbol is looked up in the current package.

Commands:

copy-package
in-package
make-innocuous

package-delete
package-diff
package-eq

package-names
package-vars
with-local-package

More Information:

For example, a full reference to the symbol BAR stored in the FOO package looks like:

   FOO::BAR

There are very few commands specifically for dealing with packages, because most of the operations are performed implicitly, rather than explicitly. To create a package, simply give the package name as part of the symbol, in the place where the symbol is normally used.

   <set-var foo::bar = "Hello">

This has the effect of creating the package FOO if it didn't already exist.

The majority of the functions documented here perform package maintenance, as opposed to variable manipulation. There are functions for querying a package about its contens, for deleting an entire package, for exporting and importing packages to and from sessions, for copying the contents of packages, and for converting packages from an internal representation to a printable representation, called an alist.

<copy-package SRC DEST Simple

Copy the contents of the package SRC to the package DEST.

<in-package PACKAGE-NAME body </in-package> Complex

Evaluate BODY in an environment where variables which are not specifically prefixed with a package name are looked up and stored within PACKAGE-NAME.

The special package name "local" creates an anonymous package within which to work. The contents of local packages are only accessible within the expressions surrounded by the in-package operator.

<make-innocuous &rest packages[]> Simple

Causes each variable in the specified PACKAGES to have non-interpretable text. This is done by substituting HTML constructs for angle braces, among other things.

<package-delete &rest package-names...> Simple

Remove the definition of the packages named by PACKAGE-NAMES, and all of the variables defined within them.

<package-diff PACKAGE-1 PACKAGE-2 &key [VERBOSE] Simple

Returns an alist describing the differences between PACKAGE-1 and PACKAGE-2.

The returned alist contains three elements -- the key DIFFERS is an array of the variable names that existed in both packages, but did not have identical values; the key ONLY-IN-XXX is an array of the variable names which were found in the XXX package (where XXX is one of either the value of PACKAGE-1 or the value of PACKAGE-2.

If the keyword argument VERBOSE=TRUE is supplied, then additional information appears in the value of the DIFFERS key -- this information is not generally easily parseable by a program, but supplies a great deal of information while debugging.

 <set-var pack1::foo=bar pack1::bar=bingo>
 <set-var pack2::foo=bar pack2::bar=bingo pack2::baz=baz>
 PACKAGE-DIFF: (normal)  <package-diff pack1 pack2>
 PACKAGE-DIFF: (verbose) <package-diff pack1 pack2 verbose=true>

PACKAGE-DIFF: (normal)  (("DIFFERS")("ONLY-IN-PACK1")("ONLY-IN-PACK2" . "BAZ"))
 PACKAGE-DIFF: (verbose) (("DIFFERS")("ONLY-IN-PACK1")("ONLY-IN-PACK2" . "BAZ"))

<package-eq PACKAGE-1 PACKAGE-2 &key [STRICT] Simple

Returns "true" if every variable in PACKAGE-1 has a matching variable and identical value in PACKAGE-2.

Without the keyword argument STRICT=TRUE, PACKAGE-2 is allowed to contain variables that PACKAGE-1 doesn't -- such variables are simply ignored, as <package-eq> executes in PACKAGE-1-centric mode.

With keyword argument STRICT=TRUE, PACKAGE-1 and PACKAGE-2 must be exactly similar; the same number of variables, and each one with the same name.

 <set-var pack1::foo=bar pack1::bar=bingo>
 <set-var pack2::foo=bar pack2::bar=bingo pack2::baz=baz>
 PACKAGE-EQ: <package-eq pack1 pack2>
 PACKAGE-EQ: (strict) <package-eq pack1 pack2 strict=true>

PACKAGE-EQ: true
 PACKAGE-EQ: (strict)

<package-names Simple

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

<set-var all-packages[]=<package-names>>

<package-vars &optional [PACKAGE-NAME] &key [STRIP=TRUE] Simple

Returns a newline separated list of the fully qualified variable names found in the package named by PACKAGE-NAME, or in the current package if PACKAGE-NAME is not given. 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 foo::bar=baz>
<set-var foo::baz=bar>
<set-var names[]=<package-vars foo>>
<get-var names[1]>

FOO::BAZ

<with-local-package body </with-local-package> Complex

Shorthand for <in-package local> <i>body</i> </in-package>

Edit Section
Function Index
Variable Index