HELP MODULES John Williams, Nov 1990 CONTENTS - (Use 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.