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.
