REF PACKAGES Titch Le Bek, Rob Duncan, 1986 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< LISP PACKAGES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file briefly describes the functions, variables and constants documented in Chapter 11 of the standard Common Lisp guide, which is: Common Lisp: The Language (Guy L. Steele, Digital Press, 1984). ------------------------------------------------- 1 A Listing of Functions Variables and Constants ------------------------------------------------- *modules* [variable] Contains a list of names of the modules that have been loaded into the Lisp system so far. Used by the functions provide and require. Default value: nil *package* [variable] Contains the current package; its initial value is the common-lisp-user package. The function load will always restore *package* to its current value once loading is completed. (defpackage name {option}*) [macro] This creates a new package named name (or modifies the existing one). The newly created or modified package is returned as the value of the defpackage form. Each option is a list of a keyword (the name of the option) and associated arguments. No part of a defpackage form is evaluated. The standard options for defpackage are as follows: (:size integer) This specifies approximately the number of symbols expected to be in the package. (:nicknames {package-name}*) The specified names become nicknames of the package being defined. (:shadow {symbol-name}*) Symbols with the specified names are created as shadows in the package being defined, just as with the function shadow. (:shadowing-import-from package-name {symbol-name}*) Symbols with the specified names are located in the specified package. These symbols are imported into the package being defined, shadowing other symbols if necessary, just as with the function shadowing-import. (:use {package-name}*) The package being defined is made to `use' (inherit from) the packages specified by this option, just as with the function use-package. If no :use option is supplied, then a default list is assumed as for make-package. (:import-from package-name {symbol-name}*) Symbols with the specified names are located in the specified package. These symbols are imported into the package being defined, just as with the function import. (:intern {symbol-name}*) Symbols with the specified names are located or created in the package being defined, just as with the function intern. Note that the action of this option may be affected by a :use option, because an inherited symbol will be used in preference to creating a new one. (:export {symbol-name}*) Symbols with the specified names are located or created in the package being defined and then exported, just as with the function export. Note that the action of this option may be affected by a :use, :import-from, or :shadowing-import-from option, because an inherited or imported symbol will be used in preference to creating a new one. (delete-package package) [function] Deletes the specified package from all package system data structures. If package is a name but there is currently no package of that name, a correctable error is signaled. Continuing from the error makes no deletion attempt but merely returns nil from the call to delete-package. If package is a package object that has already been deleted, no error is signaled and no deletion is attempted; instead, delete-package immediately returns nil. If the package specified for deletion is currently used by other packages, a correctable error is signaled. On continuing from this error, unuse-package is performed on all such other packages so as to remove their dependency on the specified package, after which delete-package proceeds to delete the specified package. If any symbol had the specified package as its home package before the call to delete-package, then its home package is undefined after the delete-package operation has been completed. Symbols in the deleted package are not modified in any other way. (do-all-symbols (var [form]) [macro] {declaration}* {tag | statement}*) do-all-symbols is similar to do-symbols but executes the body once for every symbol contained in every package. (do-external-symbols (var [package [form]]) [macro] {declaration}* {tag | statement}*) do-external-symbols is like do-symbols except that only the external symbols of package are scanned. (do-symbols (var [package [form]]) [macro] {declaration}* {tag | statement}*) do-symbols iterates over the symbols in package. The body is performed once for each symbol accessible in package with the variable var bound to the symbol. Then form is evaluated and its result is the value of do-symbols. (export symbols &optional package) [function] The symbols in the list symbols become accessible as external in package. export returns nil. (find-all-symbols name) [function] Returns a list containing every (interned) symbol whose print name is equal to name. (find-package name) [function] Returns the package called name, or nil if no such package exists. (find-symbol string &optional package) [function] If a symbol with the print-name string is accessible in package, that symbol and a keyword specifying its status are returned. Otherwise nil and nil are returned. (import symbols &optional package) [function] symbols become internal symbols in package. import signals a correctable error if any of the imported symbols has the same name as some other symbol already accessible in package. (in-package name) [macro] This macro causes *package* to be set to the package named name, which must be a symbol or string. The name is not evaluated. An error is signaled if the package does not already exist. Everything this macro does is also performed at compile time if the call appears at top level. (intern string &optional package) [function] package (which defaults to the current package) is searched for a symbol with the name specified by string. If no such symbol is found then one is created and installed in the specified package as an internal symbol. Two values are returned: the first is the symbol that was found or created; the second is nil if no pre-existing symbol was found and otherwise is one of three values - :internal, :external, :inherited. (list-all-packages) [function] Returns a list of all packages that currently exist in the Lisp system. (make-package name &key :nicknames :use) [function] Creates and returns a new package named name. :nicknames is a list of strings to be used as alternative names for the package. :use is a list of packages whose external symbols are to be inherited by the new package. :use defaults to a list containing the common-lisp package. (package-name package) [function] Returns a string naming package. (package-nicknames package) [function] Returns a list of nickname strings for package. (package-shadowing-symbols package) [function] Returns a list of shadowing symbols for package. (package-use-list package) [function] Returns a list of packages used by package. (package-used-by-list package) [function] Returns a list of all packages that use package. (provide name) [function] provide adds a new module name to the list of modules maintained. (rename-package package name &optional nicknames) [function] Replaces the old name and all the old nicknames of package with a new name (a string or symbol) and new nicknames (a list of strings or symbols which defaults to nil). (require name &optional pathname) [function] Loads the module named name from the file specified by pathname unless such has already been loaded. If pathname is not supplied, require will attempt to locate the source code by implementation-defined means. (shadow symbol-names &optional package) [function] For each symbol name in the list symbol-names, shadow checks whether a symbol of that name is present (directly, not by inheritance) in package, and if not, creates one. The members of symbol-names may either be symbols (in which case the print name is used) or strings. (shadowing-import symbols &optional package) [function] Each symbol in symbols is imported and placed on the shadowing-symbols list of package. (unexport symbols &optional package) [function] Changes the status of the symbols in package from external to internal. It is an error to unexport a symbol from the keyword package. (unintern symbol &optional package) [function] If symbol is in package unintern removes it and returns true. Otherwise unintern does nothing and returns nil. (unuse-package packages &optional package) [function] Removes the packages in packages from the use-list of package. (use-package packages &optional package) [function] Adds the packages in packages to the use-list of package. The new use-list is returned. (with-package-iterator (mname package-list {symbol-type}+) [macro] {form}*) The name mname is bound and defined as if by macrolet, with the body {form}* as its lexical scope, to be a `generator macro' such that each invocation of (mname) will return a symbol and that successive invocations will eventually deliver, one by one, all the symbols from the packages that are elements of the list that is the value of the expression package-list. At each invocation of the generator macro, there are two possibilities. If there is yet another unprocessed symbol, then four values are returned: t, the symbol, a keyword indicating the accessibility of the symbol within the package (see below), and the package from which the symbol was accessed. If there are no more unprocessed symbols in the list of packages, then one value is returned: nil. When the generator macro returns a symbol as its second value, the fourth value is always one of the packages present or named in the package-list value, and the third value is a keyword indicating accessibility: :internal means present in the package and not exported; :external means present and exported; and :inherited means not present (thus not shadowed) but inherited from some package used by the package that is the fourth value. Each symbol-type in an invocation of with-package-iterator is not evaluated. More than one may be present; their order does not matter. They indicate the accessibility types of interest. A symbol is not returned by the generator macro unless its actual accessibility matches one of the symbol-type indicators. The standard symbol-type indicators are :internal, :external, and :inherited. The order in which symbols are produced by successive invocations of the generator macro is not necessarily correlated in any way with the order of the packages in package-list. --- C.all/lisp/ref/packages --- Copyright University of Sussex 1993. All rights reserved.