;;; sec6.00.mhtml: -*- Meta-HTML -*- 

;;;  Copyright (c) 1996 Universal Access Inc.
;;;  Author: Henry Minsky (hqm@ua.com) Sun Sep 15 11:05:59 1996.
<set-var title="The Package System">
<include header.mhtml>

<plain-text>
  <pagelist-control-panel>
  <h2>The Meta-HTML Package System</h2>

  In Meta-HTML, all variables are stored in <em>packages</em>. A package
  is a set of pairs of variable names and their values. A variable name
  is also known as a <em>symbol</em>.

  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.

  Reference documentation on the package system can be found
  at <secref Packages>

  When you start up Meta-HTML a package named <code>DEFAULT</code> is
  created, and that becomes the current package. 

</plain-text>
<eval-table>
<set-var wizard-name="Gandalf">

<get-var wizard-name>
##BGandalfB##

<get-var default::wizard-name>
##BGandalfB##
</eval-table>

<plain-text>

  If you reference a package which does not yet exist, the package is
  created automatically the first time you set a value in it.

</plain-text>
<eval-table>
<set-var magic::wizard="Gandalf">

<get-var magic::wizard>
##BGandalfB##

<get-var wizard>
##B[Null string returned -- 'wizard' is not bound in the DEFAULT package]B##
</eval-table>

<plain-text>
  <h2>The <funref package-names> Function</h2>

  You can list all the packages in the environment using the
  <funref package-names> function. 

  <set-var magic::wizard="Gandalf">

  For example, the current packages which exist at this point in the
  evaluation of this page are:

  <blockquote>
  <pre>
  &lt;package-names&gt;
  <package-names>
  </pre>
  </blockquote>

  <h2>Packages Are A Convenient Way To Store Information</h2>

  Packages can be used conveniently in a variety of ways as 
  a data structure for storing sets of information. For example,
  a package can be used as a hash-table, where the symbols
  are the keys. You can enumerate or iterate over the
  symbols in a package using the <funref package-vars> function.

</plain-text>
<blockquote>
<pre>
&lt;set-var magic::wizard="Gandalf" 
magic::hobbits="Bilbo Baggins\nFrodo"
magic::monsters="Gollum\nSmaug\nShelob"&gt;
<set-var  magic::wizard="Gandalf" 
  magic::hobbits="Bilbo Baggins\nFrodo"
  magic::monsters="Gollum\nSmaug\nShelob">
&lt;package-vars magic&gt;

<b><package-vars magic></b>
</pre>
</blockquote>

<plain-text>
  The <funref package-vars> function returns an array of
  all symbol names which exist in a package. You can
  iterate over the elements of this array, as in the following example
  which prints the value of each symbol in the <em>magic</em> package.

  The following code prints the symbol values of the <em>magic</em>
  package in an HTML description-list environment.
</plain-text>

<example-table result>
<set-var symbols[]=<package-vars magic>>
<set-var i=0>
<dl>
  <while <get-var symbols[i]>>
    <dt><get-var symbols[i]>
    <dd>
    <pre>
    <get-var <get-var symbols[i]>>
    </pre>
    <increment i>
  </while>
</dl>
</example-table>

<plain-text>
  <h3>The <funref in-package> Function</h3>

  If you are going to be referencing the variables in a particular
  package frequently, you can set that package to be the current
  package, using the <funref in-package> function.

  When you set a package to be the current package, you no longer need
  to use the package-name as a prefix on that package's variables.

  For example, if we want to access the <code>magic::hobbits</code>
  variable, we can refer to it inside of an <funref in-package>
  body.

  <example-table result>
  <in-package magic>
    <get-var hobbits>
  </in-package>
  </example-table>

  A special package name of <code>"local"</code> will create 
  an anonymous package, and the variables in that package will
  only be visible inside of the <code>in-package</code> body. 


  <funref package-vars>
  <funref package-to-alist>

  <pagelist-control-panel>
</plain-text>
<include footer.mhtml>
