The p Context


Overview of Packages

The p context provides functions to support A+ package storage.

A package is a single structure containing A+ functions, variables, and dependencies. When a package is stored in a file, it is called a packfile. A packstring is a package in the form of a character array in an A+ workspace. A package can be used for storing a miscellaneous collection of A+ objects in a file, loading an application - it is usually faster than a script -, sending A+ objects through an adap connection, and performing lexical analysis (by a very knowledgeable person).

Packages are manipulated by external functions stored in the p context, which does not need to be loaded. The functions come in pairs: those whose unqualified names begin with s work on packstrings and those whose names begin with f work on packfiles. Package storage is optimized for fast retrieval, at the expense of space where necessary.

A package consists of a number of items, each of which is an object of one of these kinds:

Nothing else can be included in a package. In particular, an item cannot be an s attribute on a variable, the state of a variable's display, an attribute set with _set, a set or preset callback, an external function (i.e., a function loaded using _dyld), or an external state, such as an adap connection.

The only operations performed during retrieval from a package are:

If some other operation is required in order to restore some information, then you must provide a mechanism supplemental to package retrieval. For example, you could include in a package an initialization routine that sets attributes on variables.

Some of the restrictions, such as the one on dynamically loaded external functions, are due to an inability to retrieve the information needed to adequately store the object; they may possibly be lifted in the course of further development of the interpreter. Some objects, such as adap connections, are so complex that full retrieval of them may never be possible.

Other restrictions reflect a need for experience with packages and further thought. Callbacks, for instance, are not included because it is not clear whether during retrieval of a package variables should be specified and then callbacks set (so that no callbacks fire), callbacks should be set and then variables specified (so that all callbacks fire), or objects should be established in their order in the package definition (so that their order determines which callbacks fire).

Creation and Modification of Packages

To create a packstring or packfile, enter the appropriate one of these statements:
     psp.snew{obj}

     p.fnew{filenm; obj}
The result of p.fnew is null and that of p.snew, ps, is of course a packstring, which is a simple character string.

To add items to a package or replace them (where the names coincide), enter the appropriate one of these statements:

     newpsp.sadd{ps; obj}

     p.fadd{filenm; obj}
where the argument names have the same significance as in the previous pair of statements, except that ps can take the form of a nested vector (p;opts), in which p is a packstring and opts is a character string selecting options, the same as the options for the corresponding form of filenm. The result of p.fadd is null, and newps, the result of p.sadd, is a packstring, which can be the one being modified, ps.

Retrieval of Objects and Information from Packages

To establish (fix) objects in the workspace from data and definitions in a package, enter the appropriate one of these statements:
     p.sfix{ps; sel}

     p.ffix{filenm; sel}
where ps and filenm are as in the previous pair of statements and sel is one of:

The explicit result of both functions is the Null.

The following two functions return data from a package in the form of a slotfiller, without establishing any global objects:

     sfp.sslot{ps; sel}

     sfp.fslot{filenm; sel}
where the arguments are as described above, except that sel is only null or a list of names, not a two-element nested vector. In the result, sf, the first element lists the names of the objects and the second gives their values; in other words, sf is in one of the allowable forms for the right argument in the creation and modification functions.

A function retrieved in this way is returned as a function scalar. Since there is no analogous form for a dependency, it cannot really be retrieved by these functions, and it has a null value in sf.

   Inquiry and Options

A list of the items in a packstring or packfile can be obtained by entering the appropriate one of
     p.scatalog{psname}

     p.fcatalog{filenm}
They both produce symbol vectors.

An option string, which is a character vector, contains any of the following characters, with the indicated meanings:

d - debug: messages are to be generated by the package functions. Primarily for debugging.

h - hash table: the ...new and ...add functions are to make a hash table, for greater speed when only some items, not all, are being retrieved. Tables are retained in packages regardless of later settings of h. Primarily for packages used as component file systems.

p - pieces: ...fix, ...slot, and ...catalog, instead of operating normally, are to return the various parts of a package as a nested array. This option is primarily for debugging, but it also enables lexical analysis.

r - result: has the same effect as p except that ...fix is also to make assignments to global objects in the usual way.

s - stats: ...new and ...add are to issue messages containing statistics for the package just created.

v - verbose: the functions are to issue messages regarding objects handled, hash table creation, etc.

As indicated above, an option string can be included with an argument that names a file or string. When an option string is not so included, package functions use the default option string, whose initial value is ''.

This default string can be changed by entering the statement

     p.opts{optstring}
where optstring is the new default string.

Example

     b10+c27                Set up variables b and c
     f{x;y}:(|x)|y            and a function f
     d:f{b;c}                  and a dependency d, and
     sp.snew `b`c`d`f         put them in a packstring s
     'test.m''abcdefghijklmnop'
     mf1mf1'test.m'        Create mapped file mf
     b38; c1000;            Change values of b and c
     sp.sadd{s;`b`mf}         and change the b value in s
                               and put mapped file mf in s
     _ex `b`c`d`f`mf
 0 0 0 0 0
     mf1[0 1 2]'ABC'         Change contents of file, using mf1

     _ex `mf1
 0
     p.sfix{s;}               Establish the objects in s
     d                        Recall that we didn't
38                             change c in s
     mf                       mf has the latest value of the file.
ABCdefghijklmnop
     p.sslot{s;}              Retrieve s as a slotfiller.
<  `.b `.c `.d `.f `.mf
< <  38
  <  27
  <                           Null for the dependency.
  < .f                        A function scalar for a function.
  < ABCdefghijklmnop          The contents of the file.
      p.sslot{s;`b`c}         Selective retrieval, as a
<  `.b `.c                     slotfiller for visibility.
< <  38
  <  27

 Now demonstrate a packfile, an option string,  and a slotfiller argument.

     p.fnew{('test.m';"vh");(`one`two`three;(3;2;1))}
 PKG: 0: Storing .one        The v elicits messages.
 PKG: 1: Storing .two
 PKG: 2: Storing .three
 PKG: Storing hash table.    The h creates a hash table.
     p.fslot{'test.m';`two`three}
<  `.two `.three              Retrieved from the file.
< <  2
  <  1

doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.