1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>defpackage (ANSI and GNU Common Lisp Document)</title>
<meta name="description" content="defpackage (ANSI and GNU Common Lisp Document)">
<meta name="keywords" content="defpackage (ANSI and GNU Common Lisp Document)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html" rel="start" title="Top">
<link href="Packages-Dictionary.html" rel="up" title="Packages Dictionary">
<link href="do_002dsymbols.html" rel="next" title="do-symbols">
<link href="use_002dpackage.html" rel="prev" title="use-package">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<span id="defpackage"></span><div class="header">
<p>
Next: <a href="do_002dsymbols.html" accesskey="n" rel="next">do-symbols</a>, Previous: <a href="use_002dpackage.html" accesskey="p" rel="prev">use-package</a>, Up: <a href="Packages-Dictionary.html" accesskey="u" rel="up">Packages Dictionary</a> </p>
</div>
<hr>
<span id="defpackage-_005bMacro_005d"></span><h4 class="subsection">11.2.19 defpackage [Macro]</h4>
<p><code>defpackage</code> <i>defined-package-name [[!<i>option</i>]]</i> ⇒ <i>package</i>
</p>
<p><i>option</i> ::={<span class="roman">(</span><tt>:nicknames</tt> {<i>nickname</i>}*<span class="roman">)</span>}* | <!-- /@w -->
<span class="roman">(</span><tt>:documentation</tt> <i>string</i><span class="roman">)</span> | <!-- /@w -->
{<span class="roman">(</span><tt>:use</tt> {<i><span class="nolinebreak">package-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
{<span class="roman">(</span><tt>:shadow</tt> {!<i><span class="nolinebreak">symbol-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
{<span class="roman">(</span><tt><span class="nolinebreak">:shadowing-import-from</span></tt> <i><span class="nolinebreak">package-name</span></i> {!<i><span class="nolinebreak">symbol-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
{<span class="roman">(</span><tt><span class="nolinebreak">:import-from</span></tt> <i><span class="nolinebreak">package-name</span></i> {!<i><span class="nolinebreak">symbol-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
{<span class="roman">(</span><tt>:export</tt> {!<i><span class="nolinebreak">symbol-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
{<span class="roman">(</span><tt>:intern</tt> {!<i><span class="nolinebreak">symbol-name</span></i>}*<span class="roman">)</span>}* | <!-- /@w -->
<span class="roman">(</span><tt>:size</tt> <i>integer</i><span class="roman">)</span><!-- /@w -->
</p>
<p><i><span class="nolinebreak">symbol-name</span></i> ::=(<i>symbol</i> | <i>string</i>)<!-- /@w -->
</p>
<span id="Arguments-and-Values_003a_003a-191"></span><h4 class="subsubheading">Arguments and Values::</h4>
<p><i>defined-package-name</i>—a <i>string designator</i>.
</p>
<p><i>package-name</i>—a <i>package designator</i>.
</p>
<p><i>nickname</i>—a <i>string designator</i>.
</p>
<p><i>symbol-name</i>—a <i>string designator</i>.
</p>
<p><i>package</i>—the <i>package</i> named <i>package-name</i>.
</p>
<span id="Description_003a_003a-255"></span><h4 class="subsubheading">Description::</h4>
<p><b>defpackage</b> creates a <i>package</i> as specified and returns
the <i>package</i>.
</p>
<p>If <i>defined-package-name</i> already refers to an existing
<i>package</i>, 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</i>, the consequences are undefined; an implementation
might choose to modify the existing <i>package</i> to reflect the
new definition. If <i>defined-package-name</i> is a <i>symbol</i>,
its <i>name</i> is used.
</p>
<p>The standard <i>options</i> are described below.
</p>
<dl compact="compact">
<dt><tt>:nicknames</tt></dt>
<dd><p>The arguments to <tt>:nicknames</tt> set the <i>package</i>’s nicknames to the
supplied names.
</p>
</dd>
<dt><tt>:documentation</tt></dt>
<dd><p>The argument to <tt>:documentation</tt> specifies a <i>documentation string</i>;
it is attached as a <i>documentation string</i> to the <i>package</i>.
At most one <tt>:documentation</tt> option
can appear in a single <b>defpackage</b> <i>form</i>.
</p>
</dd>
<dt><tt>:use</tt></dt>
<dd><p>The arguments to <tt>:use</tt> set the <i>packages</i> that the <i>package</i>
named by <i>package-name</i>
will inherit from. If <tt>:use</tt> is not supplied,
</p>
<p>it defaults to the same <i>implementation-dependent</i> value as the <tt>:use</tt> <i>argument</i> to
<b>make-package</b>.
</p>
</dd>
<dt><tt>:shadow</tt></dt>
<dd><p>The arguments to <tt>:shadow</tt>, <i>symbol-names</i>, name <i>symbols</i>
that are to be created in the <i>package</i> being defined.
These <i>symbols</i> are added to the list of shadowing
<i>symbols</i> effectively as if by <b>shadow</b>.
</p>
</dd>
<dt><tt>:shadowing-import-from</tt></dt>
<dd><p>The <i>symbols</i> named by the argument <i>symbol-names</i>
are found (involving a lookup as if by <b>find-symbol</b>)
in the specified <i>package-name</i>. The resulting <i>symbols</i>
are <i>imported</i> into the <i>package</i> being defined, and
placed on the shadowing symbols list as if by <b>shadowing-import</b>.
In no case are <i>symbols</i> created in any <i>package</i>
other than the one being defined.
</p>
</dd>
<dt><tt>:import-from</tt></dt>
<dd><p>The <i>symbols</i> named by the argument <i>symbol-names</i>
are found in the <i>package</i> named by <i>package-name</i> and
they are <i>imported</i> into the <i>package</i> being defined.
In no case are <i>symbols</i> created in any <i>package</i>
other than the one being defined.
</p>
</dd>
<dt><tt>:export</tt></dt>
<dd><p>The <i>symbols</i> named by
the argument <i>symbol-names</i> are found
or created in the <i>package</i> being defined
and <i>exported</i>.
The <tt>:export</tt> option interacts
with the <tt>:use</tt> option, since inherited <i>symbols</i>
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 <i>accessible</i> as
an (inherited) <i>internal symbol</i> via <b>use-package</b>, that the
<i>symbol</i> named by <i>symbol-name</i>
is first <i>imported</i> into the <i>package</i> being
defined, and is then <i>exported</i> from that <i>package</i>.
</p>
</dd>
<dt><tt>:intern</tt></dt>
<dd><p>The <i>symbols</i> named by the argument <i>symbol-names</i>
are found or created in the <i>package</i> being defined.
The <tt>:intern</tt> option interacts with the
<tt>:use</tt> option, since inherited <i>symbols</i>
can be used rather than new ones created.
</p>
</dd>
<dt><tt>:size</tt></dt>
<dd><p>The argument to the <tt>:size</tt> option
declares the approximate number of <i>symbols</i> expected in the
<i>package</i>.
This is an efficiency hint only and might be ignored by an
implementation.
</p></dd>
</dl>
<p>The order in which the options appear in a
<b>defpackage</b> form is irrelevant.
The order in which they are executed is as follows:
</p><dl compact="compact">
<dt>1.</dt>
<dd><p><tt>:shadow</tt> and <tt>:shadowing-import-from</tt>.
</p></dd>
<dt>2.</dt>
<dd><p><tt>:use</tt>.
</p></dd>
<dt>3.</dt>
<dd><p><tt>:import-from</tt> and <tt>:intern</tt>.
</p></dd>
<dt>4.</dt>
<dd><p><tt>:export</tt>.
</p></dd>
</dl>
<p>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 <i>symbols</i>.
The <tt>:export</tt> option is executed last so that it can refer to
<i>symbols</i> created by any of the other options; in
particular, <i>shadowing symbols</i> and
<i>imported</i> <i>symbols</i> can be made external.
</p>
<p>If a <i>defpackage</i> <i>form</i> appears as a <i>top level form</i>,
all of the actions normally performed by this <i>macro</i>
at load time must also be performed at compile time.
</p>
<span id="Examples_003a_003a-173"></span><h4 class="subsubheading">Examples::</h4>
<div class="example">
<pre class="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.
)
</pre></div>
<span id="Affected-By_003a_003a-53"></span><h4 class="subsubheading">Affected By::</h4>
<p>Existing <i>packages</i>.
</p>
<span id="Exceptional-Situations_003a_003a-71"></span><h4 class="subsubheading">Exceptional Situations::</h4>
<p>If one of the supplied <tt>:nicknames</tt> already
refers to an existing <i>package</i>,
an error of <i>type</i> <b>package-error</b> is signaled.
</p>
<p>An error of <i>type</i> <b>program-error</b> should be signaled if <tt>:size</tt> or <tt>:documentation</tt>
appears more than once.
</p>
<p>Since <i>implementations</i> might allow extended <i>options</i>
an error of <i>type</i> <b>program-error</b> should be signaled
if an <i>option</i> is present that is not
actually supported in the host <i>implementation</i>.
</p>
<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 <b>string=</b> with each other. If either condition is
violated, an error of <i>type</i> <b>program-error</b> should be signaled.
</p>
<p>For the <tt>:shadowing-import-from</tt> and <tt>:import-from</tt> options,
a <i>correctable</i> <i>error</i> of <i>type</i> <b>package-error</b>
is signaled if no <i>symbol</i> is
<i>accessible</i> in the <i>package</i> named by
<i>package-name</i> for one of the argument <i>symbol-names</i>.
</p>
<p>Name conflict errors are handled by the underlying calls to
<b>make-package</b>, <b>use-package</b>, <b>import</b>, and
<b>export</b>. See <a href="Package-Concepts.html">Package Concepts</a>.
</p>
<span id="See-Also_003a_003a-227"></span><h4 class="subsubheading">See Also::</h4>
<p><a href="documentation.html">documentation</a>
,
<a href="Package-Concepts.html">Package Concepts</a>,
<a href="Compilation.html">Compilation</a>
</p>
<span id="Notes_003a_003a-132"></span><h4 class="subsubheading">Notes::</h4>
<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 <b>defpackage</b>
(for some other <i>package</i>) expects to find
these <i>symbols</i> <i>accessible</i> but not necessarily external.
</p>
<p>It is recommended that the entire <i>package</i> definition is put
in a single place, and that all the <i>package</i> 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
<i>packages</i>. Such a file can be read in the <tt>COMMON-LISP-USER</tt> <i>package</i>,
avoiding any initial state issues.
</p>
<p><b>defpackage</b> cannot be used to create two “mutually
recursive” packages, such as:
</p>
<div class="example">
<pre class="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"))
</pre></div>
<p>However, nothing prevents the user from using the
<i>package</i>-affecting functions
such as <b>use-package</b>,
<b>import</b>, and <b>export</b> to establish such links
after a more standard use of <b>defpackage</b>.
</p>
<p>The macroexpansion of <b>defpackage</b>
could usefully canonicalize the names
into <i>strings</i>,
so that even if a source file has random <i>symbols</i> in the
<b>defpackage</b> form, the compiled file would only contain
<i>strings</i>.
</p>
<p>Frequently additional <i>implementation-dependent</i> options take the
form of a <i>keyword</i> 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>
<hr>
<div class="header">
<p>
Next: <a href="do_002dsymbols.html" accesskey="n" rel="next">do-symbols</a>, Previous: <a href="use_002dpackage.html" accesskey="p" rel="prev">use-package</a>, Up: <a href="Packages-Dictionary.html" accesskey="u" rel="up">Packages Dictionary</a> </p>
</div>
</body>
</html>
|
