HELP MODULES                                     John Williams, Nov 1990


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction
  2   Module Names
  3   Loading Modules
  4   Creating Modules
  5   Standard Poplog Modules
  6   The CONTRIB Module
  7   Accessing Pop-11 Library Packages


-----------------------------------------------------------------------
1  Introduction
-----------------------------------------------------------------------

Common Lisp provides a simple but convenient mechanism for creating and
loading modules. The term module denotes a large program, or suite of
programs, contained in one or more files, that can be handled as a
single named unit.

Modules may be coded in any Poplog language, though if a module is not
written in Lisp, it is the module's own responsibility to ensure the
appropiate data-structures and procedures are made available to Lisp
(see HELP * POPLISP and HELP * PROLOG for details of how this might be
done).


-----------------------------------------------------------------------
2  Module Names
-----------------------------------------------------------------------

Modules are referred to by name. Module names may either be strings or
symbols. Names are case-sensitive: the names "foo" and "FOO" are
different. However, symbols are translated to lower case, so :foo and
"FOO" are equivalent.

It is generally simplest to use keyword symbols for module names.
Keywords have several advantages: they don't need quoting, they are
unique, and they can't interfere with any symbols of the same name that
might be created by the module itself.

Symbols in the Pop11 package are treated specially. See the section
entitled Accessing Pop-11 Library Packages, below.


-----------------------------------------------------------------------
3  Loading Modules
-----------------------------------------------------------------------

To load a module into the Lisp environment, use:

    (require module-name &optional pathnames)

If the module has already been loaded, this just returns nil; otherwise
the relevant source files are located and loaded. If the source file
pathname(s) are not explicitly stated, require searches the directories
listed in the special variable *module-directory-list* for a file with
the same name as the module. An error is signaled if the module cannot
be located.


-----------------------------------------------------------------------
4  Creating Modules
-----------------------------------------------------------------------

To declare the existence of a module, use:

    (provide module-name)

Calls to provide are conventionally placed at the beginning of the
module. When provide is executed, the name of the module is added to the
list that is the value of the special variable *modules*, indicating
that the module has been loaded.

The source file should have the extension ".lsp" (as should all Lisp
files), and live in one of the directories in *module-directory-list*.
Initially, this list is

    ("$poplocal/local/lisp/modules/"
     "$usepop/pop/lisp/modules")

The second directory contains modules provided as a standard part of
Poplog Common Lisp (see below). The first enables sites to create their
own modules and make them accessible to all Poplog users at that site.
In addition, users are free to add other directories to the list, so
that they can maintain their own private collection of modules.

So, for example, the source for the PROCESS module called lives in

    $usepop/pop/lisp/modules/process.lsp


-----------------------------------------------------------------------
5  Standard Poplog Modules
-----------------------------------------------------------------------

Poplog Common Lisp provides these modules as standard:

    CONTRIB
    EXTERNAL
    HISTORY
    MAGIC-WORDS
    PROCESS
    PROFILE
    PROLOG
    RUN-UNIX-PROGRAM    (Unix only)
    SEQUENCE-COMPILER-MACROS
    STOREUTILS

Apart from the first, CONTRIB, each module has its own HELP file. The
CONTRIB module is discussed below.


-----------------------------------------------------------------------
6  The CONTRIB Module
-----------------------------------------------------------------------

The CONTRIB module simply adds the directory

    $popcontrib/lisp/modules

to the list of directories in *module-directory-list*.

Modules in this directory consist of UNSUPPORTED software, either
contributed by Poplog users, or of public-domain origin.

Currently there is just one module provided in this directory: CLX (a
well-known Lisp interface to the X window system). This is described in
HELP * CLX.

See HELP * CONTRIB for further information on $popcontrib.


-----------------------------------------------------------------------
7  Accessing Pop-11 Library Packages
-----------------------------------------------------------------------

If the module name given to require is a symbol in a package named
Pop11, and no module of that name can be found in the normal way, then
require will search the Pop-11 library for a file with the same name as
the symbol. If such a file is found, its name is automatically added to
*modules*, as if provide had been used. For example, to load the Pop-11
FLAVOURS library package, do

    (require 'pop11:flavours)

Note: Symbols in the Pop11 package are only treated specially if a Lisp
module of that name cannot be located. So a Lisp module called FLAVOURS
would shadow the Pop-11 library FLAVOURS. To explicitly load a
particular Pop-11 library, use either the magic word lib, or the Pop-11
procedure loadlib, thus:

    lib library-name

or

    (pop11:loadlib library-name)

The argument library-name should be a simple string.



--- C.all/lisp/help/modules
--- Copyright University of Sussex 1990. All rights reserved.
