Next: , Up: Package Concepts


11.1.1 Introduction to Packages

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

The next figure lists some defined names that are applicable to packages. Where an operator takes an argument that is either a symbol or a list of symbols, an argument of nil is treated as an empty list of symbols. Any package argument may be either a string, a symbol, or a package. If a symbol is supplied, its name will be used as the package name.

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

Figure 11.1: Some Defined Names related to Packages

11.1.1.1 Package Names and Nicknames

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

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

11.1.1.2 Symbols in a Package
11.1.1.2.1 Internal and External Symbols

The mappings in a package are divided into two classes, external and internal. The symbols targeted by these different mappings are called external symbols and internal symbols of the package. Within a package, a name refers to one symbol or to none; if it does refer to a symbol, then it is either external or internal in that package, but not both. External symbols are part of the package's public interface to other packages. Symbols become external symbols of a given package if they have been exported from that package.

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

11.1.1.2.2 Package Inheritance

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

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

11.1.1.2.3 Accessibility of Symbols in a Package

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

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

Symbols from one package can be made accessible in another package in two ways.

11.1.1.2.4 Locating a Symbol in a Package

When a symbol is to be located in a given package the following occurs:

11.1.1.2.5 Prevention of Name Conflicts in Packages

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

The following rules apply to name conflicts: