@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{} # (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{} # (find-package "COMMON-LISP-USER") @result{} # (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{} (#) @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{} # (rename-package 'temp 'ephemeral) @result{} # (package-nicknames (find-package 'ephemeral)) @result{} () (find-package 'temporary) @result{} NIL (rename-package 'ephemeral 'temporary '(temp fleeting)) @result{} # (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{} # (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{} # (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{} # (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{} # (symbol-package *bar-symbol*) @result{} # (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-use-list *baz-package*) @result{} (#) (package-used-by-list *foo-package*) @result{} (#) (package-used-by-list *bar-package*) @result{} (#) (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{} # (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{} # (make-package "OWNER" :use '("temp")) @result{} # (package-used-by-list 'temp) @result{} (#) (package-use-list 'owner) @result{} (#) @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{} # (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{} # (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{} # (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{} # (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{} (#) (use-package 'trash 'temp) @result{} T (package-use-list 'temp) @result{} (# #) (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{} # (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{} # (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-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{} (#) (use-package 'common-lisp-user 'temp) @result{} T (package-use-list 'temp) @result{} (# #) @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-used-by-list 'temp) @result{} (#) @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* @result{} # (make-package "SAMPLE-PACKAGE" :use '("COMMON-LISP")) @result{} # (list (symbol-package (let ((*package* (find-package 'sample-package))) (setq *some-symbol* (read-from-string "just-testing")))) *package*) @result{} (# #) (list (symbol-package (read-from-string "just-testing")) *package*) @result{} (# #) (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{} # @end example @subsubheading See Also:: @b{package-error} @c end of including dict-packages @c %**end of chapter