130 lines
18 KiB
HTML
130 lines
18 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Macro DEFPACKAGE</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="f_use_pk.htm">
|
|
<LINK REL=UP HREF="c_packag.htm">
|
|
<LINK REL=NEXT HREF="m_do_sym.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="f_use_pk.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_packag.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="m_do_sym.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="defpackage"><I>Macro</I> <B>DEFPACKAGE</B></A> <P>
|
|
<P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>defpackage</B> <I>defined-package-name [[<I>option</I>]]</I> => <I>package</I><P>
|
|
<P>
|
|
<PRE>
|
|
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 <A REL=DEFINITION HREF="26_glo_i.htm#integer">integer</A>)
|
|
</PRE>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>defined-package-name</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#string_designator"><I>string designator</I></A>. <P>
|
|
<I>package-name</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#package_designator"><I>package designator</I></A>. <P>
|
|
<I>nickname</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#string_designator"><I>string designator</I></A>. <P>
|
|
<I>symbol-name</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#string_designator"><I>string designator</I></A>. <P>
|
|
<I>package</I>---the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> named <I>package-name</I>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> creates a <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> as specified and returns the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>. <P>
|
|
If <I>defined-package-name</I> already refers to an existing <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>, the name-to-package mapping for that name is not changed. If the new definition is at variance with the current state of that <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>, the consequences are undefined; an implementation might choose to modify the existing <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> to reflect the new definition. If <I>defined-package-name</I> is a <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A>, its <A REL=DEFINITION HREF="26_glo_n.htm#name"><I>name</I></A> is used. <P>
|
|
The standard <I>options</I> are described below. <P>
|
|
<P><DL><DT><TT>:nicknames</TT> <P><DD>
|
|
The arguments to <TT>:nicknames</TT> set the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>'s nicknames to the supplied names. <P>
|
|
<DT><TT>:documentation</TT> <P><DD>
|
|
The argument to <TT>:documentation</TT> specifies a <A REL=DEFINITION HREF="26_glo_d.htm#documentation_string"><I>documentation string</I></A>; it is attached as a <A REL=DEFINITION HREF="26_glo_d.htm#documentation_string"><I>documentation string</I></A> to the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>. At most one <TT>:documentation</TT> option can appear in a single <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>. <P>
|
|
<DT><TT>:use</TT> <P><DD>
|
|
The arguments to <TT>:use</TT> set the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>packages</I></A> that the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> named by <I>package-name</I> will inherit from. If <TT>:use</TT> is not supplied, it defaults to the same <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A> value as the <TT>:use</TT> <A REL=DEFINITION HREF="26_glo_a.htm#argument"><I>argument</I></A> to <A REL=DEFINITION HREF="f_mk_pkg.htm#make-package"><B>make-package</B></A>. <P>
|
|
<DT><TT>:shadow</TT> <P><DD>
|
|
The arguments to <TT>:shadow</TT>, <I>symbol-names</I>, name <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> that are to be created in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined. These <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> are added to the list of shadowing <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> effectively as if by <A REL=DEFINITION HREF="f_shadow.htm#shadow"><B>shadow</B></A>. <P>
|
|
<DT><TT>:shadowing-import-from</TT> <P><DD>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> named by the argument <I>symbol-names</I> are found (involving a lookup as if by <A REL=DEFINITION HREF="f_find_s.htm#find-symbol"><B>find-symbol</B></A>) in the specified <I>package-name</I>. The resulting <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> are <I>imported</I> into the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined, and placed on the shadowing symbols list as if by <A REL=DEFINITION HREF="f_shdw_i.htm#shadowing-import"><B>shadowing-import</B></A>. In no case are <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> created in any <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> other than the one being defined. <P>
|
|
<DT><TT>:import-from</TT> <P><DD>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> named by the argument <I>symbol-names</I> are found in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> named by <I>package-name</I> and they are <I>imported</I> into the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined. In no case are <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> created in any <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> other than the one being defined. <P>
|
|
<DT><TT>:export</TT> <P><DD>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> named by the argument <I>symbol-names</I> are found or created in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined and <A REL=DEFINITION HREF="26_glo_e.htm#exported"><I>exported</I></A>. The <TT>:export</TT> option interacts with the <TT>:use</TT> option, since inherited <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> can be used rather than new ones created. The <TT>:export</TT> option interacts with the <TT>:import-from</TT> and <TT>:shadowing-import-from</TT> options, since <I>imported</I> symbols can be used rather than new ones created. If an argument to the <TT>:export</TT> option is <A REL=DEFINITION HREF="26_glo_a.htm#accessible"><I>accessible</I></A> as an (inherited) <A REL=DEFINITION HREF="26_glo_i.htm#internal_symbol"><I>internal symbol</I></A> via <A REL=DEFINITION HREF="f_use_pk.htm#use-package"><B>use-package</B></A>, that the <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A> named by <I>symbol-name</I> is first <I>imported</I> into the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined, and is then <A REL=DEFINITION HREF="26_glo_e.htm#exported"><I>exported</I></A> from that <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>. <P>
|
|
<DT><TT>:intern</TT> <P><DD>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> named by the argument <I>symbol-names</I> are found or created in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> being defined. The <TT>:intern</TT> option interacts with the <TT>:use</TT> option, since inherited <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> can be used rather than new ones created. <P>
|
|
<DT><TT>:size</TT> <P><DD>
|
|
The argument to the <TT>:size</TT> option declares the approximate number of <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> expected in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>. This is an efficiency hint only and might be ignored by an implementation. <P></DL><P>
|
|
The order in which the options appear in a <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> form is irrelevant. The order in which they are executed is as follows: <P><DL><DT>1. <TT>:shadow</TT> and <TT>:shadowing-import-from</TT>. <DD><DT>2. <TT>:use</TT>. <DD><DT>3. <TT>:import-from</TT> and <TT>:intern</TT>. <DD><DT>4. <TT>:export</TT>. <P><DD></DL>Shadows are established first, since they might be necessary to block spurious name conflicts when the <TT>:use</TT> option is processed. The <TT>:use</TT> option is executed next so that <TT>:intern</TT> and <TT>:export</TT> options can refer to normally inherited <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A>. The <TT>:export</TT> option is executed last so that it can refer to <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> created by any of the other options; in particular, <A REL=DEFINITION HREF="26_glo_s.htm#shadowing_symbol"><I>shadowing symbols</I></A> and <I>imported</I> <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> can be made external. <P>
|
|
If a defpackage <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> appears as a <A REL=DEFINITION HREF="26_glo_t.htm#top_level_form"><I>top level form</I></A>, all of the actions normally performed by this <A REL=DEFINITION HREF="26_glo_m.htm#macro"><I>macro</I></A> at load time must also be performed at compile time. <P>
|
|
<P><B>Examples:</B><P>
|
|
<P>
|
|
<PRE>
|
|
(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.
|
|
)
|
|
</PRE>
|
|
</TT> <P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
Existing <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>packages</I></A>. <P>
|
|
<P><B>Exceptional Situations:</B><P>
|
|
<P>
|
|
If one of the supplied <TT>:nicknames</TT> already refers to an existing <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>, an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_pkg_er.htm#package-error"><B>package-error</B></A> is signaled. <P>
|
|
An error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_progra.htm#program-error"><B>program-error</B></A> should be signaled if <TT>:size</TT> or <TT>:documentation</TT> appears more than once. <P>
|
|
Since <A REL=DEFINITION HREF="26_glo_i.htm#implementation"><I>implementations</I></A> might allow extended <I>options</I> an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_progra.htm#program-error"><B>program-error</B></A> should be signaled if an <I>option</I> is present that is not actually supported in the host <A REL=DEFINITION HREF="26_glo_i.htm#implementation"><I>implementation</I></A>. <P>
|
|
The collection of <I>symbol-name</I> arguments given to the options <TT>:shadow</TT>, <TT>:intern</TT>, <TT>:import-from</TT>, and <TT>:shadowing-import-from</TT> must all be disjoint; additionally, the <I>symbol-name</I> arguments given to <TT>:export</TT> and <TT>:intern</TT> must be disjoint. Disjoint in this context is defined as no two of the <I>symbol-names</I> being <A REL=DEFINITION HREF="f_stgeq_.htm#stringEQ"><B>string=</B></A> with each other. If either condition is violated, an error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_progra.htm#program-error"><B>program-error</B></A> should be signaled. <P>
|
|
For the <TT>:shadowing-import-from</TT> and <TT>:import-from</TT> options, a <A REL=DEFINITION HREF="26_glo_c.htm#correctable"><I>correctable</I></A> <A REL=DEFINITION HREF="26_glo_e.htm#error"><I>error</I></A> of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_pkg_er.htm#package-error"><B>package-error</B></A> is signaled if no <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbol</I></A> is <A REL=DEFINITION HREF="26_glo_a.htm#accessible"><I>accessible</I></A> in the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> named by <I>package-name</I> for one of the argument <I>symbol-names</I>. <P>
|
|
Name conflict errors are handled by the underlying calls to <A REL=DEFINITION HREF="f_mk_pkg.htm#make-package"><B>make-package</B></A>, <A REL=DEFINITION HREF="f_use_pk.htm#use-package"><B>use-package</B></A>, <A REL=DEFINITION HREF="f_import.htm#import"><B>import</B></A>, and <A REL=DEFINITION HREF="f_export.htm#export"><B>export</B></A>. See <A REL=CHILD HREF="11_a.htm">Section 11.1 (Package Concepts)</A>. <P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="f_docume.htm#documentation"><B>documentation</B></A>, <A REL=CHILD HREF="11_a.htm">Section 11.1 (Package Concepts)</A>, <A REL=CHILD HREF="03_b.htm">Section 3.2 (Compilation)</A> <P>
|
|
<P><B>Notes:</B><P>
|
|
<P>
|
|
The <TT>:intern</TT> option is useful if an <TT>:import-from</TT> or a <TT>:shadowing-import-from</TT> option in a subsequent call to <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> (for some other <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>) expects to find these <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> <A REL=DEFINITION HREF="26_glo_a.htm#accessible"><I>accessible</I></A> but not necessarily external. <P>
|
|
It is recommended that the entire <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> definition is put in a single place, and that all the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A> definitions of a program are in a single file. This file can be <I>loaded</I> before <I>loading</I> or compiling anything else that depends on those <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>packages</I></A>. Such a file can be read in the <TT>COMMON-LISP-USER</TT> package, avoiding any initial state issues. <P>
|
|
<A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> cannot be used to create two ``mutually recursive'' packages, such as: <P>
|
|
<PRE>
|
|
(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"))
|
|
</PRE>
|
|
</TT> <P>
|
|
However, nothing prevents the user from using the <A REL=DEFINITION HREF="26_glo_p.htm#package"><I>package</I></A>-affecting functions such as <A REL=DEFINITION HREF="f_use_pk.htm#use-package"><B>use-package</B></A>, <A REL=DEFINITION HREF="f_import.htm#import"><B>import</B></A>, and <A REL=DEFINITION HREF="f_export.htm#export"><B>export</B></A> to establish such links after a more standard use of <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A>. <P>
|
|
The macroexpansion of <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> could usefully canonicalize the names into <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>strings</I></A>, so that even if a source file has random <A REL=DEFINITION HREF="26_glo_s.htm#symbol"><I>symbols</I></A> in the <A REL=DEFINITION HREF="#defpackage"><B>defpackage</B></A> form, the compiled file would only contain <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>strings</I></A>. <P>
|
|
Frequently additional <A REL=DEFINITION HREF="26_glo_i.htm#implementation-dependent"><I>implementation-dependent</I></A> options take the form of a <A REL=DEFINITION HREF="26_glo_k.htm#keyword"><I>keyword</I></A> standing by itself as an abbreviation for a list <TT>(keyword T)</TT>; this syntax should be properly reported as an unrecognized option in implementations that do not support it. <P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss059.htm">COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY</A><LI> <A REL=CHILD HREF="../Issues/iss238.htm">MAKE-PACKAGE-USE-DEFAULT:IMPLEMENTATION-DEPENDENT</A><LI> <A REL=CHILD HREF="../Issues/iss254.htm">PACKAGE-FUNCTION-CONSISTENCY:MORE-PERMISSIVE</A><LI> <A REL=CHILD HREF="../Issues/iss135.htm">DOCUMENTATION-FUNCTION-BUGS:FIX</A><LI> <A REL=CHILD HREF="../Issues/iss108.htm">DEFPACKAGE:ADDITION</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|