dotfiles/gcl-info/chap-11.texi

@node Packages, Numbers (Numbers), Symbols, Top
@chapter Packages

@menu
* Package Concepts::		
* Packages Dictionary::		
@end menu

@node Package Concepts, Packages Dictionary, Packages, Packages
@section Package Concepts

@c including concept-packages

@menu
* Introduction to Packages::	
* Standardized Packages::	
@end menu

@node Introduction to Packages, Standardized Packages, Package Concepts, Package Concepts
@subsection Introduction to Packages

A @i{package}
@IGindex{package}
 establishes a mapping from names to @i{symbols}. 
At any given time, one @i{package} is current.
The @i{current package}
@IGindex{current package}
 is the one that is the @i{value} of @b{*package*}.
When using the @i{Lisp reader},
it is possible to refer to @i{symbols} in @i{packages} 
other than the current one through the use of @i{package prefixes} in the 
printed representation of the @i{symbol}.

Figure 11--1 lists some @i{defined names} that are applicable
to @i{packages}.
Where an @i{operator} 
takes an argument that is either a @i{symbol} or a @i{list} 
of @i{symbols},
an argument of @b{nil} is treated as an empty @i{list} of @i{symbols}.
Any @i{package} argument may be either a @i{string}, a @i{symbol}, or
a @i{package}.  If a @i{symbol} is supplied, its name will be used
as the @i{package} name.

@group
@noindent
@w{  *modules*            import                     provide           }
@w{  *package*            in-package                 rename-package    }
@w{  defpackage           intern                     require           }
@w{  do-all-symbols       list-all-packages          shadow            }
@w{  do-external-symbols  make-package               shadowing-import  }
@w{  do-symbols           package-name               unexport          }
@w{  export               package-nicknames          unintern          }
@w{  find-all-symbols     package-shadowing-symbols  unuse-package     }
@w{  find-package         package-use-list           use-package       }
@w{  find-symbol          package-used-by-list                         }

@noindent
@w{         Figure 11--1: Some Defined Names related to Packages       }

@end group

@menu
* Package Names and Nicknames::	 
* Symbols in a Package::	
* Internal and External Symbols::  
* Package Inheritance::		
* Accessibility of Symbols in a Package::  
* Locating a Symbol in a Package::  
* Prevention of Name Conflicts in Packages::  
@end menu

@node Package Names and Nicknames, Symbols in a Package, Introduction to Packages, Introduction to Packages
@subsubsection Package Names and Nicknames

Each @i{package} has a @i{name} (a @i{string}) and perhaps some @i{nicknames}
(also @i{strings}).
These are assigned when the @i{package} is created and can be changed later.  

There is a single namespace for @i{packages}.  
The @i{function} @b{find-package} translates a package
@i{name} or @i{nickname} into the associated @i{package}.  
The @i{function} @b{package-name} returns the @i{name} of a @i{package}.  
The @i{function} @b{package-nicknames} returns 
a @i{list} of all @i{nicknames} for a @i{package}.
@b{rename-package} removes a @i{package}'s
current @i{name} and @i{nicknames} and replaces them with new ones
specified by the caller.

@node Symbols in a Package, Internal and External Symbols, Package Names and Nicknames, Introduction to Packages
@subsubsection Symbols in a Package

@node Internal and External Symbols, Package Inheritance, Symbols in a Package, Introduction to Packages
@subsubsection Internal and External Symbols

The mappings in a @i{package} are divided into two classes, external and internal.
The @i{symbols} targeted by these different mappings 
are called @i{external symbols} and @i{internal symbols}
@IGindex{internal symbol}
 of the
@i{package}. Within a @i{package}, a name refers to one
@i{symbol} or to none; if it does refer
to a @i{symbol}, then it is either external or internal in that
@i{package}, but not both.
@i{External symbols}
@IGindex{external symbol}

are part of the package's public interface to other @i{packages}.
@i{Symbols} become @i{external symbols} of a given
@i{package} if they have been @i{exported} from that @i{package}.

A @i{symbol} has the same @i{name} no matter what @i{package} 
it is @i{present} in, but it might be an @i{external symbol} of some @i{packages}
and an @i{internal symbol} of others. 

@node Package Inheritance, Accessibility of Symbols in a Package, Internal and External Symbols, Introduction to Packages
@subsubsection Package Inheritance

@i{Packages} can be built up in layers.  From one point of view,
a @i{package} is a single collection
of mappings from @i{strings} into @i{internal symbols} and 
@i{external symbols}.
However, some of these mappings might be established within the @i{package} 
itself, while other mappings are inherited from other @i{packages} 
via @b{use-package}.
A @i{symbol} is said to be @i{present}
@IGindex{present}
 in a @i{package} 
if the mapping is in the @i{package} itself and is
not inherited from somewhere else.

There is no way to inherit the @i{internal symbols} of another @i{package};
to refer to an @i{internal symbol} using the @i{Lisp reader}, 
    a @i{package} containing the @i{symbol} 
     must be made to be the @i{current package},
    a @i{package prefix} must be used,
 or the @i{symbol} must be @i{imported} into the @i{current package}.

@node Accessibility of Symbols in a Package, Locating a Symbol in a Package, Package Inheritance, Introduction to Packages
@subsubsection Accessibility of Symbols in a Package

A @i{symbol} becomes @i{accessible}
@IGindex{accessible}
 in a @i{package} 
    if that is its @i{home package} when it is created,
 or if it is @i{imported} into that @i{package},
 or by inheritance via @b{use-package}.

If a @i{symbol} is @i{accessible} in a @i{package},
it can be referred to when using the @i{Lisp reader}
without a @i{package prefix} when that @i{package} is the @i{current package},
regardless of whether it is @i{present} or inherited.

@i{Symbols} from one @i{package} can be made @i{accessible} 
in another @i{package} in two ways.

@table @asis

@item --  
Any individual @i{symbol} can be added to a @i{package} by use
of @b{import}.  After the call to @b{import} the
@i{symbol} is @i{present} in the importing @i{package}.
The status of the @i{symbol} in the @i{package} 
it came from (if any) is unchanged, and the @i{home package} for
this @i{symbol} is unchanged.
Once @i{imported}, a @i{symbol} is @i{present} in the
importing @i{package}
and can be removed only by calling @b{unintern}.

A @i{symbol} is @i{shadowed}_3 by another @i{symbol} 
in some @i{package} if the first @i{symbol} would be @i{accessible}
by inheritance if not for the presence of the second @i{symbol}.
See @b{shadowing-import}.

@item --  
The second mechanism for making @i{symbols} from one @i{package}
@i{accessible} in another is provided by @b{use-package}.  
All of the @i{external symbols} of the used @i{package} are inherited
by the using @i{package}.
The @i{function} @b{unuse-package} undoes the effects of a previous @b{use-package}.  
@end table

@node Locating a Symbol in a Package, Prevention of Name Conflicts in Packages, Accessibility of Symbols in a Package, Introduction to Packages
@subsubsection Locating a Symbol in a Package

When a @i{symbol} is to be located in a given @i{package} 
the following occurs:
@table @asis

@item --  
The @i{external symbols} and @i{internal symbols} of the 
@i{package} are searched for the @i{symbol}.
@item --  
The @i{external symbols} of the used @i{packages} are 
searched
in some unspecified order.  The
order does not matter; see the rules for handling name
conflicts listed below. 
@end table

@node Prevention of Name Conflicts in Packages,  , Locating a Symbol in a Package, Introduction to Packages
@subsubsection Prevention of Name Conflicts in Packages

Within one @i{package}, any particular name can refer to at most one
@i{symbol}.  A name conflict is said to occur when there would be more than
one candidate @i{symbol}.  Any time a name conflict is about to occur,
a @i{correctable} @i{error} is signaled.  

The following rules apply to name conflicts:
@table @asis

@item --  
Name conflicts are detected when they become possible, that is, when the
package structure is altered.  Name
conflicts are not checked during every name lookup.

@item --  
If the @i{same} @i{symbol} is @i{accessible} to a @i{package} 
through more than one path, there is no name conflict.
A @i{symbol} cannot conflict with itself. 
Name conflicts occur only between @i{distinct} @i{symbols} with
the same name (under @b{string=}).

@item --  
Every @i{package} has a list of shadowing @i{symbols}.  
A shadowing @i{symbol} takes precedence over any other @i{symbol} of
the same name that would otherwise be @i{accessible} in the @i{package}.  
A name conflict involving a shadowing symbol is always resolved in favor of
the shadowing @i{symbol}, without signaling an error (except for one
exception involving @b{import}).
See @b{shadow} and @b{shadowing-import}.

@item --  
The functions @b{use-package}, @b{import}, and 
@b{export} check for name conflicts.  

@item --  
@b{shadow} and @b{shadowing-import} 
never signal a name-conflict error.

@item --  
@b{unuse-package} and @b{unexport}
do not need to do any name-conflict checking.
@b{unintern} does name-conflict checking only when a @i{symbol} 
being @i{uninterned} is a @i{shadowing symbol}
@IGindex{shadowing symbol}
.

@item --  
Giving a shadowing symbol to @b{unintern} 
can uncover a name conflict that had
previously been resolved by the shadowing.  

@item --  
Package functions signal name-conflict errors of @i{type} @b{package-error} before making any
  change to the package structure.  When multiple changes are to be made,
  it is
  permissible for the implementation to process each change separately.
  For example, when @b{export} is given a 
@i{list} of 
@i{symbols},
  aborting from a name
  conflict caused by the second @i{symbol} 
  in the @i{list} might still export the
  first @i{symbol} in the @i{list}.  
  However, a name-conflict error caused by @b{export}
  of a single @i{symbol} will be signaled before
  that @i{symbol}'s @i{accessibility} in any @i{package} is changed.

@item --  
Continuing from a name-conflict error must offer the user a chance to
resolve the name conflict in favor of either of the candidates.  The
@i{package} 
structure should be altered to reflect the resolution of the
name conflict, via @b{shadowing-import}, 
@b{unintern},
or @b{unexport}.

@item --  
A name conflict in @b{use-package} between a @i{symbol} 
@i{present} in the using @i{package} and an @i{external symbol} of the used 
@i{package} is resolved in favor of the first @i{symbol} by making it a
shadowing @i{symbol}, or in favor of the second @i{symbol} by uninterning
the first @i{symbol} from the using @i{package}. 

@item --  
A name conflict in @b{export} or @b{unintern} 
due to a @i{package}'s inheriting two @i{distinct} @i{symbols} 
with the @i{same} @i{name} (under @b{string=})
from two other @i{packages} can be resolved in
favor of either @i{symbol} by importing it into the using
@i{package} and making it a @i{shadowing symbol}
@IGindex{shadowing symbol}
,
just as with @b{use-package}.
@end table

@node Standardized Packages,  , Introduction to Packages, Package Concepts
@subsection Standardized Packages

This section describes the @i{packages} that are available
in every @i{conforming implementation}.  A summary of the
@i{names} and @i{nicknames} of those @i{standardized} @i{packages} 
is given in Figure 11--2.

@group
@noindent
@w{  Name              Nicknames  }
@w{  @t{COMMON-LISP}       @t{CL}         }
@w{  @t{COMMON-LISP-USER}  @t{CL-USER}    }
@w{  @t{KEYWORD}           @i{none}       }

