option ::= (
:nicknames
nickname*
)*
| (:documentation
string) | (:use
package-name*
)*
| (:shadow
symbol-name*
)*
| (:shadowing-import-from
package-name symbol-name*
)*
| (:import-from
package-name symbol-name*
)*
| (:export
symbol-name*
)*
| (:intern
symbol-name*
)*
| (:size
integer)
defpackage creates a package as specified and returns the package.
If defined-package-name already refers to an existing 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 package, the consequences are undefined; an implementation might choose to modify the existing package to reflect the new definition. If defined-package-name is a symbol, its name is used.
The standard options
are described below.
The arguments to :nicknames
set the package's nicknames to the supplied names.
The argument to :documentation
specifies a documentation string; it is attached as a documentation string to the package. At most one :documentation
option can appear in a single defpackage form.
The arguments to :use
set the packages that the package named by package-name will inherit from. If :use
is not supplied, it defaults to the same implementation-dependent value as the :use
keyword argument to make-package.
The arguments to :shadow
, symbol-names, name symbols that are to be created in the package being defined. These symbols are added to the list of shadowing symbols effectively as if by shadow.
The symbols named by the argument symbol-names are found (involving a lookup as if by find-symbol) in the specified package-name. The resulting symbols are imported into the package being defined, and placed on the shadowing symbols list as if by shadowing-import. In no case are symbols created in any package other than the one being defined.
The symbols named by the argument symbol-names are found in the package named by package-name and they are imported into the package being defined. In no case are symbols created in any package other than the one being defined.
The symbols named by the argument symbol-names are found or created in the package being defined and exported. The :export
option interacts with the :use
option, since inherited symbols can be used rather than new ones created. The :export
option interacts with the :import-from
and :shadowing-import-from
options, since imported symbols can be used rather than new ones created. If an argument to the :export
option is accessible as an (inherited) internal symbol via use-package, that the symbol named by symbol-name is first imported into the package being defined, and is then exported from that package.
The symbols named by the argument symbol-names are found or created in the package being defined. The :intern
option interacts with the :use
option, since inherited symbols can be used rather than new ones created.
The argument to the :size
option declares the approximate number of symbols expected in the package. This is an efficiency hint only and might be ignored by an implementation.
The order in which the options appear in a defpackage form is irrelevant. The order in which they are executed is as follows:
:shadow
and :shadowing-import-from
. :use
. :import-from
and :intern
. :export
.
Shadows are established first, since they might be necessary to block spurious name conflicts when the :use
option is processed. The :use
option is executed next so that :intern
and :export
options can refer to normally inherited symbols. The :export
option is executed last so that it can refer to symbols created by any of the other options; in particular, shadowing symbols and imported symbols can be made external.
If a defpackage form appears as a top level form, all of the actions normally performed by this macro at load time must also be performed at compile time.
(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"))
→#<PACKAGE "MY-PACKAGE">
(defpackage my-package-2 (:nicknames mypkg :my-pkg) ; remember Common Lisp conventions for case (:use common-lisp) ; conversion on symbols (:shadow CAR :cdr #:cons) (:export "CONS"))
→#<PACKAGE "MY-PACKAGE-2">
In the above example, the symbol cons
exported from package my-package-2
is the shadowed one, not the one refering to the function cons.
Existing packages.
If one of the supplied :nicknames
already refers to an existing package, an error of type package-error is signaled.
An error of type program-error should be signaled if :size
or :documentation
appears more than once.
Since implementations might allow extended options
an error of type program-error should be signaled if an option
is present that is not actually supported in the host implementation.
The collection of symbol-name arguments given to the options :shadow
, :intern
, :import-from
, and :shadowing-import-from
must all be disjoint; additionally, the symbol-name arguments given to :export
and :intern
must be disjoint. Disjoint in this context is defined as no two of the symbol-names being string= with each other. If either condition is violated, an error of type program-error should be signaled.
For the :shadowing-import-from
and :import-from
options, a correctable error of type package-error is signaled if no symbol is accessible in the package named by package-name for one of the argument symbol-names.
Name conflict errors are handled by the underlying calls to make-package, use-package, import, and export. See section {\secref\PackageConcepts}.
The :intern
option is useful if an :import-from
or a :shadowing-import-from
option in a subsequent call to defpackage (for some other package) expects to find these symbols accessible but not necessarily external.
It is recommended that the entire package definition is put in a single place, and that all the package definitions of a program are in a single file. This file can be loaded before loading or compiling anything else that depends on those packages. Such a file can be read in the common-lisp-user
package, avoiding any initial state issues.
defpackage cannot be used to create two "mutually recursive" packages, such as:
(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"))
However, nothing prevents the user from using the package-affecting functions such as use-package, import, and export to establish such links after a more standard use of defpackage.
The macroexpansion of defpackage could usefully canonicalize the names into strings, so that even if a source file has random symbols in the defpackage form, the compiled file would only contain strings.
Frequently additional implementation-dependent options take the form of a keyword standing by itself as an abbreviation for a list (keyword T); this syntax should be properly reported as an unrecognized option in implementations that do not support it.
\issue{DEFPACKAGE:ADDITION} \issue{DOCUMENTATION-FUNCTION-BUGS:FIX} \issue{PACKAGE-FUNCTION-CONSISTENCY:MORE-PERMISSIVE} \issue{DOCUMENTATION-FUNCTION-BUGS:FIX} \issue{MAKE-PACKAGE-USE-DEFAULT:IMPLEMENTATION-DEPENDENT} \issue{COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY}