11.1 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.

Figure 11–1 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. 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. Symbols in a Package 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. 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. 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. Locating a Symbol in a Package

When a symbol is to be located in a given package the following occurs: 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:

11.1.2 Standardized Packages

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

Name Nicknames
Figure 11–2. Standardized Package Names The COMMON-LISP Package

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

The COMMON-LISP package has as external symbols those symbols enumerated in the figures in Section 1.9 (Symbols in the COMMON-LISP Package), and no others. These external symbols are present in the COMMON-LISP package but their home package need not be the COMMON-LISP package.

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

The COMMON-LISP package can have additional internal symbols. Constraints on the COMMON-LISP Package for Conforming Implementations

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

A conforming implementation must not place any property on an external symbol of the COMMON-LISP package using a property indicator that is either an external symbol of any standardized package or a symbol that is otherwise accessible in the COMMON-LISP-USER package. Constraints on the COMMON-LISP Package for Conforming Programs

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

  1. Binding or altering its value (lexically or dynamically). (Some exceptions are noted below.)

  2. Defining, undefining, or binding it as a function. (Some exceptions are noted below.)

  3. Defining, undefining, or binding it as a macro or compiler macro. (Some exceptions are noted below.)

  4. Defining it as a type specifier (via defstruct, defclass, deftype, define-condition).

  5. Defining it as a structure (via defstruct).

  6. Defining it as a declaration with a declaration proclamation.

  7. Defining it as a symbol macro.

  8. Altering its home package.

  9. Tracing it (via trace).

  10. Declaring or proclaiming it special (via declare, declaim, or proclaim).

  11. Declaring or proclaiming its type or ftype (via declare, declaim, or proclaim). (Some exceptions are noted below.)

  12. Removing it from the COMMON-LISP package.

  13. Defining a setf expander for it (via defsetf or define-setf-method).

  14. Defining, undefining, or binding its setf function name.

  15. Defining it as a method combination type (via define-method-combination).

  16. Using it as the class-name argument to setf of find-class.

  17. Binding it as a catch tag.

  18. Binding it as a restart name.

  19. Defining a method for a standardized generic function which is applicable when all of the arguments are direct instances of standardized classes. Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs

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

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

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

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

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

The COMMON-LISP-USER package is the current package when a Common Lisp system starts up. This package uses the COMMON-LISP package. The COMMON-LISP-USER package has the nickname CL-USER. The COMMON-LISP-USER package can have additional symbols interned within it; it can use other implementation-defined packages. The KEYWORD Package

The KEYWORD package contains symbols, called keywords1, that are typically used as special markers in programs and their associated data expressions1.

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

Symbols in the KEYWORD package are, by definition, of type keyword. Interning a Symbol in the KEYWORD Package

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

It is generally best to confine the use of 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 :on and :off.

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

Other, implementation-defined packages might be present in the initial Common Lisp environment.

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