@noindent
@w{  Figure 11--2: Standardized Package Names}

@end group

@menu
* The COMMON-LISP Package::	
* Constraints on the COMMON-LISP Package for Conforming Implementations::  
* Constraints on the COMMON-LISP Package for Conforming Programs::  
* Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs::  
* The COMMON-LISP-USER Package::  
* The KEYWORD Package::		
* Interning a Symbol in the KEYWORD Package::  
* Notes about The KEYWORD Package::  
* Implementation-Defined Packages::  
@end menu

@node The COMMON-LISP Package, Constraints on the COMMON-LISP Package for Conforming Implementations, Standardized Packages, Standardized Packages
@subsubsection The COMMON-LISP Package

@IPindex{common-lisp}

@IPindex{cl}

The @t{COMMON-LISP} @i{package} contains the primitives of the @r{Common Lisp} system as
defined by this specification.  Its @i{external} @i{symbols} include
all of the @i{defined names} (except for @i{defined names} in
the @t{KEYWORD} @i{package}) that are present in the @r{Common Lisp} system, 
such as @b{car}, @b{cdr},  @b{*package*}, etc.
The @t{COMMON-LISP} @i{package} has the @i{nickname} @t{CL}.

The @t{COMMON-LISP} @i{package} has as @i{external} @i{symbols} those 
symbols enumerated in the figures in @ref{Symbols in the COMMON-LISP Package}, and no others.
These @i{external} @i{symbols} are @i{present} in the @t{COMMON-LISP} @i{package}
but their @i{home package} need not be the @t{COMMON-LISP} @i{package}.

For example, the symbol @t{HELP} cannot be an @i{external symbol} of
the @t{COMMON-LISP} @i{package} because it is not mentioned in @ref{Symbols in the COMMON-LISP Package}.
In contrast, the @i{symbol} @b{variable}
must be an @i{external symbol} of the @t{COMMON-LISP} @i{package} 
even though it has no definition
because it is listed in that section
(to support its use as a valid second @i{argument} to the @i{function} @b{documentation}). 

The @t{COMMON-LISP} @i{package} can have additional @i{internal symbols}.

@node Constraints on the COMMON-LISP Package for Conforming Implementations, Constraints on the COMMON-LISP Package for Conforming Programs, The COMMON-LISP Package, Standardized Packages
@subsubsection Constraints on the COMMON-LISP Package for Conforming Implementations

In a @i{conforming implementation},
an @i{external} @i{symbol} of the @t{COMMON-LISP} @i{package} can have
   a @i{function}, @i{macro}, or @i{special operator} definition, 
   a @i{global variable} definition
   (or other status as a @i{dynamic variable} 
    due to a @b{special} @i{proclamation}),
or a @i{type} definition
only if explicitly permitted in this standard.
For example,
  @b{fboundp} @i{yields} @i{false} 
  for any @i{external symbol} of the @t{COMMON-LISP} @i{package} 
  that is not the @i{name} of a @i{standardized} 
   @i{function}, @i{macro} or @i{special operator},
and
  @b{boundp} returns @i{false} 
  for any @i{external symbol} of the @t{COMMON-LISP} @i{package} 
  that is not the @i{name} of a @i{standardized} @i{global variable}.
It also follows that
  @i{conforming programs} can use @i{external symbols} of the @t{COMMON-LISP} @i{package} 
  as the @i{names} of local @i{lexical variables} 
  with confidence that those @i{names} have not been @i{proclaimed} @b{special} 
  by the @i{implementation}
  unless those @i{symbols} are
    @i{names} of @i{standardized} @i{global variables}.

A @i{conforming implementation} must not place any @i{property} on
an @i{external symbol} of the @t{COMMON-LISP} @i{package} using a @i{property indicator}
that is either an @i{external symbol} of any @i{standardized} @i{package}
or a @i{symbol} that is otherwise @i{accessible} in the @t{COMMON-LISP-USER} @i{package}.

@node Constraints on the COMMON-LISP Package for Conforming Programs, Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, Constraints on the COMMON-LISP Package for Conforming Implementations, Standardized Packages
@subsubsection Constraints on the COMMON-LISP Package for Conforming Programs

@ITindex{redefinition}

Except where explicitly allowed, the consequences are undefined if any
of the following actions are performed on an @i{external symbol} 
of the @t{COMMON-LISP} @i{package}:

@table @asis

@item 1.  
@i{Binding} or altering its value (lexically or dynamically).
	      (Some exceptions are noted below.)

@item 2.  
Defining, 

	      undefining, 

	  or @i{binding} it as a @i{function}.
	      (Some exceptions are noted below.)

@item 3.  
Defining,

	      undefining, 

	   or @i{binding} it as a @i{macro}

	      or @i{compiler macro}.

	      (Some exceptions are noted below.)

@item 4.  
Defining it as a @i{type specifier} 
	      (via @b{defstruct}, 
		   @b{defclass},
		   @b{deftype},
		   @b{define-condition}).

@item 5.  
Defining it as a structure (via @b{defstruct}).

@item 6.  
Defining it as a @i{declaration} 
	      with a @b{declaration} @i{proclamation}.

@item 7.  
Defining it as a @i{symbol macro}.

@item 8.  
Altering its @i{home package}.

@item 9.  
Tracing it  (via @b{trace}).

@item 10.  
Declaring or proclaiming it
	       @b{special}
	       (via @b{declare},

		    @b{declaim},

		 or @b{proclaim}).

@item 11.  
Declaring or proclaiming its @b{type} or @b{ftype}
	       (via @b{declare},

		    @b{declaim},

		 or @b{proclaim}).
	       (Some exceptions are noted below.)

@item 12.  
Removing it from the @t{COMMON-LISP} @i{package}.

@item 13.  
Defining a @i{setf expander} for it 
	       (via @b{defsetf} or @b{define-setf-method}).

@item 14.  
Defining, undefining, or binding its @i{setf function name}.

@item 15.  
Defining it as a @i{method combination} type 
		(via @b{define-method-combination}).

@item 16.  
Using it as the class-name argument 
	       to @b{setf} of @b{find-class}.

@item 17.  
Binding it as a @i{catch tag}.

@item 18.  
Binding it as a @i{restart} @i{name}.

@item 19.  
Defining a @i{method} 
	       for a @i{standardized} @i{generic function} 
	       which is @i{applicable} when all of the @i{arguments}
      	       are @i{direct instances} of @i{standardized} @i{classes}.

@end table

@node Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, The COMMON-LISP-USER Package, Constraints on the COMMON-LISP Package for Conforming Programs, Standardized Packages
@subsubsection Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs

If an @i{external symbol} of the @t{COMMON-LISP} @i{package}
is not globally defined as a @i{standardized} @i{dynamic variable} 
					      or @i{constant variable},
it is allowed to lexically @i{bind} it 
          and to declare the @b{type} of that @i{binding}, 
and
it is allowed to locally @i{establish} it as a @i{symbol macro} 
(@i{e.g.}, with @b{symbol-macrolet}).

Unless explicitly specified otherwise,
if an @i{external symbol} of the @t{COMMON-LISP} @i{package} 
is globally defined as a @i{standardized} @i{dynamic variable},
it is permitted to @i{bind} or @i{assign} that @i{dynamic variable}
provided that the ``Value Type'' constraints on the @i{dynamic variable} 
are maintained, and that the new @i{value} of the @i{variable} 
is consistent with the stated purpose of the @i{variable}.

If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
it is allowed to lexically @i{bind} it as a @i{function} (@i{e.g.}, with @b{flet}),
              to declare the @b{ftype} of that @i{binding}, 
          and 
              (in @i{implementations} which provide the ability to do so)
	      to @b{trace} that @i{binding}.

If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
it is allowed to lexically @i{bind} it as a @i{macro} (@i{e.g.}, with @b{macrolet}).

If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined 
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
it is allowed to lexically @i{bind} its @i{setf function name}
as a @i{function},
and to declare the @b{ftype} of that @i{binding}.

@node The COMMON-LISP-USER Package, The KEYWORD Package, Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, Standardized Packages
@subsubsection The COMMON-LISP-USER Package

@IPindex{common-lisp-user}

@IPindex{cl-user}

The @t{COMMON-LISP-USER} @i{package} is the @i{current package} when 
a @r{Common Lisp} system starts up.  This @i{package} @i{uses} the @t{COMMON-LISP} @i{package}.
The @t{COMMON-LISP-USER} @i{package} has the @i{nickname} @t{CL-USER}.

The @t{COMMON-LISP-USER} @i{package} can have additional @i{symbols} @i{interned} within it;
it can @i{use} other @i{implementation-defined} @i{packages}.

@node The KEYWORD Package, Interning a Symbol in the KEYWORD Package, The COMMON-LISP-USER Package, Standardized Packages
@subsubsection The KEYWORD Package

@IPindex{keyword}

The @t{KEYWORD} @i{package} contains @i{symbols}, called @i{keywords}_1,
that are typically used as special markers in @i{programs} 
and their associated data @i{expressions}_1.

@i{Symbol} @i{tokens} that start with a @i{package marker} 
are parsed by the @i{Lisp reader} as @i{symbols} 
in the @t{KEYWORD} @i{package}; see @ref{Symbols as Tokens}.
This makes it notationally convenient to use @i{keywords}
when communicating between programs in different @i{packages}.  
For example, the mechanism for passing @i{keyword parameters} in a @i{call} uses 
@i{keywords}_1 to name the corresponding @i{arguments};
see @ref{Ordinary Lambda Lists}.

@i{Symbols} in the @t{KEYWORD} @i{package} are, by definition, of @i{type} @b{keyword}.

@node Interning a Symbol in the KEYWORD Package, Notes about The KEYWORD Package, The KEYWORD Package, Standardized Packages
@subsubsection Interning a Symbol in the KEYWORD Package

The @t{KEYWORD} @i{package} is treated differently than other @i{packages}
in that special actions are taken when a @i{symbol} is @i{interned} in it.
In particular, when a @i{symbol} is @i{interned} in the @t{KEYWORD} @i{package},
 it is automatically made to be an @i{external symbol} 
and is automatically made to be a @i{constant variable} with itself as a @i{value}.

@node Notes about The KEYWORD Package, Implementation-Defined Packages, Interning a Symbol in the KEYWORD Package, Standardized Packages
@subsubsection Notes about The KEYWORD Package

It is generally best to confine the use of @i{keywords} to situations in which
there are a finitely enumerable set of names to be selected between.  For example,
if there were two states of a light switch, they might be called @t{:on} and @t{:off}.

In situations where the set of names is not finitely enumerable
(@i{i.e.}, where name conflicts might arise)
it is frequently best to use @i{symbols} in some @i{package}
other than @t{KEYWORD} so that conflicts will be naturally avoided.
For example, it is generally not wise for a @i{program} to use a @i{keyword}_1 
as a @i{property indicator}, since if there were ever another @i{program}
that did the same thing, each would clobber the other's data.

@node Implementation-Defined Packages,  , Notes about The KEYWORD Package, Standardized Packages
@subsubsection Implementation-Defined Packages

Other, @i{implementation-defined} @i{packages} might be present
in the initial @r{Common Lisp} environment.

It is recommended, but not required, that the documentation for a
@i{conforming implementation} contain a full list of all @i{package} names
initially present in that @i{implementation} but not specified in this specification.
(See also the @i{function} @b{list-all-packages}.)

@c end of including concept-packages

@node Packages Dictionary,  , Package Concepts, Packages
@section Packages Dictionary

@c including dict-packages

@menu
* package::			
* export::			
* find-symbol::			
* find-package::		
* find-all-symbols::		
* import::			
* list-all-packages::		
* rename-package::		
* shadow::			
* shadowing-import::		
* delete-package::		
* make-package::		
* with-package-iterator::	
* unexport::			
* unintern::			
* in-package::			
* unuse-package::		
* use-package::			
* defpackage::			
* do-symbols::			
* intern::			
* package-name::		
* package-nicknames::		
* package-shadowing-symbols::	
* package-use-list::		
* package-used-by-list::	
* packagep::			
* *package*::			
* package-error::		
* package-error-package::	
@end menu

@node package, export, Packages Dictionary, Packages Dictionary
@subsection package                                                      [System Class]

@subsubheading  Class Precedence List::
@b{package},
@b{t}

@subsubheading  Description::

A @i{package} is a @i{namespace} that maps @i{symbol} @i{names}
to @i{symbols}; see @ref{Package Concepts}.

@subsubheading  See Also::

@ref{Package Concepts},
@ref{Printing Other Objects},
@ref{Symbols as Tokens}

@node export, find-symbol, package, Packages Dictionary
@subsection export                                                           [Function]

@code{export}  @i{symbols {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.

@i{package}---a @i{package designator}.

  The default is the @i{current package}.

@subsubheading  Description::

@b{export} makes one or more @i{symbols} that are @i{accessible} 
in @i{package} (whether directly or by inheritance) be @i{external symbols}
of that @i{package}. 

If any of the @i{symbols} is already @i{accessible} as 
an @i{external symbol} of @i{package},
@b{export} has no effect on that @i{symbol}.
If the @i{symbol} is 
@i{present} in @i{package} 
as an internal symbol, it is simply changed to external status.  
If it is @i{accessible} as an @i{internal symbol} via @b{use-package}, 
it
is first @i{imported} into @i{package},
then @i{exported}.
(The @i{symbol} is then @i{present} in the @i{package} 
whether or not @i{package} continues to use the @i{package} through 
which the @i{symbol} was originally inherited.)  

@b{export} makes 
each @i{symbol}
@i{accessible} to all the @i{packages} that use @i{package}.
All of these @i{packages} are checked for name conflicts:
@t{(export @i{s} @i{p})} does
@t{(find-symbol (symbol-name @i{s}) @i{q})} for each package @i{q}
in @t{(package-used-by-list @i{p})}.  Note that in the usual case of
an @b{export} during the initial definition of a @i{package}, 
the
result of @b{package-used-by-list}
is @b{nil} and the name-conflict checking
takes negligible time.
When multiple changes are to be made,
for example when @b{export} 
is given a @i{list} of @i{symbols}, it is
permissible for the implementation to process each change separately,
so that aborting from a name
conflict caused by any but the first @i{symbol} in the 
@i{list} does not unexport the
first @i{symbol} in the @i{list}. 
However, aborting from a name-conflict error
caused by @b{export} 
of one of @i{symbols} does not leave that @i{symbol} 
@i{accessible}
to some @i{packages} 
and @i{inaccessible} to others; with respect to
each of @i{symbols} processed, @b{export}
behaves as if it were as an atomic operation.

A name conflict in @b{export} between one of
@i{symbols} being exported and a
@i{symbol} already @i{present} in a @i{package} 
that would inherit the
newly-exported @i{symbol} 
may be resolved in favor of the exported @i{symbol}
by uninterning the other one, or in favor of the already-present
@i{symbol} by making it a shadowing symbol.

@subsubheading  Examples::

@example
 (make-package 'temp :use nil) @result{}  #<PACKAGE "TEMP">
 (use-package 'temp) @result{}  T
 (intern "TEMP-SYM" 'temp) @result{}  TEMP::TEMP-SYM, NIL
 (find-symbol "TEMP-SYM") @result{}  NIL, NIL
 (export (find-symbol "TEMP-SYM" 'temp) 'temp) @result{}  T
 (find-symbol "TEMP-SYM") @result{}  TEMP-SYM, :INHERITED
@end example

@subsubheading  Side Effects::

The package system is modified.

@subsubheading  Affected By::

@i{Accessible} @i{symbols}.

@subsubheading  Exceptional Situations::

If any of the @i{symbols} is not @i{accessible} at all in @i{package},
an error of @i{type} @b{package-error} is signaled that is @i{correctable} 
by permitting the @i{user}
to interactively specify whether that @i{symbol} should be @i{imported}.

@subsubheading  See Also::

@ref{import}
,
@ref{unexport}
,
@ref{Package Concepts}

@node find-symbol, find-package, export, Packages Dictionary
@subsection find-symbol                                                      [Function]

@code{find-symbol}  @i{string {&optional} package} @result{}  @i{symbol, status}

@subsubheading  Arguments and Values:: 

@i{string}---a @i{string}.

@i{package}---a @i{package designator}.

  The default is the @i{current package}.

@i{symbol}---a @i{symbol} accessible in the @i{package}, 
		 or @b{nil}.

@i{status}---one of @t{:inherited}, @t{:external}, @t{:internal}, or @b{nil}.

@subsubheading  Description::

@b{find-symbol} locates a @i{symbol} whose @i{name} is
@i{string} in a @i{package}.
If a @i{symbol} named @i{string} is found in @i{package},
directly or by inheritance, the @i{symbol} 
found is returned as the first
value; the second value is as follows:

@table @asis

@item @t{:internal}  
If the @i{symbol} is @i{present} in @i{package}
as an @i{internal symbol}.

@item @t{:external}  
If the @i{symbol} is @i{present} in @i{package}
as an @i{external symbol}.

@item @t{:inherited}  
If the @i{symbol} is inherited by @i{package} 
through @b{use-package},
but is not @i{present} in @i{package}.

@end table

If no such @i{symbol} is @i{accessible} in @i{package},
both values are @b{nil}.

@subsubheading  Examples::

@example
 (find-symbol "NEVER-BEFORE-USED") @result{}  NIL, NIL
 (find-symbol "NEVER-BEFORE-USED") @result{}  NIL, NIL
 (intern "NEVER-BEFORE-USED") @result{}  NEVER-BEFORE-USED, NIL
 (intern "NEVER-BEFORE-USED") @result{}  NEVER-BEFORE-USED, :INTERNAL
 (find-symbol "NEVER-BEFORE-USED") @result{}  NEVER-BEFORE-USED, :INTERNAL
 (find-symbol "never-before-used") @result{}  NIL, NIL
 (find-symbol "CAR" 'common-lisp-user) @result{}  CAR, :INHERITED
 (find-symbol "CAR" 'common-lisp) @result{}  CAR, :EXTERNAL
 (find-symbol "NIL" 'common-lisp-user) @result{}  NIL, :INHERITED
 (find-symbol "NIL" 'common-lisp) @result{}  NIL, :EXTERNAL
 (find-symbol "NIL" (prog1 (make-package "JUST-TESTING" :use '())
                           (intern "NIL" "JUST-TESTING")))
@result{}  JUST-TESTING::NIL, :INTERNAL
 (export 'just-testing::nil 'just-testing)
 (find-symbol "NIL" 'just-testing) @result{}  JUST-TESTING:NIL, :EXTERNAL
 (find-symbol "NIL" "KEYWORD")
@result{}  NIL, NIL
@i{OR}@result{} :NIL, :EXTERNAL
 (find-symbol (symbol-name :nil) "KEYWORD") @result{}  :NIL, :EXTERNAL
@end example

@subsubheading  Affected By::

@b{intern},
@b{import},
@b{export},
@b{use-package},
@b{unintern},
@b{unexport},
@b{unuse-package}

@subsubheading  See Also::

@ref{intern}
, 
@ref{find-all-symbols}

@subsubheading  Notes::

@b{find-symbol} is operationally equivalent to @b{intern}, 
except that it never creates a new @i{symbol}.

@node find-package, find-all-symbols, find-symbol, Packages Dictionary
@subsection find-package                                                     [Function]

@code{find-package}  @i{name} @result{}  @i{package}

@subsubheading  Arguments and Values::

@i{name}---a @i{string designator} or a @i{package} @i{object}.

@i{package}---a @i{package} @i{object} or @b{nil}.

@subsubheading  Description::

If @i{name} is a @i{string designator},
@b{find-package} locates and returns the
@i{package} whose name or nickname is @i{name}.
This
search is case sensitive.
If there is no such @i{package},
@b{find-package} returns @b{nil}.

If @i{name} is a @i{package} @i{object},
that @i{package} @i{object} is returned.

@subsubheading  Examples::

@example
 (find-package 'common-lisp) @result{}  #<PACKAGE "COMMON-LISP">
 (find-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (find-package 'not-there) @result{}  NIL
@end example

@subsubheading  Affected By::

The set of @i{packages} created by the @i{implementation}.

@b{defpackage},
@b{delete-package},
@b{make-package},
@b{rename-package}

@subsubheading  See Also::

@ref{make-package}

@node find-all-symbols, import, find-package, Packages Dictionary
@subsection find-all-symbols                                                 [Function]

@code{find-all-symbols}  @i{string} @result{}  @i{symbols}

@subsubheading  Arguments and Values::

@i{string}---a @i{string designator}.

@i{symbols}---a @i{list} of @i{symbols}.

@subsubheading  Description::

@b{find-all-symbols} searches
 every @i{registered package}
 for @i{symbols} that have a
@i{name} that is the @i{same} (under @b{string=}) as
@i{string}.  A @i{list} of all such @i{symbols} is returned.
Whether or how the @i{list} is ordered is
@i{implementation-dependent}.

@subsubheading  Examples::

@example
 (find-all-symbols 'car)
@result{}  (CAR)
@i{OR}@result{} (CAR VEHICLES:CAR)
@i{OR}@result{} (VEHICLES:CAR CAR)
 (intern "CAR" (make-package 'temp :use nil)) @result{}  TEMP::CAR, NIL
 (find-all-symbols 'car)
@result{}  (TEMP::CAR CAR)
@i{OR}@result{} (CAR TEMP::CAR)
@i{OR}@result{} (TEMP::CAR CAR VEHICLES:CAR)
@i{OR}@result{} (CAR TEMP::CAR VEHICLES:CAR)
@end example

@subsubheading  See Also::

@ref{find-symbol}

@node import, list-all-packages, find-all-symbols, Packages Dictionary
@subsection import                                                           [Function]

@code{import}  @i{symbols {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.

@i{package}---a @i{package designator}.

 The default is the @i{current package}.

@subsubheading  Description::

@b{import} adds @i{symbol} or
@i{symbols} to the internals of @i{package}, checking for name
conflicts with existing @i{symbols} either @i{present} in @i{package}
or @i{accessible} to it.  Once the @i{symbols} have been
@i{imported}, they may be referenced in the @i{importing}
@i{package} without the use of a @i{package prefix} when using the @i{Lisp reader}.

A name conflict in @b{import} between the
@i{symbol} being imported and a symbol inherited from some other @i{package} can 
be resolved in favor of the
@i{symbol} being @i{imported} 
by making it a shadowing symbol, or in favor
of the @i{symbol} already @i{accessible} by 
not doing the @b{import}.  A
name conflict in @b{import} with a @i{symbol} 
already @i{present} in the
@i{package} 
may be resolved by uninterning that @i{symbol}, or by not
doing the @b{import}.

The imported @i{symbol} is
not automatically exported from the @i{current package}, but if it is
already @i{present} and external, then the fact that it
is external is not changed.  

If any @i{symbol} to be @i{imported} has no home
package (@i{i.e.}, @t{(symbol-package @i{symbol}) @result{}  nil}), 
@b{import} sets the @i{home package}
of the @i{symbol} to @i{package}.

If the @i{symbol} is already @i{present} in the importing @i{package},
@b{import} has no effect.  

@subsubheading  Examples::

@example
 (import 'common-lisp::car (make-package 'temp :use nil)) @result{}  T
 (find-symbol "CAR" 'temp) @result{}  CAR, :INTERNAL
 (find-symbol "CDR" 'temp) @result{}  NIL, NIL 
@end example

The form @t{(import 'editor:buffer)} takes the external symbol named 
@t{buffer} in the @t{EDITOR} @i{package} (this symbol was located when the form
was read by the @i{Lisp reader}) and adds it to the @i{current package}
as an @i{internal symbol}. The symbol @t{buffer} is then @i{present} in
the @i{current package}.

@subsubheading  Side Effects::

The package system is modified.

@subsubheading  Affected By::

Current state of the package system.

@subsubheading  Exceptional Situations::

@b{import} signals a @i{correctable} error of @i{type} @b{package-error}
if any of the @i{symbols} to be @i{imported} has the @i{same} @i{name}
(under @b{string=}) as some distinct @i{symbol} (under @b{eql})
already @i{accessible} in the @i{package}, even if the conflict is
with a @i{shadowing symbol} of the @i{package}.

@subsubheading  See Also::

@ref{shadow}
, 
@ref{export}

@node list-all-packages, rename-package, import, Packages Dictionary
@subsection list-all-packages                                                [Function]

@code{list-all-packages}  @i{<@i{no @i{arguments}}>} @result{}  @i{packages}

@subsubheading  Arguments and Values:: 

@i{packages}---a @i{list} of @i{package} @i{objects}.

@subsubheading  Description::

@b{list-all-packages} returns a 

@i{fresh}

@i{list} of 

all @i{registered packages}.

@subsubheading  Examples::

@example
 (let ((before (list-all-packages)))
    (make-package 'temp)
    (set-difference (list-all-packages) before)) @result{}  (#<PACKAGE "TEMP">)
@end example

@subsubheading  Affected By::

@b{defpackage},
@b{delete-package},
@b{make-package}

@node rename-package, shadow, list-all-packages, Packages Dictionary
@subsection rename-package                                                   [Function]

@code{rename-package}  @i{package new-name {&optional} new-nicknames} @result{}  @i{package-object}

@subsubheading  Arguments and Values:: 

@i{package}---a @i{package designator}.

@i{new-name}---a @i{package designator}.

@i{new-nicknames}---a @i{list} of @i{string designators}.
 The default is the @i{empty list}.

@i{package-object}---the renamed @i{package} @i{object}.

@subsubheading  Description::

Replaces the name and nicknames of @i{package}.
The old name and all of the old nicknames of @i{package} are eliminated
and are replaced by @i{new-name} and @i{new-nicknames}.

The consequences are undefined if @i{new-name} or any @i{new-nickname}
conflicts with any existing package names.

@subsubheading  Examples::

@example
 (make-package 'temporary :nicknames '("TEMP")) @result{}  #<PACKAGE "TEMPORARY">
 (rename-package 'temp 'ephemeral) @result{}  #<PACKAGE "EPHEMERAL">
 (package-nicknames (find-package 'ephemeral)) @result{}  ()
 (find-package 'temporary) @result{}  NIL
 (rename-package 'ephemeral 'temporary '(temp fleeting))
@result{}  #<PACKAGE "TEMPORARY">
 (package-nicknames (find-package 'temp)) @result{}  ("TEMP" "FLEETING")
@end example

@subsubheading  See Also::

@ref{make-package}

@node shadow, shadowing-import, rename-package, Packages Dictionary
@subsection shadow                                                           [Function]

@code{shadow}  @i{symbol-names {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values:: 

@i{symbol-names}---a @i{designator} for 
		       a @i{list} of @i{string designators}.

@i{package}---a @i{package designator}.

 The default is the @i{current package}.

@subsubheading  Description::

@b{shadow} assures that @i{symbols} with names given 
by @i{symbol-names} are @i{present} 
in
the @i{package}.

Specifically, @i{package} is searched for @i{symbols} 
with the @i{names} supplied by @i{symbol-names}.

For each such @i{name}, if a corresponding @i{symbol} 
is not @i{present} in @i{package} (directly, not by inheritance), 
then a corresponding @i{symbol} is created with that @i{name},
and inserted into @i{package} as an @i{internal symbol}.
The corresponding @i{symbol}, whether pre-existing or newly created,
is then added, if not already present, to the @i{shadowing symbols list}
of @i{package}.

@subsubheading  Examples::

@example
 (package-shadowing-symbols (make-package 'temp)) @result{}  NIL
 (find-symbol 'car 'temp) @result{}  CAR, :INHERITED
 (shadow 'car 'temp) @result{}  T
 (find-symbol 'car 'temp) @result{}  TEMP::CAR, :INTERNAL
 (package-shadowing-symbols 'temp) @result{}  (TEMP::CAR)
@end example

@example
 (make-package 'test-1) @result{}  #<PACKAGE "TEST-1">
 (intern "TEST" (find-package 'test-1)) @result{}  TEST-1::TEST, NIL
 (shadow 'test-1::test (find-package 'test-1)) @result{}  T
 (shadow 'TEST (find-package 'test-1)) @result{}  T
 (assert (not (null (member 'test-1::test (package-shadowing-symbols
                                            (find-package 'test-1))))))

 (make-package 'test-2) @result{}  #<PACKAGE "TEST-2">
 (intern "TEST" (find-package 'test-2)) @result{}  TEST-2::TEST, NIL
 (export 'test-2::test (find-package 'test-2)) @result{}  T
 (use-package 'test-2 (find-package 'test-1))    ;should not error

@end example

@subsubheading  Side Effects::

@b{shadow} changes the state of the package system in such a 
way that the package consistency rules do not hold across the change.

@subsubheading  Affected By::

Current state of the package system.

@subsubheading  See Also::

@ref{package-shadowing-symbols}
,
@ref{Package Concepts}

@subsubheading  Notes::

If a @i{symbol} with a name in @i{symbol-names} already exists
in @i{package}, but by inheritance, the inherited symbol becomes
@i{shadowed}_3 by a newly created @i{internal symbol}.

@node shadowing-import, delete-package, shadow, Packages Dictionary
@subsection shadowing-import                                                 [Function]

@code{shadowing-import}  @i{symbols {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.

@i{package} ---a @i{package designator}.

 The default is the @i{current package}.

@subsubheading  Description::

@b{shadowing-import} is like @b{import}, 
but it does not signal an error even if the importation of a @i{symbol} 
would shadow some @i{symbol} already @i{accessible} in @i{package}.  

@b{shadowing-import} inserts each of @i{symbols} 
into @i{package} as an internal symbol, regardless
of whether another @i{symbol} of the same name is shadowed by this
action.
If a different @i{symbol} of the same name is already @i{present}
in @i{package},
that @i{symbol} is first @i{uninterned} from @i{package}.
The new @i{symbol} is added to @i{package}'s shadowing-symbols list.  

@b{shadowing-import} does name-conflict
checking to the extent that it checks whether a distinct existing
@i{symbol} with the same name is @i{accessible}; if so, it is shadowed by
the new @i{symbol}, which implies that it must be uninterned
if it was 
@i{present} in @i{package}.

@subsubheading  Examples::
@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (setq sym (intern "CONFLICT")) @result{}  CONFLICT
 (intern "CONFLICT" (make-package 'temp)) @result{}  TEMP::CONFLICT, NIL
 (package-shadowing-symbols 'temp) @result{}  NIL
 (shadowing-import sym 'temp) @result{}  T 
 (package-shadowing-symbols 'temp) @result{}  (CONFLICT)
@end example

@subsubheading  Side Effects::

@b{shadowing-import} 
changes the state of the package system in such a way that
the consistency rules do not hold across the change.

@i{package}'s shadowing-symbols list is modified.

@subsubheading  Affected By::

Current state of the package system.

@subsubheading  See Also::

@ref{import}
, 
@ref{unintern}
, 
@ref{package-shadowing-symbols}

@node delete-package, make-package, shadowing-import, Packages Dictionary
@subsection delete-package                                                   [Function]

@code{delete-package}  @i{package} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{package}---a @i{package designator}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

@b{delete-package} deletes @i{package} from all package system
data structures. 
If the operation is successful, @b{delete-package} returns
true, otherwise @b{nil}.
The effect of @b{delete-package} is that the name and nicknames
of @i{package} cease to be recognized package names.
The package @i{object} is still a @i{package} 
(@i{i.e.}, @b{packagep} is @i{true} of it)
but @b{package-name} returns @b{nil}.
The consequences of deleting the @t{COMMON-LISP} @i{package} or the @t{KEYWORD} @i{package} are undefined.
The consequences of invoking any other package operation on @i{package}
once it has been deleted are unspecified.
In particular, the consequences of invoking @b{find-symbol},
@b{intern} and other functions that look for a symbol name in
a @i{package} are unspecified if they are called with @b{*package*}
bound to the deleted @i{package} or with the deleted @i{package} 
as an argument.

If @i{package} is a @i{package} @i{object} that has already
been deleted, @b{delete-package} immediately returns @b{nil}.

After this operation completes, the 
@i{home package}
of any @i{symbol} whose @i{home package} 
had previously been
@i{package} 
is
@i{implementation-dependent}.
Except for this, @i{symbols} @i{accessible}
in @i{package} are not modified in any other way;
@i{symbols} whose @i{home package} is not @i{package} remain unchanged.

@subsubheading  Examples::

@example
 (setq *foo-package* (make-package "FOO" :use nil))
 (setq *foo-symbol*  (intern "FOO" *foo-package*))
 (export *foo-symbol* *foo-package*)

 (setq *bar-package* (make-package "BAR" :use '("FOO")))
 (setq *bar-symbol*  (intern "BAR" *bar-package*))
 (export *foo-symbol* *bar-package*)
 (export *bar-symbol* *bar-package*)

 (setq *baz-package* (make-package "BAZ" :use '("BAR")))

 (symbol-package *foo-symbol*) @result{}  #<PACKAGE "FOO">
 (symbol-package *bar-symbol*) @result{}  #<PACKAGE "BAR">

 (prin1-to-string *foo-symbol*) @result{}  "FOO:FOO"
 (prin1-to-string *bar-symbol*) @result{}  "BAR:BAR"

 (find-symbol "FOO" *bar-package*) @result{}  FOO:FOO, :EXTERNAL

 (find-symbol "FOO" *baz-package*) @result{}  FOO:FOO, :INHERITED
 (find-symbol "BAR" *baz-package*) @result{}  BAR:BAR, :INHERITED

 (packagep *foo-package*) @result{}  @i{true}
 (packagep *bar-package*) @result{}  @i{true}
 (packagep *baz-package*) @result{}  @i{true}

 (package-name *foo-package*) @result{}  "FOO"
 (package-name *bar-package*) @result{}  "BAR"
 (package-name *baz-package*) @result{}  "BAZ"

 (package-use-list *foo-package*) @result{}  ()
 (package-use-list *bar-package*) @result{}  (#<PACKAGE "FOO">)
 (package-use-list *baz-package*) @result{}  (#<PACKAGE "BAR">)

 (package-used-by-list *foo-package*) @result{}  (#<PACKAGE "BAR">)
 (package-used-by-list *bar-package*) @result{}  (#<PACKAGE "BAZ">)
 (package-used-by-list *baz-package*) @result{}  ()

 (delete-package *bar-package*)
@t{ |> } Error: Package BAZ uses package BAR.
@t{ |> } If continued, BAZ will be made to unuse-package BAR,
@t{ |> } and then BAR will be deleted.
@t{ |> } Type :CONTINUE to continue.
@t{ |> } Debug> @b{|>>}@t{:CONTINUE}@b{<<|}
@result{}  T

 (symbol-package *foo-symbol*) @result{}  #<PACKAGE "FOO">
 (symbol-package *bar-symbol*) is unspecified

 (prin1-to-string *foo-symbol*) @result{}  "FOO:FOO"
 (prin1-to-string *bar-symbol*) is unspecified

 (find-symbol "FOO" *bar-package*) is unspecified

 (find-symbol "FOO" *baz-package*) @result{}  NIL, NIL
 (find-symbol "BAR" *baz-package*) @result{}  NIL, NIL

 (packagep *foo-package*) @result{}  T
 (packagep *bar-package*) @result{}  T
 (packagep *baz-package*) @result{}  T

 (package-name *foo-package*) @result{}  "FOO"
 (package-name *bar-package*) @result{}  NIL
 (package-name *baz-package*) @result{}  "BAZ"

 (package-use-list *foo-package*) @result{}  ()
 (package-use-list *bar-package*) is unspecified
 (package-use-list *baz-package*) @result{}  ()

 (package-used-by-list *foo-package*) @result{}  ()
 (package-used-by-list *bar-package*) is unspecified
 (package-used-by-list *baz-package*) @result{}  ()
@end example

@subsubheading  Exceptional Situations::

If the @i{package} @i{designator} is a @i{name} that does not 
currently name a @i{package}, 
a @i{correctable} error of @i{type} @b{package-error} is signaled.
If correction is attempted, no deletion action is attempted; 
instead, @b{delete-package} immediately returns @b{nil}.

If @i{package} is used by other @i{packages}, 
a @i{correctable} error of @i{type} @b{package-error} is signaled.
If correction is attempted,
@b{unuse-package} is effectively called to remove any dependencies, 
causing @i{package}'s @i{external symbols} to cease being @i{accessible} to those 
@i{packages} that use @i{package}. 
@b{delete-package} then deletes @i{package} just as it would have had 
there been no @i{packages} that used it.

@subsubheading  See Also::

@ref{unuse-package}

@node make-package, with-package-iterator, delete-package, Packages Dictionary
@subsection make-package                                                     [Function]

@code{make-package}  @i{package-name {&key} nicknames use} @result{}  @i{package}

@subsubheading  Arguments and Values::

@i{package-name}---a @i{string designator}.

@i{nicknames}---a @i{list} of @i{string designators}.
  The default is the @i{empty list}.

@i{use}---
a @i{list} of @i{package designators}.

  The default is @i{implementation-defined}.

@i{package}---a @i{package}.

@subsubheading  Description::

Creates a new @i{package} with the name @i{package-name}.  

@i{Nicknames} are additional @i{names} which may be used
to refer to the new @i{package}.

@i{use} specifies zero or more @i{packages} 
the @i{external symbols} of which are to be inherited by
the new @i{package}.  See the @i{function} @b{use-package}.

@subsubheading  Examples::                       

@example
 (make-package 'temporary :nicknames '("TEMP" "temp")) @result{}  #<PACKAGE "TEMPORARY">
 (make-package "OWNER" :use '("temp")) @result{}  #<PACKAGE "OWNER">
 (package-used-by-list 'temp) @result{}  (#<PACKAGE "OWNER">)
 (package-use-list 'owner) @result{}  (#<PACKAGE "TEMPORARY">)
@end example

@subsubheading  Affected By::

The existence of other @i{packages} in the system.

@subsubheading  Exceptional Situations::

The consequences are unspecified if @i{packages} denoted by @i{use}
do not exist.

A @i{correctable} error is signaled if the @i{package-name} 
or any of the @i{nicknames} is already 
the @i{name} or @i{nickname} of an existing @i{package}.

@subsubheading  See Also::

@ref{defpackage}
,
@ref{use-package}

@subsubheading  Notes::

In situations where the @i{packages} to be used contain symbols which would conflict,
it is necessary to first create the package with @t{:use '()},
then to use @b{shadow} or @b{shadowing-import} to address the conflicts,
and then after that to use @b{use-package} once the conflicts have been addressed.

When packages are being created as part of the static definition of a program
rather than dynamically by the program, it is generally considered more stylistically
appropriate to use @b{defpackage} rather than @b{make-package}.

@node with-package-iterator, unexport, make-package, Packages Dictionary
@subsection with-package-iterator                                               [Macro]

@code{with-package-iterator}  @i{@r{(}name package-list-form {&rest} {symbol-types}@r{)}
 		   @{@i{declaration}@}{*} @{@i{form}@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values::

@i{name}---a @i{symbol}.

@i{package-list-form}---a @i{form}; evaluated once to produce a @i{package-list}.

@i{package-list}---a @i{designator} for a list of @i{package designators}.

@i{symbol-type}---one of the @i{symbols} 
		      @t{:internal}, @t{:external}, or @t{:inherited}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{forms}---an @i{implicit progn}.

@i{results}---the @i{values} of the @i{forms}.

@subsubheading  Description::

Within the lexical scope of the body @i{forms},
the @i{name} is defined via @b{macrolet} 
such that successive invocations of @t{(@i{name})}
will return the @i{symbols}, one by one, 
from the @i{packages} in @i{package-list}. 

It is unspecified whether @i{symbols} inherited from
multiple @i{packages} are returned more than once.  
The order of @i{symbols} returned does not necessarily reflect the order
of @i{packages} in @i{package-list}.  When @i{package-list} has 
more than one element, it is unspecified whether duplicate @i{symbols} are
returned once or more than once.  

@i{Symbol-types} controls which @i{symbols} that are @i{accessible}
in a @i{package} are returned as follows:

@table @asis

@item @t{:internal}  
The @i{symbols} that are @i{present} in the @i{package},
  but that are not @i{exported}.

@item @t{:external}  
The @i{symbols} that are @i{present} in the @i{package}
  and are @i{exported}.

@item @t{:inherited}  
The @i{symbols} that are @i{exported} by used @i{packages}
  and that are not @i{shadowed}.
@end table

When more than one argument is supplied for @i{symbol-types}, 
a @i{symbol} is returned if its @i{accessibility} matches 
any one of the @i{symbol-types} supplied.  
Implementations may extend this syntax by recognizing additional 
symbol accessibility types.

An invocation of @t{(@i{name})} returns four values as follows:

@table @asis

@item 1.  
A flag that indicates whether a @i{symbol} is returned
	      (true means that a @i{symbol} is returned).
@item 2.  
A @i{symbol} that is @i{accessible} in one the
	      indicated @i{packages}.
@item 3.  
The accessibility type for that @i{symbol}; 
	      @i{i.e.}, one of the symbols @t{:internal}, @t{:external}, or @t{:inherited}.
@item 4.  
The @i{package} from which the @i{symbol} was obtained.
	      The @i{package} is one of the @i{packages} present 
	      or named in @i{package-list}.
@end table

After all @i{symbols} have been returned by successive invocations of
@t{(@i{name})}, then only one value is returned, namely @b{nil}.

The meaning of the second, third, and fourth @i{values} is that the returned 
@i{symbol} is @i{accessible} in the returned @i{package}
in the way indicated by the second return value as follows:

@table @asis

@item @t{:internal}  
Means @i{present} and not @i{exported}.

@item @t{:external}  
Means @i{present} and @i{exported}.

@item @t{:inherited}  
Means not @i{present} (thus not @i{shadowed}) but inherited
from some used @i{package}.
@end table

It is unspecified what happens if any of the implicit interior state 
of an iteration is returned outside the dynamic extent of the 
@b{with-package-iterator}
form such as by returning some @i{closure} over the invocation @i{form}.

Any number of invocations of @b{with-package-iterator} 
can be nested, and the body of the innermost one can invoke all of the
locally @i{established} @i{macros}, provided all those @i{macros}
have distinct names.

@subsubheading  Examples::

The following function should return @b{t} on any @i{package}, and signal
an error if the usage of @b{with-package-iterator} does not agree
with the corresponding usage of @b{do-symbols}.

@example
 (defun test-package-iterator (package)
   (unless (packagep package)
     (setq package (find-package package)))
   (let ((all-entries '())
         (generated-entries '()))
     (do-symbols (x package) 
       (multiple-value-bind (symbol accessibility) 
           (find-symbol (symbol-name x) package)
         (push (list symbol accessibility) all-entries)))
     (with-package-iterator (generator-fn package 
                             :internal :external :inherited)
       (loop     
         (multiple-value-bind (more? symbol accessibility pkg)
             (generator-fn)
           (unless more? (return))
           (let ((l (multiple-value-list (find-symbol (symbol-name symbol) 
                                                      package))))
             (unless (equal l (list symbol accessibility))
               (error "Symbol ~S not found as ~S in package ~A [~S]"
                      symbol accessibility (package-name package) l))
             (push l generated-entries)))))
     (unless (and (subsetp all-entries generated-entries :test #'equal)
                  (subsetp generated-entries all-entries :test #'equal))
      (error "Generated entries and Do-Symbols entries don't correspond"))
     t))
@end example

The following function prints out every @i{present} @i{symbol} 
(possibly more than once):

@example
 (defun print-all-symbols () 
   (with-package-iterator (next-symbol (list-all-packages)
                           :internal :external)
     (loop
       (multiple-value-bind (more? symbol) (next-symbol)
         (if more? 
            (print symbol)
            (return))))))
@end example

@subsubheading  Exceptional Situations::

@b{with-package-iterator} signals an error of @i{type} @b{program-error} if 
no @i{symbol-types} are supplied or if a @i{symbol-type} is not
recognized  by the implementation is supplied.  

The consequences are undefined if the local function named @i{name}
@i{established} by @b{with-package-iterator} is called after it 
has returned @i{false} as its @i{primary value}.

@subsubheading  See Also::

@ref{Traversal Rules and Side Effects}

@node unexport, unintern, with-package-iterator, Packages Dictionary
@subsection unexport                                                         [Function]

@code{unexport}  @i{symbols {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values:: 

@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.

@i{package}---a @i{package designator}.

  The default is the @i{current package}.

@subsubheading  Description::

@b{unexport} reverts external @i{symbols} in @i{package} to
internal status; it undoes the effect of @b{export}.

@b{unexport} works only on @i{symbols} 
@i{present}
in @i{package}, switching them back to internal status.
If @b{unexport} is given a @i{symbol} that is 
already @i{accessible} as an @i{internal symbol} in @i{package},
it does nothing.

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (export (intern "CONTRABAND" (make-package 'temp)) 'temp) @result{}  T
 (find-symbol "CONTRABAND") @result{}  NIL, NIL 
 (use-package 'temp) @result{}  T 
 (find-symbol "CONTRABAND") @result{}  CONTRABAND, :INHERITED
 (unexport 'contraband 'temp) @result{}  T
 (find-symbol "CONTRABAND") @result{}  NIL, NIL
@end example

@subsubheading  Side Effects::

Package system is modified.

@subsubheading  Affected By::

Current state of the package system.

@subsubheading  Exceptional Situations::

If @b{unexport} is given a @i{symbol}
not @i{accessible} in @i{package} at all, 
an error of @i{type} @b{package-error} is signaled.

The consequences are undefined if @i{package} is the @t{KEYWORD} @i{package}
or the @t{COMMON-LISP} @i{package}.

@subsubheading  See Also::

@ref{export}
, @ref{Package Concepts}

@node unintern, in-package, unexport, Packages Dictionary
@subsection unintern                                                         [Function]

@code{unintern}  @i{symbol {&optional} package} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{symbol}---a @i{symbol}.

@i{package}---a @i{package designator}.

  The default is the @i{current package}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::                      
@b{unintern} removes @i{symbol} from @i{package}.
If @i{symbol} is @i{present} in @i{package}, it is
removed from @i{package} and also from @i{package}'s 
@i{shadowing symbols list} if it is present there.  If @i{package} is the
@i{home package} for @i{symbol}, @i{symbol} is made to have no 
@i{home package}.
@i{Symbol} may continue to be @i{accessible}
in @i{package} by inheritance.

Use of @b{unintern} can result in a @i{symbol} 
that has no
recorded @i{home package},
but that in fact is @i{accessible} in some @i{package}.
@r{Common Lisp} does not check for this pathological case, 
and such @i{symbols}
are always printed preceded by @t{#:}.

@b{unintern} returns @i{true} if it removes @i{symbol}, and @b{nil} otherwise.

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (setq temps-unpack (intern "UNPACK" (make-package 'temp))) @result{}  TEMP::UNPACK 
 (unintern temps-unpack 'temp) @result{}  T
 (find-symbol "UNPACK" 'temp) @result{}  NIL, NIL 
 temps-unpack @result{}  #:UNPACK 
@end example

@subsubheading  Side Effects::

@b{unintern} changes the state of the
package system in such a way that the consistency rules do not hold
across the change.

@subsubheading  Affected By::
Current state of the package system.

@subsubheading  Exceptional Situations::
Giving a shadowing symbol to @b{unintern} 
can uncover a name conflict that had
previously been resolved by the shadowing.  If package A uses packages
B and C, A contains a shadowing symbol @t{x}, and B and C each contain external
symbols named @t{x}, then removing the shadowing symbol @t{x}
from A will reveal a name
conflict between @t{b:x} and @t{c:x} if those two @i{symbols} are distinct.
In this case @b{unintern} will signal an error.

@subsubheading  See Also::

@ref{Package Concepts}

@node in-package, unuse-package, unintern, Packages Dictionary
@subsection in-package                                                          [Macro]

@code{in-package}  @i{name} @result{}  @i{package}

@subsubheading  Arguments and Values::

@i{name}---a @i{string designator}; not evaluated.

@i{package}---the @i{package} named by @i{name}.

@subsubheading  Description::

Causes the the @i{package} named by @i{name} 
to become the @i{current package}---that is, the @i{value} of @b{*package*}.
If no such @i{package} already exists, an error of @i{type} @b{package-error} is signaled.

Everything @b{in-package} does is also performed at compile time
if the call appears as a @i{top level form}.

@subsubheading  Side Effects::

The @i{variable} @b{*package*} is assigned.
If the @b{in-package} @i{form} is a @i{top level form}, 
this assignment also occurs at compile time.

@subsubheading  Exceptional Situations::

An error of @i{type} @b{package-error} is signaled if the specified @i{package} does not exist.

@subsubheading  See Also::

@ref{package}

@node unuse-package, use-package, in-package, Packages Dictionary
@subsection unuse-package                                                    [Function]

@code{unuse-package}  @i{packages-to-unuse {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{packages-to-unuse}---a @i{designator} for
			    a @i{list} of @i{package designators}.

@i{package}---a @i{package designator}.
 The default is the @i{current package}.

@subsubheading  Description::

@b{unuse-package} causes @i{package} to cease inheriting
all the @i{external symbols} of 
@i{packages-to-unuse}; @b{unuse-package} undoes
the effects of @b{use-package}.   The 
@i{packages-to-unuse} 
are removed from the @i{use list} of @i{package}.

Any @i{symbols} that have been
@i{imported} into @i{package} continue to be @i{present} in @i{package}.

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (export (intern "SHOES" (make-package 'temp)) 'temp) @result{}  T
 (find-symbol "SHOES") @result{}  NIL, NIL
 (use-package 'temp) @result{}  T
 (find-symbol "SHOES") @result{}  SHOES, :INHERITED
 (find (find-package 'temp) (package-use-list 'common-lisp-user)) @result{}  #<PACKAGE "TEMP">
 (unuse-package 'temp) @result{}  T
 (find-symbol "SHOES") @result{}  NIL, NIL
@end example

@subsubheading  Side Effects::

The @i{use list} of @i{package} is modified.

@subsubheading  Affected By::
Current state of the package system.

@subsubheading  See Also::

@ref{use-package}
, 
@ref{package-use-list}

@node use-package, defpackage, unuse-package, Packages Dictionary
@subsection use-package                                                      [Function]

@code{use-package}  @i{packages-to-use {&optional} package} @result{}  @i{@b{t}}

@subsubheading  Arguments and Values::

@i{packages-to-use}---a @i{designator} for 
			  a @i{list} of @i{package designators}.
  The @t{KEYWORD} @i{package} may not be supplied.

@i{package}---a @i{package designator}.
  The @t{KEYWORD} @i{package} cannot be supplied.
  The default is the @i{current package}.

@subsubheading  Description::

@b{use-package} causes @i{package} to inherit all the
@i{external symbols} of @i{packages-to-use}.
The inherited @i{symbols} become @i{accessible} as 
@i{internal symbols} of @i{package}.  

@i{Packages-to-use} are added to the @i{use list} of @i{package}
if they are not there already.  All @i{external symbols} in
@i{packages-to-use} become @i{accessible} in @i{package}
as @i{internal symbols}.
@b{use-package} does not cause any new @i{symbols} to be @i{present}
in @i{package} but only makes them @i{accessible} by inheritance.

@b{use-package} checks for
name conflicts between the newly imported symbols and those already
@i{accessible} in @i{package}.  
A name conflict in @b{use-package} 
between two external symbols inherited
by @i{package} from @i{packages-to-use} may be resolved in favor of
either @i{symbol} 
by @i{importing} one of them into @i{package} and making it a
shadowing symbol. 

@subsubheading  Examples::

@example
 (export (intern "LAND-FILL" (make-package 'trash)) 'trash) @result{}  T
 (find-symbol "LAND-FILL" (make-package 'temp)) @result{}  NIL, NIL
 (package-use-list 'temp) @result{}  (#<PACKAGE "TEMP">)
 (use-package 'trash 'temp) @result{}  T
 (package-use-list 'temp) @result{}  (#<PACKAGE "TEMP"> #<PACKAGE "TRASH">)
 (find-symbol "LAND-FILL" 'temp) @result{}  TRASH:LAND-FILL, :INHERITED
@end example

@subsubheading  Side Effects::

The @i{use list} of @i{package} may be modified.

@subsubheading  See Also::

@ref{unuse-package}
,
@ref{package-use-list}
,
@ref{Package Concepts}

@subsubheading  Notes::

It is permissible for a @i{package} P_1 
to @i{use} a @i{package} P_2
even if P_2 already uses P_1.
The using of @i{packages} is not transitive, 
so no problem results from the apparent circularity.

@node defpackage, do-symbols, use-package, Packages Dictionary
@subsection defpackage                                                          [Macro]

@code{defpackage}  @i{defined-package-name [[!@i{option}]]} @result{}  @i{package}

@w{@i{option} ::=@{{(}@t{:nicknames} @{@i{nickname}@}{*}@r{)}@}{*} | }
@w{           @r{(}@t{:documentation} @i{string}@r{)} | }
@w{           @{{(}@t{:use} @{@i{package-name}@}{*}@r{)}@}{*} | }
@w{           @{{(}@t{:shadow} @{!@i{symbol-name}@}{*}@r{)}@}{*} | }
@w{           @{{(}@t{:shadowing-import-from} @i{package-name} @{!@i{symbol-name}@}{*}@r{)}@}{*} | }
@w{           @{{(}@t{:import-from} @i{package-name} @{!@i{symbol-name}@}{*}@r{)}@}{*} | }
@w{           @{{(}@t{:export} @{!@i{symbol-name}@}{*}@r{)}@}{*} | }
@w{           @{{(}@t{:intern} @{!@i{symbol-name}@}{*}@r{)}@}{*} | }
@w{           @r{(}@t{:size} @i{integer}@r{)}}

@w{@i{symbol-name} ::=(@i{symbol} | @i{string})}

@subsubheading  Arguments and Values::

@i{defined-package-name}---a @i{string designator}.

@i{package-name}---a @i{package designator}.

@i{nickname}---a @i{string designator}.

@i{symbol-name}---a @i{string designator}.

@i{package}---the @i{package} named @i{package-name}.

@subsubheading  Description::

@b{defpackage} creates a @i{package} as specified and returns 
the @i{package}.

If @i{defined-package-name} already refers to an existing 
@i{package}, the name-to-package mapping for that name is not changed.
If the new definition is at variance with the current state of that
@i{package}, the consequences are undefined;  an implementation
might choose to modify the existing @i{package} to reflect the
new definition.  If @i{defined-package-name} is a @i{symbol},
its @i{name} is used.

The standard @i{options} are described below. 

@table @asis

@item @t{:nicknames}  
The arguments to @t{:nicknames} set the @i{package}'s nicknames to the
supplied names.

@item @t{:documentation}  
The argument to @t{:documentation} specifies a @i{documentation string};
it is attached as a @i{documentation string} to the @i{package}.
At most one @t{:documentation} option 
can appear in a single @b{defpackage} @i{form}.

@item @t{:use}  
The arguments to @t{:use} set the @i{packages} that the @i{package}
named by @i{package-name}
will inherit from. If @t{:use} is not supplied,

it defaults to the same @i{implementation-dependent} value as the @t{:use} @i{argument} to
@b{make-package}.

@item @t{:shadow}  
The arguments to @t{:shadow}, @i{symbol-names}, name @i{symbols} 
that are to be created in the @i{package} being defined.
These @i{symbols} are added to the list of shadowing
@i{symbols} effectively as if by @b{shadow}.

@item @t{:shadowing-import-from}  
The @i{symbols} named by the argument @i{symbol-names}
are found (involving a lookup as if by @b{find-symbol})
in the specified @i{package-name}.  The resulting @i{symbols}
are @i{imported} into the @i{package} being defined, and 
placed on the shadowing symbols list as if by @b{shadowing-import}.
In no case are @i{symbols} created in any @i{package}
other than the one being defined.

@item @t{:import-from}  
The @i{symbols} named by the argument @i{symbol-names}
are found in the @i{package} named by @i{package-name} and 
they are @i{imported} into the @i{package} being defined.
In no case are @i{symbols} created in any @i{package}
other than the one being defined.

@item @t{:export}  
The @i{symbols} named by
the argument @i{symbol-names}  are found 
or created in the @i{package} being defined
and @i{exported}.
The @t{:export} option interacts
with the @t{:use} option, since inherited @i{symbols} 
        can be used rather than new ones created.
The @t{:export} option interacts
        with the 
@t{:import-from} and @t{:shadowing-import-from} options, since 
	@i{imported} 
symbols can be used rather than new ones created.
If an argument to the @t{:export} option is @i{accessible} as
an (inherited) @i{internal symbol} via @b{use-package}, that the
@i{symbol} named by @i{symbol-name}
is first @i{imported} into the @i{package} being
defined, and is then @i{exported} from that @i{package}.

@item @t{:intern}  
The @i{symbols} named by the argument @i{symbol-names} 
are found or created in the @i{package} being defined.
The @t{:intern} option interacts with the 
@t{:use} option, since inherited @i{symbols} 
can be used rather than new ones created.  

@item @t{:size}  
The argument to the @t{:size} option
declares the approximate number of @i{symbols} expected in the 
@i{package}.
        This is an efficiency hint only and might be ignored by an
implementation.
@end table

The order in which the options appear in a 
@b{defpackage} form is irrelevant.
The order in which they are executed is as follows:
@table @asis

@item 1.  
@t{:shadow} and @t{:shadowing-import-from}.
@item 2.  
@t{:use}. 
@item 3.  
@t{:import-from} and @t{:intern}.
@item 4.  
@t{:export}.
@end table

Shadows are established first, since they might  be necessary to block 
spurious name conflicts when the @t{:use} 
option is processed. The @t{:use} option is executed
next so that @t{:intern} and @t{:export} options can refer to normally 
inherited @i{symbols}.  
The @t{:export} option is executed last so that it can refer to 
@i{symbols} created by any of the other options; in 
particular, @i{shadowing symbols} and 
@i{imported} @i{symbols} can be made external.  

If a {defpackage} @i{form} appears as a @i{top level form},
all of the actions normally performed by this @i{macro} 
at load time must also be performed at compile time.

@subsubheading  Examples::

@example
 (defpackage "MY-PACKAGE"
   (:nicknames "MYPKG" "MY-PKG")
   (:use "COMMON-LISP")
   (:shadow "CAR" "CDR")
   (:shadowing-import-from "VENDOR-COMMON-LISP"  "CONS")
   (:import-from "VENDOR-COMMON-LISP"  "GC")
   (:export "EQ" "CONS" "FROBOLA")
   )

 (defpackage my-package
   (:nicknames mypkg :MY-PKG)  ; remember Common Lisp conventions for case
   (:use common-lisp)          ; conversion on symbols
   (:shadow CAR :cdr #:cons)                              
   (:export "CONS")            ; this is the shadowed one.
   )
@end example

@subsubheading  Affected By::

Existing @i{packages}.

@subsubheading  Exceptional Situations::

If one of the supplied @t{:nicknames} already
refers to an existing @i{package}, 
an error of @i{type} @b{package-error} is signaled.

An error of @i{type} @b{program-error} should be signaled if @t{:size} or @t{:documentation}
appears more than once.

Since @i{implementations} might allow extended @i{options}
an error of @i{type} @b{program-error} should be signaled
if an @i{option} is present that is not 
actually supported in the host @i{implementation}.

The collection of @i{symbol-name} arguments given to the options 
      @t{:shadow}, @t{:intern}, 
@t{:import-from}, and @t{:shadowing-import-from} must 
      all be disjoint; additionally, the @i{symbol-name} arguments given to 
      @t{:export} and @t{:intern} 
must be disjoint. 
Disjoint in this context is defined as no two of the @i{symbol-names}
being @b{string=} with each other. If either condition is 
      violated, an error of @i{type} @b{program-error} should be signaled.

For the @t{:shadowing-import-from} and @t{:import-from} options,
a @i{correctable} @i{error} of @i{type} @b{package-error}
        is signaled if no @i{symbol} is 
@i{accessible} in the @i{package} named by
        @i{package-name} for one of the argument @i{symbol-names}.

Name conflict errors are handled by the underlying calls to 
@b{make-package}, @b{use-package}, @b{import}, and 
@b{export}. See @ref{Package Concepts}.

@subsubheading  See Also::

@ref{documentation; (setf documentation)}
,
@ref{Package Concepts},
@ref{Compilation}

@subsubheading  Notes::

The @t{:intern} option is useful if an @t{:import-from} or a 
@t{:shadowing-import-from} option in a subsequent call to @b{defpackage} 
(for some other @i{package}) expects to find
these @i{symbols} @i{accessible} but not necessarily external.

It is recommended that the entire @i{package} definition is put
in a single place, and that all the @i{package} definitions of a
program are in a single file.  This file can be @i{loaded} before
@i{loading} or compiling anything else that depends on those 
@i{packages}. Such a file can be read in the @t{COMMON-LISP-USER} @i{package},
avoiding any initial state issues.

@b{defpackage} cannot be used to create two ``mutually
recursive'' packages, such as:

@example
 (defpackage my-package
   (:use common-lisp your-package)    ;requires your-package to exist first
   (:export "MY-FUN"))                
 (defpackage your-package
   (:use common-lisp)
   (:import-from my-package "MY-FUN") ;requires my-package to exist first
   (:export "MY-FUN"))
@end example

However, nothing prevents the user from using the 
@i{package}-affecting functions 
such as @b{use-package}, 
@b{import}, and @b{export} to establish such links
after a more standard use of @b{defpackage}.

The macroexpansion of @b{defpackage} 
could usefully canonicalize the names
into @i{strings}, 
so that even if a source file has random @i{symbols} in the
@b{defpackage} form, the compiled file would only contain 
@i{strings}.

Frequently additional @i{implementation-dependent} options take the
form of a @i{keyword} standing by itself as an abbreviation for a list
@t{(keyword T)}; this syntax should be properly reported as an unrecognized
option in implementations that do not support it.

@node do-symbols, intern, defpackage, Packages Dictionary
@subsection do-symbols, do-external-symbols, do-all-symbols                     [Macro]

@code{do-symbols}  @i{@r{(}var @r{[}package @r{[}result-form@r{]}@r{]}@r{)}
			 @{@i{declaration}@}{*}
			       @{tag | statement@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@code{do-external-symbols}  @i{@r{(}var @r{[}package @r{[}result-form@r{]}@r{]}@r{)}
			 @{@i{declaration}@}{*}
			       @{tag | statement@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@code{do-all-symbols}  @i{@r{(}var @r{[}result-form@r{]}@r{)}
			 @{@i{declaration}@}{*}
		    	       @{tag | statement@}{*}}@*
   @result{}  @i{@{@i{result}@}{*}}

@subsubheading  Arguments and Values:: 

@i{var}---a @i{variable} @i{name}; not evaluated.

@i{package}---a @i{package designator}; evaluated.

  The default in @b{do-symbols} and @b{do-external-symbols} is the @i{current package}.

@i{result-form}---a @i{form}; evaluated as described below.
 The default is @b{nil}.

@i{declaration}---a @b{declare} @i{expression}; not evaluated.

@i{tag}---a @i{go tag}; not evaluated.

@i{statement}---a @i{compound form}; evaluated as described below.

@i{results}---the @i{values} returned by the @i{result-form} 
            if a @i{normal return} occurs,
   or else, if an @i{explicit return} occurs, the @i{values} that were transferred.

@subsubheading  Description::

@b{do-symbols},
@b{do-external-symbols}, and
@b{do-all-symbols} iterate over the @i{symbols} 
of @i{packages}.
For each @i{symbol} in the set of @i{packages} chosen,
the @i{var} is bound to the @i{symbol},
and the @i{statements} in the body are executed.  
When all the @i{symbols} have been processed,
@i{result-form} is evaluated and returned as the value of the macro.  

@b{do-symbols} iterates 
over the @i{symbols} @i{accessible} in
@i{package}.

@i{Statements} may execute more than once for @i{symbols} 
that are inherited from multiple @i{packages}.

@b{do-all-symbols} iterates on every @i{registered package}. 
@b{do-all-symbols} will not process every @i{symbol}
whatsoever, because a @i{symbol} not @i{accessible} in any
@i{registered package} will not be processed.
@b{do-all-symbols} may cause a @i{symbol} that is @i{present} in
several @i{packages} to be processed more than once.

@b{do-external-symbols} iterates on the external symbols of @i{package}.

When @i{result-form} is evaluated, @i{var} is bound and has the value @b{nil}.

An @i{implicit block} named @b{nil} surrounds the entire @b{do-symbols},
@b{do-external-symbols}, or @b{do-all-symbols} @i{form}.

@b{return} or @b{return-from} may be used to terminate the 
iteration prematurely.  

If execution of the body affects which @i{symbols} 
are contained in the set of @i{packages} over which iteration
is occurring, other than to
remove the @i{symbol} 
currently the value of @i{var} by using @b{unintern},
the consequences are undefined.

For each of these macros, the 
@i{scope} of the name binding does not include any
initial value form, but the optional result forms are included.

Any @i{tag} in the body is treated as with @b{tagbody}.

@subsubheading  Examples::

@example
 (make-package 'temp :use nil) @result{}  #<PACKAGE "TEMP">
 (intern "SHY" 'temp) @result{}  TEMP::SHY, NIL ;SHY will be an internal symbol
                                         ;in the package TEMP
 (export (intern "BOLD" 'temp) 'temp)  @result{}  T  ;BOLD will be external  
 (let ((lst ()))
   (do-symbols (s (find-package 'temp)) (push s lst))
   lst)
@result{}  (TEMP::SHY TEMP:BOLD)
@i{OR}@result{} (TEMP:BOLD TEMP::SHY)
 (let ((lst ()))
   (do-external-symbols (s (find-package 'temp) lst) (push s lst))
   lst) 
@result{}  (TEMP:BOLD)
 (let ((lst ()))                                                     
   (do-all-symbols (s lst)
     (when (eq (find-package 'temp) (symbol-package s)) (push s lst)))
   lst)
@result{}  (TEMP::SHY TEMP:BOLD)
@i{OR}@result{} (TEMP:BOLD TEMP::SHY)
@end example

@subsubheading  See Also::

@ref{intern}
,
@ref{export}
,

@ref{Traversal Rules and Side Effects}

@node intern, package-name, do-symbols, Packages Dictionary
@subsection intern                                                           [Function]

@code{intern}  @i{string {&optional} package} @result{}  @i{symbol, status}

@subsubheading  Arguments and Values::

@i{string}---a @i{string}.

@i{package}---a @i{package designator}.

  The default is the @i{current package}.

@i{symbol}---a @i{symbol}.

@i{status}---one of @t{:inherited}, @t{:external}, @t{:internal}, or @b{nil}.

@subsubheading  Description::

@b{intern} enters a @i{symbol} named @i{string} into @i{package}.
If a @i{symbol} whose name is the same as @i{string} 
is already @i{accessible} in @i{package}, it is returned.
If no such @i{symbol} is @i{accessible} in @i{package}, 
a new @i{symbol} with the given name is created 
and entered into @i{package} as an @i{internal symbol},
or as an @i{external symbol} if the @i{package} is the @t{KEYWORD} @i{package}; 
@i{package} becomes the @i{home package} of the created @i{symbol}.

The first value returned by @b{intern}, @i{symbol},
is the @i{symbol} that was found or
created.  
The meaning of the @i{secondary value}, @i{status}, is as follows:
@table @asis

@item @t{:internal}  
The @i{symbol} was found 
and is
@i{present} in @i{package} as an @i{internal symbol}.

@item @t{:external}  
The @i{symbol} was found
and is
@i{present} as an @i{external symbol}.

@item @t{:inherited}  
The @i{symbol} was found
and is inherited via @b{use-package} 
(which implies that the @i{symbol} is internal).

@item @b{nil}  
No pre-existing @i{symbol} was found,
so one was created.

It is @i{implementation-dependent} whether the @i{string} 
that becomes the new @i{symbol}'s @i{name} is the given
@i{string} or a copy of it.  Once a @i{string}
has been given as the @i{string} @i{argument} to
@i{intern} in this situation where a new @i{symbol} is created,
the consequences are undefined if a
subsequent attempt is made to alter that @i{string}.

@end table

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (intern "Never-Before") @result{}  |Never-Before|, NIL
 (intern "Never-Before") @result{}  |Never-Before|, :INTERNAL 
 (intern "NEVER-BEFORE" "KEYWORD") @result{}  :NEVER-BEFORE, NIL
 (intern "NEVER-BEFORE" "KEYWORD") @result{}  :NEVER-BEFORE, :EXTERNAL
@end example

@subsubheading  See Also::

@ref{find-symbol}
,
@ref{read; read-preserving-whitespace}
,
@b{symbol},
@ref{unintern}
,
@ref{Symbols as Tokens}

@subsubheading  Notes::

@b{intern} does not need to do any name conflict checking 
because it never creates a new @i{symbol} 
if there is already an @i{accessible} @i{symbol} with the name given.

@node package-name, package-nicknames, intern, Packages Dictionary
@subsection package-name                                                     [Function]

@code{package-name}  @i{package} @result{}  @i{name}

@subsubheading  Arguments and Values::

@i{package}---a @i{package designator}.

@i{name}---a @i{string} 

or @b{nil}.

@subsubheading  Description::

@b{package-name} returns the @i{string} that names @i{package},

or @b{nil} if the @i{package} @i{designator}
is a @i{package} @i{object} that has no name (see the @i{function} @b{delete-package}).

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 (package-name *package*) @result{}  "COMMON-LISP-USER"
 (package-name (symbol-package :test)) @result{}  "KEYWORD"
 (package-name (find-package 'common-lisp)) @result{}  "COMMON-LISP"
@end example

@example
 (defvar *foo-package* (make-package "FOO"))
 (rename-package "FOO" "FOO0")
 (package-name *foo-package*) @result{}  "FOO0"
@end example

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{package} is not a @i{package designator}.

@node package-nicknames, package-shadowing-symbols, package-name, Packages Dictionary
@subsection package-nicknames                                                [Function]

@code{package-nicknames}  @i{package} @result{}  @i{nicknames}

@subsubheading  Arguments and Values:: 

@i{package}---a @i{package designator}.

@i{nicknames}---a @i{list} of @i{strings}.

@subsubheading  Description::

Returns the @i{list} of nickname @i{strings}
for @i{package}, not including the name of @i{package}.

@subsubheading  Examples::

@example
 (package-nicknames (make-package 'temporary
                                   :nicknames '("TEMP" "temp")))
@result{}  ("temp" "TEMP") 
@end example

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{package} is not a @i{package designator}.

@node package-shadowing-symbols, package-use-list, package-nicknames, Packages Dictionary
@subsection package-shadowing-symbols                                        [Function]

@code{package-shadowing-symbols}  @i{package} @result{}  @i{symbols}

@subsubheading  Arguments and Values:: 

@i{package}---a @i{package designator}.

@i{symbols}---a @i{list} of @i{symbols}.

@subsubheading  Description::

Returns a @i{list} of @i{symbols} that have been declared 
as @i{shadowing symbols} in @i{package} by @b{shadow} 
or @b{shadowing-import} (or the equivalent @b{defpackage} options).
All @i{symbols} on this @i{list} are @i{present} in @i{package}.

@subsubheading  Examples::

@example
 (package-shadowing-symbols (make-package 'temp)) @result{}  ()
 (shadow 'cdr 'temp) @result{}  T
 (package-shadowing-symbols 'temp) @result{}  (TEMP::CDR)
 (intern "PILL" 'temp) @result{}  TEMP::PILL, NIL
 (shadowing-import 'pill 'temp) @result{}  T
 (package-shadowing-symbols 'temp) @result{}  (PILL TEMP::CDR)
@end example

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{package} is not a @i{package designator}.

@subsubheading  See Also::

@ref{shadow}
,
@ref{shadowing-import}

@subsubheading  Notes::

Whether the list of @i{symbols} is @i{fresh} is @i{implementation-dependent}.

@node package-use-list, package-used-by-list, package-shadowing-symbols, Packages Dictionary
@subsection package-use-list                                                 [Function]

@code{package-use-list}  @i{package} @result{}  @i{use-list}

@subsubheading  Arguments and Values:: 

@i{package}---a @i{package designator}.

@i{use-list}---a @i{list} of @i{package} @i{objects}.

@subsubheading  Description::

Returns a @i{list} of other @i{packages} used by @i{package}.

@subsubheading  Examples::

@example
 (package-use-list (make-package 'temp)) @result{}  (#<PACKAGE "COMMON-LISP">)
 (use-package 'common-lisp-user 'temp) @result{}  T
 (package-use-list 'temp) @result{}  (#<PACKAGE "COMMON-LISP"> #<PACKAGE "COMMON-LISP-USER">)
@end example

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{package} is not a @i{package designator}.

@subsubheading  See Also::

@ref{use-package}
,
@ref{unuse-package}

@node package-used-by-list, packagep, package-use-list, Packages Dictionary
@subsection package-used-by-list                                             [Function]

@code{package-used-by-list}  @i{package} @result{}  @i{used-by-list}

@subsubheading  Arguments and Values:: 

@i{package}---a @i{package designator}.

@i{used-by-list}---a @i{list} of @i{package} @i{objects}.

@subsubheading  Description::

@b{package-used-by-list} returns a @i{list} 
of other @i{packages} that use @i{package}.

@subsubheading  Examples::

@example
 (package-used-by-list (make-package 'temp)) @result{}  ()
 (make-package 'trash :use '(temp)) @result{}  #<PACKAGE "TRASH">
 (package-used-by-list 'temp) @result{}  (#<PACKAGE "TRASH">)
@end example

@subsubheading  Exceptional Situations::

Should signal an error of @i{type} @b{type-error}
			      if @i{package} is not a @i{package}.

@subsubheading  See Also::

@ref{use-package}
,
@ref{unuse-package}

@node packagep, *package*, package-used-by-list, Packages Dictionary
@subsection packagep                                                         [Function]

@code{packagep}  @i{object} @result{}  @i{generalized-boolean}

@subsubheading  Arguments and Values::

@i{object}---an @i{object}.

@i{generalized-boolean}---a @i{generalized boolean}.

@subsubheading  Description::

Returns @i{true} if @i{object} is of @i{type} @b{package};
otherwise, returns @i{false}.

@subsubheading  Examples::
@example
 (packagep *package*) @result{}  @i{true} 
 (packagep 'common-lisp) @result{}  @i{false} 
 (packagep (find-package 'common-lisp)) @result{}  @i{true} 
@end example

@subsubheading  Notes::

@example
 (packagep @i{object}) @equiv{} (typep @i{object} 'package)
@end example

@node *package*, package-error, packagep, Packages Dictionary
@subsection *package*                                                        [Variable]

@subsubheading  Value Type::

a @i{package} @i{object}.

@subsubheading  Initial Value::

the @t{COMMON-LISP-USER} @i{package}.

@subsubheading  Description::

Whatever @i{package} @i{object} is currently 
the @i{value} of @b{*package*} is referred to as the @i{current package}.

@subsubheading  Examples::

@example
 (in-package "COMMON-LISP-USER") @result{}  #<PACKAGE "COMMON-LISP-USER">
 *package* @result{}  #<PACKAGE "COMMON-LISP-USER">
 (make-package "SAMPLE-PACKAGE" :use '("COMMON-LISP"))
@result{}  #<PACKAGE "SAMPLE-PACKAGE">
 (list 
   (symbol-package
     (let ((*package* (find-package 'sample-package)))
       (setq *some-symbol* (read-from-string "just-testing"))))
   *package*)
@result{}  (#<PACKAGE "SAMPLE-PACKAGE"> #<PACKAGE "COMMON-LISP-USER">)
 (list (symbol-package (read-from-string "just-testing"))
       *package*)
@result{}  (#<PACKAGE "COMMON-LISP-USER"> #<PACKAGE "COMMON-LISP-USER">)
 (eq 'foo (intern "FOO")) @result{}  @i{true}
 (eq 'foo (let ((*package* (find-package 'sample-package)))
            (intern "FOO")))
@result{}  @i{false}
@end example

@subsubheading  Affected By::

@b{load},
@b{compile-file},
@b{in-package}

@subsubheading  See Also::

@ref{compile-file}
,
@ref{in-package}
,
@ref{load}
,
@ref{package}

@node package-error, package-error-package, *package*, Packages Dictionary
@subsection package-error                                              [Condition Type]

@subsubheading  Class Precedence List::
@b{package-error},
@b{error},
@b{serious-condition},
@b{condition},
@b{t}

@subsubheading  Description::

The @i{type} @b{package-error} consists of @i{error} @i{conditions}
related to operations on @i{packages}.
The offending @i{package} (or @i{package} @i{name})
is initialized by the @t{:package} initialization argument to @b{make-condition}, 
and is @i{accessed} by the @i{function} @b{package-error-package}.

@subsubheading  See Also::

@ref{package-error-package}
,
@ref{Conditions}

@node package-error-package,  , package-error, Packages Dictionary
@subsection package-error-package                                            [Function]

@code{package-error-package}  @i{condition} @result{}  @i{package}

@subsubheading  Arguments and Values::

@i{condition}---a @i{condition} of @i{type} @b{package-error}.

@i{package}---a @i{package designator}.

@subsubheading  Description::

Returns a @i{designator} for the offending @i{package}
in the @i{situation} represented by the @i{condition}.

@subsubheading  Examples::

@example
 (package-error-package 
   (make-condition 'package-error
     :package (find-package "COMMON-LISP")))
@result{}  #<Package "COMMON-LISP">
@end example

@subsubheading  See Also::

@b{package-error}

@c end of including dict-packages

@c %**end of chapter