3
@node Packages, Numbers (Numbers), Symbols, Top
8
* Packages Dictionary::
11
@node Package Concepts, Packages Dictionary, Packages, Packages
12
@section Package Concepts
14
@c including concept-packages
17
* Introduction to Packages::
18
* Standardized Packages::
21
@node Introduction to Packages, Standardized Packages, Package Concepts, Package Concepts
22
@subsection Introduction to Packages
26
establishes a mapping from names to @i{symbols}.
27
At any given time, one @i{package} is current.
28
The @i{current package}
29
@IGindex{current package}
30
is the one that is the @i{value} of @b{*package*}.
31
When using the @i{Lisp reader},
32
it is possible to refer to @i{symbols} in @i{packages}
33
other than the current one through the use of @i{package prefixes} in the
34
printed representation of the @i{symbol}.
36
Figure 11--1 lists some @i{defined names} that are applicable
39
takes an argument that is either a @i{symbol} or a @i{list}
41
an argument of @b{nil} is treated as an empty @i{list} of @i{symbols}.
42
Any @i{package} argument may be either a @i{string}, a @i{symbol}, or
43
a @i{package}. If a @i{symbol} is supplied, its name will be used
44
as the @i{package} name.
49
@w{ *modules* import provide }
50
@w{ *package* in-package rename-package }
51
@w{ defpackage intern require }
52
@w{ do-all-symbols list-all-packages shadow }
53
@w{ do-external-symbols make-package shadowing-import }
54
@w{ do-symbols package-name unexport }
55
@w{ export package-nicknames unintern }
56
@w{ find-all-symbols package-shadowing-symbols unuse-package }
57
@w{ find-package package-use-list use-package }
58
@w{ find-symbol package-used-by-list }
61
@w{ Figure 11--1: Some Defined Names related to Packages }
67
* Package Names and Nicknames::
68
* Symbols in a Package::
69
* Internal and External Symbols::
70
* Package Inheritance::
71
* Accessibility of Symbols in a Package::
72
* Locating a Symbol in a Package::
73
* Prevention of Name Conflicts in Packages::
76
@node Package Names and Nicknames, Symbols in a Package, Introduction to Packages, Introduction to Packages
77
@subsubsection Package Names and Nicknames
79
Each @i{package} has a @i{name} (a @i{string}) and perhaps some @i{nicknames}
81
These are assigned when the @i{package} is created and can be changed later.
83
There is a single namespace for @i{packages}.
84
The @i{function} @b{find-package} translates a package
85
@i{name} or @i{nickname} into the associated @i{package}.
86
The @i{function} @b{package-name} returns the @i{name} of a @i{package}.
87
The @i{function} @b{package-nicknames} returns
88
a @i{list} of all @i{nicknames} for a @i{package}.
89
@b{rename-package} removes a @i{package}'s
90
current @i{name} and @i{nicknames} and replaces them with new ones
91
specified by the caller.
93
@node Symbols in a Package, Internal and External Symbols, Package Names and Nicknames, Introduction to Packages
94
@subsubsection Symbols in a Package
96
@node Internal and External Symbols, Package Inheritance, Symbols in a Package, Introduction to Packages
97
@subsubsection Internal and External Symbols
99
The mappings in a @i{package} are divided into two classes, external and internal.
100
The @i{symbols} targeted by these different mappings
101
are called @i{external symbols} and @i{internal symbols}
102
@IGindex{internal symbol}
104
@i{package}. Within a @i{package}, a name refers to one
105
@i{symbol} or to none; if it does refer
106
to a @i{symbol}, then it is either external or internal in that
107
@i{package}, but not both.
109
@IGindex{external symbol}
111
are part of the package's public interface to other @i{packages}.
112
@i{Symbols} become @i{external symbols} of a given
113
@i{package} if they have been @i{exported} from that @i{package}.
115
A @i{symbol} has the same @i{name} no matter what @i{package}
116
it is @i{present} in, but it might be an @i{external symbol} of some @i{packages}
117
and an @i{internal symbol} of others.
119
@node Package Inheritance, Accessibility of Symbols in a Package, Internal and External Symbols, Introduction to Packages
120
@subsubsection Package Inheritance
122
@i{Packages} can be built up in layers. From one point of view,
123
a @i{package} is a single collection
124
of mappings from @i{strings} into @i{internal symbols} and
125
@i{external symbols}.
126
However, some of these mappings might be established within the @i{package}
127
itself, while other mappings are inherited from other @i{packages}
129
A @i{symbol} is said to be @i{present}
132
if the mapping is in the @i{package} itself and is
133
not inherited from somewhere else.
135
There is no way to inherit the @i{internal symbols} of another @i{package};
136
to refer to an @i{internal symbol} using the @i{Lisp reader},
137
a @i{package} containing the @i{symbol}
138
must be made to be the @i{current package},
139
a @i{package prefix} must be used,
140
or the @i{symbol} must be @i{imported} into the @i{current package}.
142
@node Accessibility of Symbols in a Package, Locating a Symbol in a Package, Package Inheritance, Introduction to Packages
143
@subsubsection Accessibility of Symbols in a Package
145
A @i{symbol} becomes @i{accessible}
148
if that is its @i{home package} when it is created,
149
or if it is @i{imported} into that @i{package},
150
or by inheritance via @b{use-package}.
152
If a @i{symbol} is @i{accessible} in a @i{package},
153
it can be referred to when using the @i{Lisp reader}
154
without a @i{package prefix} when that @i{package} is the @i{current package},
155
regardless of whether it is @i{present} or inherited.
157
@i{Symbols} from one @i{package} can be made @i{accessible}
158
in another @i{package} in two ways.
163
Any individual @i{symbol} can be added to a @i{package} by use
164
of @b{import}. After the call to @b{import} the
165
@i{symbol} is @i{present} in the importing @i{package}.
166
The status of the @i{symbol} in the @i{package}
167
it came from (if any) is unchanged, and the @i{home package} for
168
this @i{symbol} is unchanged.
169
Once @i{imported}, a @i{symbol} is @i{present} in the
170
importing @i{package}
171
and can be removed only by calling @b{unintern}.
173
A @i{symbol} is @i{shadowed}_3 by another @i{symbol}
174
in some @i{package} if the first @i{symbol} would be @i{accessible}
175
by inheritance if not for the presence of the second @i{symbol}.
176
See @b{shadowing-import}.
179
The second mechanism for making @i{symbols} from one @i{package}
180
@i{accessible} in another is provided by @b{use-package}.
181
All of the @i{external symbols} of the used @i{package} are inherited
182
by the using @i{package}.
183
The @i{function} @b{unuse-package} undoes the effects of a previous @b{use-package}.
186
@node Locating a Symbol in a Package, Prevention of Name Conflicts in Packages, Accessibility of Symbols in a Package, Introduction to Packages
187
@subsubsection Locating a Symbol in a Package
189
When a @i{symbol} is to be located in a given @i{package}
190
the following occurs:
194
The @i{external symbols} and @i{internal symbols} of the
195
@i{package} are searched for the @i{symbol}.
197
The @i{external symbols} of the used @i{packages} are
199
in some unspecified order. The
200
order does not matter; see the rules for handling name
201
conflicts listed below.
204
@node Prevention of Name Conflicts in Packages, , Locating a Symbol in a Package, Introduction to Packages
205
@subsubsection Prevention of Name Conflicts in Packages
207
Within one @i{package}, any particular name can refer to at most one
208
@i{symbol}. A name conflict is said to occur when there would be more than
209
one candidate @i{symbol}. Any time a name conflict is about to occur,
210
a @i{correctable} @i{error} is signaled.
212
The following rules apply to name conflicts:
216
Name conflicts are detected when they become possible, that is, when the
217
package structure is altered. Name
218
conflicts are not checked during every name lookup.
221
If the @i{same} @i{symbol} is @i{accessible} to a @i{package}
222
through more than one path, there is no name conflict.
223
A @i{symbol} cannot conflict with itself.
224
Name conflicts occur only between @i{distinct} @i{symbols} with
225
the same name (under @b{string=}).
228
Every @i{package} has a list of shadowing @i{symbols}.
229
A shadowing @i{symbol} takes precedence over any other @i{symbol} of
230
the same name that would otherwise be @i{accessible} in the @i{package}.
231
A name conflict involving a shadowing symbol is always resolved in favor of
232
the shadowing @i{symbol}, without signaling an error (except for one
233
exception involving @b{import}).
234
See @b{shadow} and @b{shadowing-import}.
237
The functions @b{use-package}, @b{import}, and
238
@b{export} check for name conflicts.
241
@b{shadow} and @b{shadowing-import}
242
never signal a name-conflict error.
245
@b{unuse-package} and @b{unexport}
246
do not need to do any name-conflict checking.
247
@b{unintern} does name-conflict checking only when a @i{symbol}
248
being @i{uninterned} is a @i{shadowing symbol}
249
@IGindex{shadowing symbol}
253
Giving a shadowing symbol to @b{unintern}
254
can uncover a name conflict that had
255
previously been resolved by the shadowing.
258
Package functions signal name-conflict errors of @i{type} @b{package-error} before making any
259
change to the package structure. When multiple changes are to be made,
261
permissible for the implementation to process each change separately.
262
For example, when @b{export} is given a
266
conflict caused by the second @i{symbol}
267
in the @i{list} might still export the
268
first @i{symbol} in the @i{list}.
269
However, a name-conflict error caused by @b{export}
270
of a single @i{symbol} will be signaled before
271
that @i{symbol}'s @i{accessibility} in any @i{package} is changed.
274
Continuing from a name-conflict error must offer the user a chance to
275
resolve the name conflict in favor of either of the candidates. The
277
structure should be altered to reflect the resolution of the
278
name conflict, via @b{shadowing-import},
283
A name conflict in @b{use-package} between a @i{symbol}
284
@i{present} in the using @i{package} and an @i{external symbol} of the used
285
@i{package} is resolved in favor of the first @i{symbol} by making it a
286
shadowing @i{symbol}, or in favor of the second @i{symbol} by uninterning
287
the first @i{symbol} from the using @i{package}.
290
A name conflict in @b{export} or @b{unintern}
291
due to a @i{package}'s inheriting two @i{distinct} @i{symbols}
292
with the @i{same} @i{name} (under @b{string=})
293
from two other @i{packages} can be resolved in
294
favor of either @i{symbol} by importing it into the using
295
@i{package} and making it a @i{shadowing symbol}
296
@IGindex{shadowing symbol}
298
just as with @b{use-package}.
301
@node Standardized Packages, , Introduction to Packages, Package Concepts
302
@subsection Standardized Packages
304
This section describes the @i{packages} that are available
305
in every @i{conforming implementation}. A summary of the
306
@i{names} and @i{nicknames} of those @i{standardized} @i{packages}
307
is given in Figure 11--2.
313
@w{ @t{COMMON-LISP} @t{CL} }
314
@w{ @t{COMMON-LISP-USER} @t{CL-USER} }
315
@w{ @t{KEYWORD} @i{none} }
318
@w{ Figure 11--2: Standardized Package Names}
324
* The COMMON-LISP Package::
325
* Constraints on the COMMON-LISP Package for Conforming Implementations::
326
* Constraints on the COMMON-LISP Package for Conforming Programs::
327
* Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs::
328
* The COMMON-LISP-USER Package::
329
* The KEYWORD Package::
330
* Interning a Symbol in the KEYWORD Package::
331
* Notes about The KEYWORD Package::
332
* Implementation-Defined Packages::
335
@node The COMMON-LISP Package, Constraints on the COMMON-LISP Package for Conforming Implementations, Standardized Packages, Standardized Packages
336
@subsubsection The COMMON-LISP Package
338
@IPindex{common-lisp}
342
The @t{COMMON-LISP} @i{package} contains the primitives of the @r{Common Lisp} system as
343
defined by this specification. Its @i{external} @i{symbols} include
344
all of the @i{defined names} (except for @i{defined names} in
345
the @t{KEYWORD} @i{package}) that are present in the @r{Common Lisp} system,
346
such as @b{car}, @b{cdr}, @b{*package*}, etc.
347
The @t{COMMON-LISP} @i{package} has the @i{nickname} @t{CL}.
349
The @t{COMMON-LISP} @i{package} has as @i{external} @i{symbols} those
350
symbols enumerated in the figures in @ref{Symbols in the COMMON-LISP Package}, and no others.
351
These @i{external} @i{symbols} are @i{present} in the @t{COMMON-LISP} @i{package}
352
but their @i{home package} need not be the @t{COMMON-LISP} @i{package}.
354
For example, the symbol @t{HELP} cannot be an @i{external symbol} of
355
the @t{COMMON-LISP} @i{package} because it is not mentioned in @ref{Symbols in the COMMON-LISP Package}.
356
In contrast, the @i{symbol} @b{variable}
357
must be an @i{external symbol} of the @t{COMMON-LISP} @i{package}
358
even though it has no definition
359
because it is listed in that section
360
(to support its use as a valid second @i{argument} to the @i{function} @b{documentation}).
362
The @t{COMMON-LISP} @i{package} can have additional @i{internal symbols}.
364
@node Constraints on the COMMON-LISP Package for Conforming Implementations, Constraints on the COMMON-LISP Package for Conforming Programs, The COMMON-LISP Package, Standardized Packages
365
@subsubsection Constraints on the COMMON-LISP Package for Conforming Implementations
367
In a @i{conforming implementation},
368
an @i{external} @i{symbol} of the @t{COMMON-LISP} @i{package} can have
369
a @i{function}, @i{macro}, or @i{special operator} definition,
370
a @i{global variable} definition
371
(or other status as a @i{dynamic variable}
372
due to a @b{special} @i{proclamation}),
373
or a @i{type} definition
374
only if explicitly permitted in this standard.
376
@b{fboundp} @i{yields} @i{false}
377
for any @i{external symbol} of the @t{COMMON-LISP} @i{package}
378
that is not the @i{name} of a @i{standardized}
379
@i{function}, @i{macro} or @i{special operator},
381
@b{boundp} returns @i{false}
382
for any @i{external symbol} of the @t{COMMON-LISP} @i{package}
383
that is not the @i{name} of a @i{standardized} @i{global variable}.
385
@i{conforming programs} can use @i{external symbols} of the @t{COMMON-LISP} @i{package}
386
as the @i{names} of local @i{lexical variables}
387
with confidence that those @i{names} have not been @i{proclaimed} @b{special}
388
by the @i{implementation}
389
unless those @i{symbols} are
390
@i{names} of @i{standardized} @i{global variables}.
392
A @i{conforming implementation} must not place any @i{property} on
393
an @i{external symbol} of the @t{COMMON-LISP} @i{package} using a @i{property indicator}
394
that is either an @i{external symbol} of any @i{standardized} @i{package}
395
or a @i{symbol} that is otherwise @i{accessible} in the @t{COMMON-LISP-USER} @i{package}.
397
@node Constraints on the COMMON-LISP Package for Conforming Programs, Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, Constraints on the COMMON-LISP Package for Conforming Implementations, Standardized Packages
398
@subsubsection Constraints on the COMMON-LISP Package for Conforming Programs
400
@ITindex{redefinition}
402
Except where explicitly allowed, the consequences are undefined if any
403
of the following actions are performed on an @i{external symbol}
404
of the @t{COMMON-LISP} @i{package}:
409
@i{Binding} or altering its value (lexically or dynamically).
410
(Some exceptions are noted below.)
417
or @i{binding} it as a @i{function}.
418
(Some exceptions are noted below.)
425
or @i{binding} it as a @i{macro}
427
or @i{compiler macro}.
429
(Some exceptions are noted below.)
432
Defining it as a @i{type specifier}
436
@b{define-condition}).
439
Defining it as a structure (via @b{defstruct}).
442
Defining it as a @i{declaration}
443
with a @b{declaration} @i{proclamation}.
446
Defining it as a @i{symbol macro}.
449
Altering its @i{home package}.
452
Tracing it (via @b{trace}).
455
Declaring or proclaiming it
464
Declaring or proclaiming its @b{type} or @b{ftype}
470
(Some exceptions are noted below.)
473
Removing it from the @t{COMMON-LISP} @i{package}.
476
Defining a @i{setf expander} for it
477
(via @b{defsetf} or @b{define-setf-method}).
480
Defining, undefining, or binding its @i{setf function name}.
483
Defining it as a @i{method combination} type
484
(via @b{define-method-combination}).
487
Using it as the class-name argument
488
to @b{setf} of @b{find-class}.
491
Binding it as a @i{catch tag}.
494
Binding it as a @i{restart} @i{name}.
497
Defining a @i{method}
498
for a @i{standardized} @i{generic function}
499
which is @i{applicable} when all of the @i{arguments}
500
are @i{direct instances} of @i{standardized} @i{classes}.
504
@node Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, The COMMON-LISP-USER Package, Constraints on the COMMON-LISP Package for Conforming Programs, Standardized Packages
505
@subsubsection Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs
507
If an @i{external symbol} of the @t{COMMON-LISP} @i{package}
508
is not globally defined as a @i{standardized} @i{dynamic variable}
509
or @i{constant variable},
510
it is allowed to lexically @i{bind} it
511
and to declare the @b{type} of that @i{binding},
513
it is allowed to locally @i{establish} it as a @i{symbol macro}
514
(@i{e.g.}, with @b{symbol-macrolet}).
516
Unless explicitly specified otherwise,
517
if an @i{external symbol} of the @t{COMMON-LISP} @i{package}
518
is globally defined as a @i{standardized} @i{dynamic variable},
519
it is permitted to @i{bind} or @i{assign} that @i{dynamic variable}
520
provided that the ``Value Type'' constraints on the @i{dynamic variable}
521
are maintained, and that the new @i{value} of the @i{variable}
522
is consistent with the stated purpose of the @i{variable}.
524
If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined
525
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
526
it is allowed to lexically @i{bind} it as a @i{function} (@i{e.g.}, with @b{flet}),
527
to declare the @b{ftype} of that @i{binding},
529
(in @i{implementations} which provide the ability to do so)
530
to @b{trace} that @i{binding}.
532
If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined
533
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
534
it is allowed to lexically @i{bind} it as a @i{macro} (@i{e.g.}, with @b{macrolet}).
536
If an @i{external symbol} of the @t{COMMON-LISP} @i{package} is not defined
537
as a @i{standardized} @i{function}, @i{macro}, or @i{special operator},
538
it is allowed to lexically @i{bind} its @i{setf function name}
540
and to declare the @b{ftype} of that @i{binding}.
542
@node The COMMON-LISP-USER Package, The KEYWORD Package, Some Exceptions to Constraints on the COMMON-LISP Package for Conforming Programs, Standardized Packages
543
@subsubsection The COMMON-LISP-USER Package
545
@IPindex{common-lisp-user}
549
The @t{COMMON-LISP-USER} @i{package} is the @i{current package} when
550
a @r{Common Lisp} system starts up. This @i{package} @i{uses} the @t{COMMON-LISP} @i{package}.
551
The @t{COMMON-LISP-USER} @i{package} has the @i{nickname} @t{CL-USER}.
553
The @t{COMMON-LISP-USER} @i{package} can have additional @i{symbols} @i{interned} within it;
554
it can @i{use} other @i{implementation-defined} @i{packages}.
556
@node The KEYWORD Package, Interning a Symbol in the KEYWORD Package, The COMMON-LISP-USER Package, Standardized Packages
557
@subsubsection The KEYWORD Package
561
The @t{KEYWORD} @i{package} contains @i{symbols}, called @i{keywords}_1,
562
that are typically used as special markers in @i{programs}
563
and their associated data @i{expressions}_1.
565
@i{Symbol} @i{tokens} that start with a @i{package marker}
566
are parsed by the @i{Lisp reader} as @i{symbols}
567
in the @t{KEYWORD} @i{package}; see @ref{Symbols as Tokens}.
568
This makes it notationally convenient to use @i{keywords}
569
when communicating between programs in different @i{packages}.
570
For example, the mechanism for passing @i{keyword parameters} in a @i{call} uses
571
@i{keywords}_1 to name the corresponding @i{arguments};
572
see @ref{Ordinary Lambda Lists}.
574
@i{Symbols} in the @t{KEYWORD} @i{package} are, by definition, of @i{type} @b{keyword}.
576
@node Interning a Symbol in the KEYWORD Package, Notes about The KEYWORD Package, The KEYWORD Package, Standardized Packages
577
@subsubsection Interning a Symbol in the KEYWORD Package
579
The @t{KEYWORD} @i{package} is treated differently than other @i{packages}
580
in that special actions are taken when a @i{symbol} is @i{interned} in it.
581
In particular, when a @i{symbol} is @i{interned} in the @t{KEYWORD} @i{package},
582
it is automatically made to be an @i{external symbol}
583
and is automatically made to be a @i{constant variable} with itself as a @i{value}.
585
@node Notes about The KEYWORD Package, Implementation-Defined Packages, Interning a Symbol in the KEYWORD Package, Standardized Packages
586
@subsubsection Notes about The KEYWORD Package
588
It is generally best to confine the use of @i{keywords} to situations in which
589
there are a finitely enumerable set of names to be selected between. For example,
590
if there were two states of a light switch, they might be called @t{:on} and @t{:off}.
592
In situations where the set of names is not finitely enumerable
593
(@i{i.e.}, where name conflicts might arise)
594
it is frequently best to use @i{symbols} in some @i{package}
595
other than @t{KEYWORD} so that conflicts will be naturally avoided.
596
For example, it is generally not wise for a @i{program} to use a @i{keyword}_1
597
as a @i{property indicator}, since if there were ever another @i{program}
598
that did the same thing, each would clobber the other's data.
600
@node Implementation-Defined Packages, , Notes about The KEYWORD Package, Standardized Packages
601
@subsubsection Implementation-Defined Packages
603
Other, @i{implementation-defined} @i{packages} might be present
604
in the initial @r{Common Lisp} environment.
606
It is recommended, but not required, that the documentation for a
607
@i{conforming implementation} contain a full list of all @i{package} names
608
initially present in that @i{implementation} but not specified in this specification.
609
(See also the @i{function} @b{list-all-packages}.)
611
@c end of including concept-packages
613
@node Packages Dictionary, , Package Concepts, Packages
614
@section Packages Dictionary
616
@c including dict-packages
625
* list-all-packages::
631
* with-package-iterator::
641
* package-nicknames::
642
* package-shadowing-symbols::
644
* package-used-by-list::
648
* package-error-package::
651
@node package, export, Packages Dictionary, Packages Dictionary
652
@subsection package [System Class]
654
@subsubheading Class Precedence List::
658
@subsubheading Description::
660
A @i{package} is a @i{namespace} that maps @i{symbol} @i{names}
661
to @i{symbols}; see @ref{Package Concepts}.
663
@subsubheading See Also::
665
@ref{Package Concepts},
666
@ref{Printing Other Objects},
667
@ref{Symbols as Tokens}
669
@node export, find-symbol, package, Packages Dictionary
670
@subsection export [Function]
672
@code{export} @i{symbols @r{&optional} package} @result{} @i{@b{t}}
674
@subsubheading Arguments and Values::
676
@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.
678
@i{package}---a @i{package designator}.
680
The default is the @i{current package}.
682
@subsubheading Description::
684
@b{export} makes one or more @i{symbols} that are @i{accessible}
685
in @i{package} (whether directly or by inheritance) be @i{external symbols}
688
If any of the @i{symbols} is already @i{accessible} as
689
an @i{external symbol} of @i{package},
690
@b{export} has no effect on that @i{symbol}.
692
@i{present} in @i{package}
693
as an internal symbol, it is simply changed to external status.
694
If it is @i{accessible} as an @i{internal symbol} via @b{use-package},
696
is first @i{imported} into @i{package},
698
(The @i{symbol} is then @i{present} in the @i{package}
699
whether or not @i{package} continues to use the @i{package} through
700
which the @i{symbol} was originally inherited.)
704
@i{accessible} to all the @i{packages} that use @i{package}.
705
All of these @i{packages} are checked for name conflicts:
706
@t{(export @i{s} @i{p})} does
707
@t{(find-symbol (symbol-name @i{s}) @i{q})} for each package @i{q}
708
in @t{(package-used-by-list @i{p})}. Note that in the usual case of
709
an @b{export} during the initial definition of a @i{package},
711
result of @b{package-used-by-list}
712
is @b{nil} and the name-conflict checking
713
takes negligible time.
714
When multiple changes are to be made,
715
for example when @b{export}
716
is given a @i{list} of @i{symbols}, it is
717
permissible for the implementation to process each change separately,
718
so that aborting from a name
719
conflict caused by any but the first @i{symbol} in the
720
@i{list} does not unexport the
721
first @i{symbol} in the @i{list}.
722
However, aborting from a name-conflict error
724
of one of @i{symbols} does not leave that @i{symbol}
727
and @i{inaccessible} to others; with respect to
728
each of @i{symbols} processed, @b{export}
729
behaves as if it were as an atomic operation.
731
A name conflict in @b{export} between one of
732
@i{symbols} being exported and a
733
@i{symbol} already @i{present} in a @i{package}
734
that would inherit the
735
newly-exported @i{symbol}
736
may be resolved in favor of the exported @i{symbol}
737
by uninterning the other one, or in favor of the already-present
738
@i{symbol} by making it a shadowing symbol.
740
@subsubheading Examples::
743
(make-package 'temp :use nil) @result{} #<PACKAGE "TEMP">
744
(use-package 'temp) @result{} T
745
(intern "TEMP-SYM" 'temp) @result{} TEMP::TEMP-SYM, NIL
746
(find-symbol "TEMP-SYM") @result{} NIL, NIL
747
(export (find-symbol "TEMP-SYM" 'temp) 'temp) @result{} T
748
(find-symbol "TEMP-SYM") @result{} TEMP-SYM, :INHERITED
751
@subsubheading Side Effects::
753
The package system is modified.
755
@subsubheading Affected By::
757
@i{Accessible} @i{symbols}.
759
@subsubheading Exceptional Situations::
761
If any of the @i{symbols} is not @i{accessible} at all in @i{package},
762
an error of @i{type} @b{package-error} is signaled that is @i{correctable}
763
by permitting the @i{user}
764
to interactively specify whether that @i{symbol} should be @i{imported}.
766
@subsubheading See Also::
772
@ref{Package Concepts}
774
@node find-symbol, find-package, export, Packages Dictionary
775
@subsection find-symbol [Function]
777
@code{find-symbol} @i{string @r{&optional} package} @result{} @i{symbol, status}
779
@subsubheading Arguments and Values::
781
@i{string}---a @i{string}.
783
@i{package}---a @i{package designator}.
785
The default is the @i{current package}.
787
@i{symbol}---a @i{symbol} accessible in the @i{package},
790
@i{status}---one of @t{:inherited}, @t{:external}, @t{:internal}, or @b{nil}.
792
@subsubheading Description::
794
@b{find-symbol} locates a @i{symbol} whose @i{name} is
795
@i{string} in a @i{package}.
796
If a @i{symbol} named @i{string} is found in @i{package},
797
directly or by inheritance, the @i{symbol}
798
found is returned as the first
799
value; the second value is as follows:
804
If the @i{symbol} is @i{present} in @i{package}
805
as an @i{internal symbol}.
808
If the @i{symbol} is @i{present} in @i{package}
809
as an @i{external symbol}.
812
If the @i{symbol} is inherited by @i{package}
813
through @b{use-package},
814
but is not @i{present} in @i{package}.
818
If no such @i{symbol} is @i{accessible} in @i{package},
819
both values are @b{nil}.
821
@subsubheading Examples::
824
(find-symbol "NEVER-BEFORE-USED") @result{} NIL, NIL
825
(find-symbol "NEVER-BEFORE-USED") @result{} NIL, NIL
826
(intern "NEVER-BEFORE-USED") @result{} NEVER-BEFORE-USED, NIL
827
(intern "NEVER-BEFORE-USED") @result{} NEVER-BEFORE-USED, :INTERNAL
828
(find-symbol "NEVER-BEFORE-USED") @result{} NEVER-BEFORE-USED, :INTERNAL
829
(find-symbol "never-before-used") @result{} NIL, NIL
830
(find-symbol "CAR" 'common-lisp-user) @result{} CAR, :INHERITED
831
(find-symbol "CAR" 'common-lisp) @result{} CAR, :EXTERNAL
832
(find-symbol "NIL" 'common-lisp-user) @result{} NIL, :INHERITED
833
(find-symbol "NIL" 'common-lisp) @result{} NIL, :EXTERNAL
834
(find-symbol "NIL" (prog1 (make-package "JUST-TESTING" :use '())
835
(intern "NIL" "JUST-TESTING")))
836
@result{} JUST-TESTING::NIL, :INTERNAL
837
(export 'just-testing::nil 'just-testing)
838
(find-symbol "NIL" 'just-testing) @result{} JUST-TESTING:NIL, :EXTERNAL
839
(find-symbol "NIL" "KEYWORD")
841
@i{OR}@result{} :NIL, :EXTERNAL
842
(find-symbol (symbol-name :nil) "KEYWORD") @result{} :NIL, :EXTERNAL
845
@subsubheading Affected By::
855
@subsubheading See Also::
859
@ref{find-all-symbols}
861
@subsubheading Notes::
863
@b{find-symbol} is operationally equivalent to @b{intern},
864
except that it never creates a new @i{symbol}.
866
@node find-package, find-all-symbols, find-symbol, Packages Dictionary
867
@subsection find-package [Function]
869
@code{find-package} @i{name} @result{} @i{package}
871
@subsubheading Arguments and Values::
873
@i{name}---a @i{string designator} or a @i{package} @i{object}.
875
@i{package}---a @i{package} @i{object} or @b{nil}.
877
@subsubheading Description::
879
If @i{name} is a @i{string designator},
880
@b{find-package} locates and returns the
881
@i{package} whose name or nickname is @i{name}.
883
search is case sensitive.
884
If there is no such @i{package},
885
@b{find-package} returns @b{nil}.
887
If @i{name} is a @i{package} @i{object},
888
that @i{package} @i{object} is returned.
890
@subsubheading Examples::
893
(find-package 'common-lisp) @result{} #<PACKAGE "COMMON-LISP">
894
(find-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
895
(find-package 'not-there) @result{} NIL
898
@subsubheading Affected By::
900
The set of @i{packages} created by the @i{implementation}.
907
@subsubheading See Also::
911
@node find-all-symbols, import, find-package, Packages Dictionary
912
@subsection find-all-symbols [Function]
914
@code{find-all-symbols} @i{string} @result{} @i{symbols}
916
@subsubheading Arguments and Values::
918
@i{string}---a @i{string designator}.
920
@i{symbols}---a @i{list} of @i{symbols}.
922
@subsubheading Description::
924
@b{find-all-symbols} searches
925
every @i{registered package}
926
for @i{symbols} that have a
927
@i{name} that is the @i{same} (under @b{string=}) as
928
@i{string}. A @i{list} of all such @i{symbols} is returned.
929
Whether or how the @i{list} is ordered is
930
@i{implementation-dependent}.
932
@subsubheading Examples::
935
(find-all-symbols 'car)
937
@i{OR}@result{} (CAR VEHICLES:CAR)
938
@i{OR}@result{} (VEHICLES:CAR CAR)
939
(intern "CAR" (make-package 'temp :use nil)) @result{} TEMP::CAR, NIL
940
(find-all-symbols 'car)
941
@result{} (TEMP::CAR CAR)
942
@i{OR}@result{} (CAR TEMP::CAR)
943
@i{OR}@result{} (TEMP::CAR CAR VEHICLES:CAR)
944
@i{OR}@result{} (CAR TEMP::CAR VEHICLES:CAR)
947
@subsubheading See Also::
951
@node import, list-all-packages, find-all-symbols, Packages Dictionary
952
@subsection import [Function]
954
@code{import} @i{symbols @r{&optional} package} @result{} @i{@b{t}}
956
@subsubheading Arguments and Values::
958
@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.
960
@i{package}---a @i{package designator}.
962
The default is the @i{current package}.
964
@subsubheading Description::
966
@b{import} adds @i{symbol} or
967
@i{symbols} to the internals of @i{package}, checking for name
968
conflicts with existing @i{symbols} either @i{present} in @i{package}
969
or @i{accessible} to it. Once the @i{symbols} have been
970
@i{imported}, they may be referenced in the @i{importing}
971
@i{package} without the use of a @i{package prefix} when using the @i{Lisp reader}.
973
A name conflict in @b{import} between the
974
@i{symbol} being imported and a symbol inherited from some other @i{package} can
975
be resolved in favor of the
976
@i{symbol} being @i{imported}
977
by making it a shadowing symbol, or in favor
978
of the @i{symbol} already @i{accessible} by
979
not doing the @b{import}. A
980
name conflict in @b{import} with a @i{symbol}
981
already @i{present} in the
983
may be resolved by uninterning that @i{symbol}, or by not
984
doing the @b{import}.
986
The imported @i{symbol} is
987
not automatically exported from the @i{current package}, but if it is
988
already @i{present} and external, then the fact that it
989
is external is not changed.
991
If any @i{symbol} to be @i{imported} has no home
992
package (@i{i.e.}, @t{(symbol-package @i{symbol}) @result{} nil}),
993
@b{import} sets the @i{home package}
994
of the @i{symbol} to @i{package}.
996
If the @i{symbol} is already @i{present} in the importing @i{package},
997
@b{import} has no effect.
999
@subsubheading Examples::
1002
(import 'common-lisp::car (make-package 'temp :use nil)) @result{} T
1003
(find-symbol "CAR" 'temp) @result{} CAR, :INTERNAL
1004
(find-symbol "CDR" 'temp) @result{} NIL, NIL
1007
The form @t{(import 'editor:buffer)} takes the external symbol named
1008
@t{buffer} in the @t{EDITOR} @i{package} (this symbol was located when the form
1009
was read by the @i{Lisp reader}) and adds it to the @i{current package}
1010
as an @i{internal symbol}. The symbol @t{buffer} is then @i{present} in
1011
the @i{current package}.
1013
@subsubheading Side Effects::
1015
The package system is modified.
1017
@subsubheading Affected By::
1019
Current state of the package system.
1021
@subsubheading Exceptional Situations::
1023
@b{import} signals a @i{correctable} error of @i{type} @b{package-error}
1024
if any of the @i{symbols} to be @i{imported} has the @i{same} @i{name}
1025
(under @b{string=}) as some distinct @i{symbol} (under @b{eql})
1026
already @i{accessible} in the @i{package}, even if the conflict is
1027
with a @i{shadowing symbol} of the @i{package}.
1029
@subsubheading See Also::
1035
@node list-all-packages, rename-package, import, Packages Dictionary
1036
@subsection list-all-packages [Function]
1038
@code{list-all-packages} @i{<@i{no @i{arguments}}>} @result{} @i{packages}
1040
@subsubheading Arguments and Values::
1042
@i{packages}---a @i{list} of @i{package} @i{objects}.
1044
@subsubheading Description::
1046
@b{list-all-packages} returns a
1052
all @i{registered packages}.
1054
@subsubheading Examples::
1057
(let ((before (list-all-packages)))
1058
(make-package 'temp)
1059
(set-difference (list-all-packages) before)) @result{} (#<PACKAGE "TEMP">)
1062
@subsubheading Affected By::
1068
@node rename-package, shadow, list-all-packages, Packages Dictionary
1069
@subsection rename-package [Function]
1071
@code{rename-package} @i{package new-name @r{&optional} new-nicknames} @result{} @i{package-object}
1073
@subsubheading Arguments and Values::
1075
@i{package}---a @i{package designator}.
1077
@i{new-name}---a @i{package designator}.
1079
@i{new-nicknames}---a @i{list} of @i{string designators}.
1080
The default is the @i{empty list}.
1082
@i{package-object}---the renamed @i{package} @i{object}.
1084
@subsubheading Description::
1086
Replaces the name and nicknames of @i{package}.
1087
The old name and all of the old nicknames of @i{package} are eliminated
1088
and are replaced by @i{new-name} and @i{new-nicknames}.
1090
The consequences are undefined if @i{new-name} or any @i{new-nickname}
1091
conflicts with any existing package names.
1093
@subsubheading Examples::
1096
(make-package 'temporary :nicknames '("TEMP")) @result{} #<PACKAGE "TEMPORARY">
1097
(rename-package 'temp 'ephemeral) @result{} #<PACKAGE "EPHEMERAL">
1098
(package-nicknames (find-package 'ephemeral)) @result{} ()
1099
(find-package 'temporary) @result{} NIL
1100
(rename-package 'ephemeral 'temporary '(temp fleeting))
1101
@result{} #<PACKAGE "TEMPORARY">
1102
(package-nicknames (find-package 'temp)) @result{} ("TEMP" "FLEETING")
1105
@subsubheading See Also::
1109
@node shadow, shadowing-import, rename-package, Packages Dictionary
1110
@subsection shadow [Function]
1112
@code{shadow} @i{symbol-names @r{&optional} package} @result{} @i{@b{t}}
1114
@subsubheading Arguments and Values::
1116
@i{symbol-names}---a @i{designator} for
1117
a @i{list} of @i{string designators}.
1119
@i{package}---a @i{package designator}.
1121
The default is the @i{current package}.
1123
@subsubheading Description::
1125
@b{shadow} assures that @i{symbols} with names given
1126
by @i{symbol-names} are @i{present}
1130
Specifically, @i{package} is searched for @i{symbols}
1131
with the @i{names} supplied by @i{symbol-names}.
1133
For each such @i{name}, if a corresponding @i{symbol}
1134
is not @i{present} in @i{package} (directly, not by inheritance),
1135
then a corresponding @i{symbol} is created with that @i{name},
1136
and inserted into @i{package} as an @i{internal symbol}.
1137
The corresponding @i{symbol}, whether pre-existing or newly created,
1138
is then added, if not already present, to the @i{shadowing symbols list}
1141
@subsubheading Examples::
1144
(package-shadowing-symbols (make-package 'temp)) @result{} NIL
1145
(find-symbol 'car 'temp) @result{} CAR, :INHERITED
1146
(shadow 'car 'temp) @result{} T
1147
(find-symbol 'car 'temp) @result{} TEMP::CAR, :INTERNAL
1148
(package-shadowing-symbols 'temp) @result{} (TEMP::CAR)
1152
(make-package 'test-1) @result{} #<PACKAGE "TEST-1">
1153
(intern "TEST" (find-package 'test-1)) @result{} TEST-1::TEST, NIL
1154
(shadow 'test-1::test (find-package 'test-1)) @result{} T
1155
(shadow 'TEST (find-package 'test-1)) @result{} T
1156
(assert (not (null (member 'test-1::test (package-shadowing-symbols
1157
(find-package 'test-1))))))
1159
(make-package 'test-2) @result{} #<PACKAGE "TEST-2">
1160
(intern "TEST" (find-package 'test-2)) @result{} TEST-2::TEST, NIL
1161
(export 'test-2::test (find-package 'test-2)) @result{} T
1162
(use-package 'test-2 (find-package 'test-1)) ;should not error
1166
@subsubheading Side Effects::
1168
@b{shadow} changes the state of the package system in such a
1169
way that the package consistency rules do not hold across the change.
1171
@subsubheading Affected By::
1173
Current state of the package system.
1175
@subsubheading See Also::
1177
@ref{package-shadowing-symbols}
1179
@ref{Package Concepts}
1181
@subsubheading Notes::
1183
If a @i{symbol} with a name in @i{symbol-names} already exists
1184
in @i{package}, but by inheritance, the inherited symbol becomes
1185
@i{shadowed}_3 by a newly created @i{internal symbol}.
1187
@node shadowing-import, delete-package, shadow, Packages Dictionary
1188
@subsection shadowing-import [Function]
1190
@code{shadowing-import} @i{symbols @r{&optional} package} @result{} @i{@b{t}}
1192
@subsubheading Arguments and Values::
1194
@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.
1196
@i{package} ---a @i{package designator}.
1198
The default is the @i{current package}.
1200
@subsubheading Description::
1202
@b{shadowing-import} is like @b{import},
1203
but it does not signal an error even if the importation of a @i{symbol}
1204
would shadow some @i{symbol} already @i{accessible} in @i{package}.
1206
@b{shadowing-import} inserts each of @i{symbols}
1207
into @i{package} as an internal symbol, regardless
1208
of whether another @i{symbol} of the same name is shadowed by this
1210
If a different @i{symbol} of the same name is already @i{present}
1212
that @i{symbol} is first @i{uninterned} from @i{package}.
1213
The new @i{symbol} is added to @i{package}'s shadowing-symbols list.
1215
@b{shadowing-import} does name-conflict
1216
checking to the extent that it checks whether a distinct existing
1217
@i{symbol} with the same name is @i{accessible}; if so, it is shadowed by
1218
the new @i{symbol}, which implies that it must be uninterned
1220
@i{present} in @i{package}.
1222
@subsubheading Examples::
1224
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
1225
(setq sym (intern "CONFLICT")) @result{} CONFLICT
1226
(intern "CONFLICT" (make-package 'temp)) @result{} TEMP::CONFLICT, NIL
1227
(package-shadowing-symbols 'temp) @result{} NIL
1228
(shadowing-import sym 'temp) @result{} T
1229
(package-shadowing-symbols 'temp) @result{} (CONFLICT)
1232
@subsubheading Side Effects::
1234
@b{shadowing-import}
1235
changes the state of the package system in such a way that
1236
the consistency rules do not hold across the change.
1238
@i{package}'s shadowing-symbols list is modified.
1240
@subsubheading Affected By::
1242
Current state of the package system.
1244
@subsubheading See Also::
1250
@ref{package-shadowing-symbols}
1252
@node delete-package, make-package, shadowing-import, Packages Dictionary
1253
@subsection delete-package [Function]
1255
@code{delete-package} @i{package} @result{} @i{generalized-boolean}
1257
@subsubheading Arguments and Values::
1259
@i{package}---a @i{package designator}.
1261
@i{generalized-boolean}---a @i{generalized boolean}.
1263
@subsubheading Description::
1265
@b{delete-package} deletes @i{package} from all package system
1267
If the operation is successful, @b{delete-package} returns
1268
true, otherwise @b{nil}.
1269
The effect of @b{delete-package} is that the name and nicknames
1270
of @i{package} cease to be recognized package names.
1271
The package @i{object} is still a @i{package}
1272
(@i{i.e.}, @b{packagep} is @i{true} of it)
1273
but @b{package-name} returns @b{nil}.
1274
The consequences of deleting the @t{COMMON-LISP} @i{package} or the @t{KEYWORD} @i{package} are undefined.
1275
The consequences of invoking any other package operation on @i{package}
1276
once it has been deleted are unspecified.
1277
In particular, the consequences of invoking @b{find-symbol},
1278
@b{intern} and other functions that look for a symbol name in
1279
a @i{package} are unspecified if they are called with @b{*package*}
1280
bound to the deleted @i{package} or with the deleted @i{package}
1283
If @i{package} is a @i{package} @i{object} that has already
1284
been deleted, @b{delete-package} immediately returns @b{nil}.
1286
After this operation completes, the
1288
of any @i{symbol} whose @i{home package}
1292
@i{implementation-dependent}.
1293
Except for this, @i{symbols} @i{accessible}
1294
in @i{package} are not modified in any other way;
1295
@i{symbols} whose @i{home package} is not @i{package} remain unchanged.
1297
@subsubheading Examples::
1300
(setq *foo-package* (make-package "FOO" :use nil))
1301
(setq *foo-symbol* (intern "FOO" *foo-package*))
1302
(export *foo-symbol* *foo-package*)
1304
(setq *bar-package* (make-package "BAR" :use '("FOO")))
1305
(setq *bar-symbol* (intern "BAR" *bar-package*))
1306
(export *foo-symbol* *bar-package*)
1307
(export *bar-symbol* *bar-package*)
1309
(setq *baz-package* (make-package "BAZ" :use '("BAR")))
1311
(symbol-package *foo-symbol*) @result{} #<PACKAGE "FOO">
1312
(symbol-package *bar-symbol*) @result{} #<PACKAGE "BAR">
1314
(prin1-to-string *foo-symbol*) @result{} "FOO:FOO"
1315
(prin1-to-string *bar-symbol*) @result{} "BAR:BAR"
1317
(find-symbol "FOO" *bar-package*) @result{} FOO:FOO, :EXTERNAL
1319
(find-symbol "FOO" *baz-package*) @result{} FOO:FOO, :INHERITED
1320
(find-symbol "BAR" *baz-package*) @result{} BAR:BAR, :INHERITED
1322
(packagep *foo-package*) @result{} @i{true}
1323
(packagep *bar-package*) @result{} @i{true}
1324
(packagep *baz-package*) @result{} @i{true}
1326
(package-name *foo-package*) @result{} "FOO"
1327
(package-name *bar-package*) @result{} "BAR"
1328
(package-name *baz-package*) @result{} "BAZ"
1330
(package-use-list *foo-package*) @result{} ()
1331
(package-use-list *bar-package*) @result{} (#<PACKAGE "FOO">)
1332
(package-use-list *baz-package*) @result{} (#<PACKAGE "BAR">)
1334
(package-used-by-list *foo-package*) @result{} (#<PACKAGE "BAR">)
1335
(package-used-by-list *bar-package*) @result{} (#<PACKAGE "BAZ">)
1336
(package-used-by-list *baz-package*) @result{} ()
1338
(delete-package *bar-package*)
1339
@t{ |> } Error: Package BAZ uses package BAR.
1340
@t{ |> } If continued, BAZ will be made to unuse-package BAR,
1341
@t{ |> } and then BAR will be deleted.
1342
@t{ |> } Type :CONTINUE to continue.
1343
@t{ |> } Debug> @b{|>>}@t{:CONTINUE}@b{<<|}
1346
(symbol-package *foo-symbol*) @result{} #<PACKAGE "FOO">
1347
(symbol-package *bar-symbol*) is unspecified
1349
(prin1-to-string *foo-symbol*) @result{} "FOO:FOO"
1350
(prin1-to-string *bar-symbol*) is unspecified
1352
(find-symbol "FOO" *bar-package*) is unspecified
1354
(find-symbol "FOO" *baz-package*) @result{} NIL, NIL
1355
(find-symbol "BAR" *baz-package*) @result{} NIL, NIL
1357
(packagep *foo-package*) @result{} T
1358
(packagep *bar-package*) @result{} T
1359
(packagep *baz-package*) @result{} T
1361
(package-name *foo-package*) @result{} "FOO"
1362
(package-name *bar-package*) @result{} NIL
1363
(package-name *baz-package*) @result{} "BAZ"
1365
(package-use-list *foo-package*) @result{} ()
1366
(package-use-list *bar-package*) is unspecified
1367
(package-use-list *baz-package*) @result{} ()
1369
(package-used-by-list *foo-package*) @result{} ()
1370
(package-used-by-list *bar-package*) is unspecified
1371
(package-used-by-list *baz-package*) @result{} ()
1374
@subsubheading Exceptional Situations::
1376
If the @i{package} @i{designator} is a @i{name} that does not
1377
currently name a @i{package},
1378
a @i{correctable} error of @i{type} @b{package-error} is signaled.
1379
If correction is attempted, no deletion action is attempted;
1380
instead, @b{delete-package} immediately returns @b{nil}.
1382
If @i{package} is used by other @i{packages},
1383
a @i{correctable} error of @i{type} @b{package-error} is signaled.
1384
If correction is attempted,
1385
@b{unuse-package} is effectively called to remove any dependencies,
1386
causing @i{package}'s @i{external symbols} to cease being @i{accessible} to those
1387
@i{packages} that use @i{package}.
1388
@b{delete-package} then deletes @i{package} just as it would have had
1389
there been no @i{packages} that used it.
1391
@subsubheading See Also::
1395
@node make-package, with-package-iterator, delete-package, Packages Dictionary
1396
@subsection make-package [Function]
1398
@code{make-package} @i{package-name @r{&key} nicknames use} @result{} @i{package}
1400
@subsubheading Arguments and Values::
1402
@i{package-name}---a @i{string designator}.
1404
@i{nicknames}---a @i{list} of @i{string designators}.
1405
The default is the @i{empty list}.
1408
a @i{list} of @i{package designators}.
1410
The default is @i{implementation-defined}.
1412
@i{package}---a @i{package}.
1414
@subsubheading Description::
1416
Creates a new @i{package} with the name @i{package-name}.
1418
@i{Nicknames} are additional @i{names} which may be used
1419
to refer to the new @i{package}.
1421
@i{use} specifies zero or more @i{packages}
1422
the @i{external symbols} of which are to be inherited by
1423
the new @i{package}. See the @i{function} @b{use-package}.
1425
@subsubheading Examples::
1428
(make-package 'temporary :nicknames '("TEMP" "temp")) @result{} #<PACKAGE "TEMPORARY">
1429
(make-package "OWNER" :use '("temp")) @result{} #<PACKAGE "OWNER">
1430
(package-used-by-list 'temp) @result{} (#<PACKAGE "OWNER">)
1431
(package-use-list 'owner) @result{} (#<PACKAGE "TEMPORARY">)
1434
@subsubheading Affected By::
1436
The existence of other @i{packages} in the system.
1438
@subsubheading Exceptional Situations::
1440
The consequences are unspecified if @i{packages} denoted by @i{use}
1443
A @i{correctable} error is signaled if the @i{package-name}
1444
or any of the @i{nicknames} is already
1445
the @i{name} or @i{nickname} of an existing @i{package}.
1447
@subsubheading See Also::
1453
@subsubheading Notes::
1455
In situations where the @i{packages} to be used contain symbols which would conflict,
1456
it is necessary to first create the package with @t{:use '()},
1457
then to use @b{shadow} or @b{shadowing-import} to address the conflicts,
1458
and then after that to use @b{use-package} once the conflicts have been addressed.
1460
When packages are being created as part of the static definition of a program
1461
rather than dynamically by the program, it is generally considered more stylistically
1462
appropriate to use @b{defpackage} rather than @b{make-package}.
1464
@node with-package-iterator, unexport, make-package, Packages Dictionary
1465
@subsection with-package-iterator [Macro]
1467
@code{with-package-iterator} @i{@r{(}name package-list-form @r{&rest} @r{symbol-types}@r{)}
1468
@{@i{declaration}@}* @{@i{form}@}*}@*
1469
@result{} @i{@{@i{result}@}*}
1471
@subsubheading Arguments and Values::
1473
@i{name}---a @i{symbol}.
1475
@i{package-list-form}---a @i{form}; evaluated once to produce a @i{package-list}.
1477
@i{package-list}---a @i{designator} for a list of @i{package designators}.
1479
@i{symbol-type}---one of the @i{symbols}
1480
@t{:internal}, @t{:external}, or @t{:inherited}.
1482
@i{declaration}---a @b{declare} @i{expression}; not evaluated.
1484
@i{forms}---an @i{implicit progn}.
1486
@i{results}---the @i{values} of the @i{forms}.
1488
@subsubheading Description::
1490
Within the lexical scope of the body @i{forms},
1491
the @i{name} is defined via @b{macrolet}
1492
such that successive invocations of @t{(@i{name})}
1493
will return the @i{symbols}, one by one,
1494
from the @i{packages} in @i{package-list}.
1496
It is unspecified whether @i{symbols} inherited from
1497
multiple @i{packages} are returned more than once.
1498
The order of @i{symbols} returned does not necessarily reflect the order
1499
of @i{packages} in @i{package-list}. When @i{package-list} has
1500
more than one element, it is unspecified whether duplicate @i{symbols} are
1501
returned once or more than once.
1503
@i{Symbol-types} controls which @i{symbols} that are @i{accessible}
1504
in a @i{package} are returned as follows:
1509
The @i{symbols} that are @i{present} in the @i{package},
1510
but that are not @i{exported}.
1513
The @i{symbols} that are @i{present} in the @i{package}
1514
and are @i{exported}.
1516
@item @t{:inherited}
1517
The @i{symbols} that are @i{exported} by used @i{packages}
1518
and that are not @i{shadowed}.
1521
When more than one argument is supplied for @i{symbol-types},
1522
a @i{symbol} is returned if its @i{accessibility} matches
1523
any one of the @i{symbol-types} supplied.
1524
Implementations may extend this syntax by recognizing additional
1525
symbol accessibility types.
1527
An invocation of @t{(@i{name})} returns four values as follows:
1532
A flag that indicates whether a @i{symbol} is returned
1533
(true means that a @i{symbol} is returned).
1535
A @i{symbol} that is @i{accessible} in one the
1536
indicated @i{packages}.
1538
The accessibility type for that @i{symbol};
1539
@i{i.e.}, one of the symbols @t{:internal}, @t{:external}, or @t{:inherited}.
1541
The @i{package} from which the @i{symbol} was obtained.
1542
The @i{package} is one of the @i{packages} present
1543
or named in @i{package-list}.
1546
After all @i{symbols} have been returned by successive invocations of
1547
@t{(@i{name})}, then only one value is returned, namely @b{nil}.
1549
The meaning of the second, third, and fourth @i{values} is that the returned
1550
@i{symbol} is @i{accessible} in the returned @i{package}
1551
in the way indicated by the second return value as follows:
1556
Means @i{present} and not @i{exported}.
1559
Means @i{present} and @i{exported}.
1561
@item @t{:inherited}
1562
Means not @i{present} (thus not @i{shadowed}) but inherited
1563
from some used @i{package}.
1566
It is unspecified what happens if any of the implicit interior state
1567
of an iteration is returned outside the dynamic extent of the
1568
@b{with-package-iterator}
1569
form such as by returning some @i{closure} over the invocation @i{form}.
1571
Any number of invocations of @b{with-package-iterator}
1572
can be nested, and the body of the innermost one can invoke all of the
1573
locally @i{established} @i{macros}, provided all those @i{macros}
1574
have distinct names.
1576
@subsubheading Examples::
1578
The following function should return @b{t} on any @i{package}, and signal
1579
an error if the usage of @b{with-package-iterator} does not agree
1580
with the corresponding usage of @b{do-symbols}.
1583
(defun test-package-iterator (package)
1584
(unless (packagep package)
1585
(setq package (find-package package)))
1586
(let ((all-entries '())
1587
(generated-entries '()))
1588
(do-symbols (x package)
1589
(multiple-value-bind (symbol accessibility)
1590
(find-symbol (symbol-name x) package)
1591
(push (list symbol accessibility) all-entries)))
1592
(with-package-iterator (generator-fn package
1593
:internal :external :inherited)
1595
(multiple-value-bind (more? symbol accessibility pkg)
1597
(unless more? (return))
1598
(let ((l (multiple-value-list (find-symbol (symbol-name symbol)
1600
(unless (equal l (list symbol accessibility))
1601
(error "Symbol ~S not found as ~S in package ~A [~S]"
1602
symbol accessibility (package-name package) l))
1603
(push l generated-entries)))))
1604
(unless (and (subsetp all-entries generated-entries :test #'equal)
1605
(subsetp generated-entries all-entries :test #'equal))
1606
(error "Generated entries and Do-Symbols entries don't correspond"))
1610
The following function prints out every @i{present} @i{symbol}
1611
(possibly more than once):
1614
(defun print-all-symbols ()
1615
(with-package-iterator (next-symbol (list-all-packages)
1616
:internal :external)
1618
(multiple-value-bind (more? symbol) (next-symbol)
1624
@subsubheading Exceptional Situations::
1626
@b{with-package-iterator} signals an error of @i{type} @b{program-error} if
1627
no @i{symbol-types} are supplied or if a @i{symbol-type} is not
1628
recognized by the implementation is supplied.
1630
The consequences are undefined if the local function named @i{name}
1631
@i{established} by @b{with-package-iterator} is called after it
1632
has returned @i{false} as its @i{primary value}.
1634
@subsubheading See Also::
1636
@ref{Traversal Rules and Side Effects}
1638
@node unexport, unintern, with-package-iterator, Packages Dictionary
1639
@subsection unexport [Function]
1641
@code{unexport} @i{symbols @r{&optional} package} @result{} @i{@b{t}}
1643
@subsubheading Arguments and Values::
1645
@i{symbols}---a @i{designator} for a @i{list} of @i{symbols}.
1647
@i{package}---a @i{package designator}.
1649
The default is the @i{current package}.
1651
@subsubheading Description::
1653
@b{unexport} reverts external @i{symbols} in @i{package} to
1654
internal status; it undoes the effect of @b{export}.
1656
@b{unexport} works only on @i{symbols}
1658
in @i{package}, switching them back to internal status.
1659
If @b{unexport} is given a @i{symbol} that is
1660
already @i{accessible} as an @i{internal symbol} in @i{package},
1663
@subsubheading Examples::
1666
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
1667
(export (intern "CONTRABAND" (make-package 'temp)) 'temp) @result{} T
1668
(find-symbol "CONTRABAND") @result{} NIL, NIL
1669
(use-package 'temp) @result{} T
1670
(find-symbol "CONTRABAND") @result{} CONTRABAND, :INHERITED
1671
(unexport 'contraband 'temp) @result{} T
1672
(find-symbol "CONTRABAND") @result{} NIL, NIL
1675
@subsubheading Side Effects::
1677
Package system is modified.
1679
@subsubheading Affected By::
1681
Current state of the package system.
1683
@subsubheading Exceptional Situations::
1685
If @b{unexport} is given a @i{symbol}
1686
not @i{accessible} in @i{package} at all,
1687
an error of @i{type} @b{package-error} is signaled.
1689
The consequences are undefined if @i{package} is the @t{KEYWORD} @i{package}
1690
or the @t{COMMON-LISP} @i{package}.
1692
@subsubheading See Also::
1695
, @ref{Package Concepts}
1697
@node unintern, in-package, unexport, Packages Dictionary
1698
@subsection unintern [Function]
1700
@code{unintern} @i{symbol @r{&optional} package} @result{} @i{generalized-boolean}
1702
@subsubheading Arguments and Values::
1704
@i{symbol}---a @i{symbol}.
1706
@i{package}---a @i{package designator}.
1708
The default is the @i{current package}.
1710
@i{generalized-boolean}---a @i{generalized boolean}.
1712
@subsubheading Description::
1713
@b{unintern} removes @i{symbol} from @i{package}.
1714
If @i{symbol} is @i{present} in @i{package}, it is
1715
removed from @i{package} and also from @i{package}'s
1716
@i{shadowing symbols list} if it is present there. If @i{package} is the
1717
@i{home package} for @i{symbol}, @i{symbol} is made to have no
1719
@i{Symbol} may continue to be @i{accessible}
1720
in @i{package} by inheritance.
1722
Use of @b{unintern} can result in a @i{symbol}
1724
recorded @i{home package},
1725
but that in fact is @i{accessible} in some @i{package}.
1726
@r{Common Lisp} does not check for this pathological case,
1727
and such @i{symbols}
1728
are always printed preceded by @t{#:}.
1730
@b{unintern} returns @i{true} if it removes @i{symbol}, and @b{nil} otherwise.
1732
@subsubheading Examples::
1735
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
1736
(setq temps-unpack (intern "UNPACK" (make-package 'temp))) @result{} TEMP::UNPACK
1737
(unintern temps-unpack 'temp) @result{} T
1738
(find-symbol "UNPACK" 'temp) @result{} NIL, NIL
1739
temps-unpack @result{} #:UNPACK
1742
@subsubheading Side Effects::
1744
@b{unintern} changes the state of the
1745
package system in such a way that the consistency rules do not hold
1748
@subsubheading Affected By::
1749
Current state of the package system.
1751
@subsubheading Exceptional Situations::
1752
Giving a shadowing symbol to @b{unintern}
1753
can uncover a name conflict that had
1754
previously been resolved by the shadowing. If package A uses packages
1755
B and C, A contains a shadowing symbol @t{x}, and B and C each contain external
1756
symbols named @t{x}, then removing the shadowing symbol @t{x}
1757
from A will reveal a name
1758
conflict between @t{b:x} and @t{c:x} if those two @i{symbols} are distinct.
1759
In this case @b{unintern} will signal an error.
1761
@subsubheading See Also::
1763
@ref{Package Concepts}
1765
@node in-package, unuse-package, unintern, Packages Dictionary
1766
@subsection in-package [Macro]
1768
@code{in-package} @i{name} @result{} @i{package}
1770
@subsubheading Arguments and Values::
1772
@i{name}---a @i{string designator}; not evaluated.
1774
@i{package}---the @i{package} named by @i{name}.
1776
@subsubheading Description::
1778
Causes the the @i{package} named by @i{name}
1779
to become the @i{current package}---that is, the @i{value} of @b{*package*}.
1780
If no such @i{package} already exists, an error of @i{type} @b{package-error} is signaled.
1782
Everything @b{in-package} does is also performed at compile time
1783
if the call appears as a @i{top level form}.
1785
@subsubheading Side Effects::
1787
The @i{variable} @b{*package*} is assigned.
1788
If the @b{in-package} @i{form} is a @i{top level form},
1789
this assignment also occurs at compile time.
1791
@subsubheading Exceptional Situations::
1793
An error of @i{type} @b{package-error} is signaled if the specified @i{package} does not exist.
1795
@subsubheading See Also::
1799
@node unuse-package, use-package, in-package, Packages Dictionary
1800
@subsection unuse-package [Function]
1802
@code{unuse-package} @i{packages-to-unuse @r{&optional} package} @result{} @i{@b{t}}
1804
@subsubheading Arguments and Values::
1806
@i{packages-to-unuse}---a @i{designator} for
1807
a @i{list} of @i{package designators}.
1809
@i{package}---a @i{package designator}.
1810
The default is the @i{current package}.
1812
@subsubheading Description::
1814
@b{unuse-package} causes @i{package} to cease inheriting
1815
all the @i{external symbols} of
1816
@i{packages-to-unuse}; @b{unuse-package} undoes
1817
the effects of @b{use-package}. The
1818
@i{packages-to-unuse}
1819
are removed from the @i{use list} of @i{package}.
1821
Any @i{symbols} that have been
1822
@i{imported} into @i{package} continue to be @i{present} in @i{package}.
1824
@subsubheading Examples::
1827
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
1828
(export (intern "SHOES" (make-package 'temp)) 'temp) @result{} T
1829
(find-symbol "SHOES") @result{} NIL, NIL
1830
(use-package 'temp) @result{} T
1831
(find-symbol "SHOES") @result{} SHOES, :INHERITED
1832
(find (find-package 'temp) (package-use-list 'common-lisp-user)) @result{} #<PACKAGE "TEMP">
1833
(unuse-package 'temp) @result{} T
1834
(find-symbol "SHOES") @result{} NIL, NIL
1837
@subsubheading Side Effects::
1839
The @i{use list} of @i{package} is modified.
1841
@subsubheading Affected By::
1842
Current state of the package system.
1844
@subsubheading See Also::
1848
@ref{package-use-list}
1850
@node use-package, defpackage, unuse-package, Packages Dictionary
1851
@subsection use-package [Function]
1853
@code{use-package} @i{packages-to-use @r{&optional} package} @result{} @i{@b{t}}
1855
@subsubheading Arguments and Values::
1857
@i{packages-to-use}---a @i{designator} for
1858
a @i{list} of @i{package designators}.
1859
The @t{KEYWORD} @i{package} may not be supplied.
1861
@i{package}---a @i{package designator}.
1862
The @t{KEYWORD} @i{package} cannot be supplied.
1863
The default is the @i{current package}.
1865
@subsubheading Description::
1867
@b{use-package} causes @i{package} to inherit all the
1868
@i{external symbols} of @i{packages-to-use}.
1869
The inherited @i{symbols} become @i{accessible} as
1870
@i{internal symbols} of @i{package}.
1872
@i{Packages-to-use} are added to the @i{use list} of @i{package}
1873
if they are not there already. All @i{external symbols} in
1874
@i{packages-to-use} become @i{accessible} in @i{package}
1875
as @i{internal symbols}.
1876
@b{use-package} does not cause any new @i{symbols} to be @i{present}
1877
in @i{package} but only makes them @i{accessible} by inheritance.
1879
@b{use-package} checks for
1880
name conflicts between the newly imported symbols and those already
1881
@i{accessible} in @i{package}.
1882
A name conflict in @b{use-package}
1883
between two external symbols inherited
1884
by @i{package} from @i{packages-to-use} may be resolved in favor of
1886
by @i{importing} one of them into @i{package} and making it a
1889
@subsubheading Examples::
1892
(export (intern "LAND-FILL" (make-package 'trash)) 'trash) @result{} T
1893
(find-symbol "LAND-FILL" (make-package 'temp)) @result{} NIL, NIL
1894
(package-use-list 'temp) @result{} (#<PACKAGE "TEMP">)
1895
(use-package 'trash 'temp) @result{} T
1896
(package-use-list 'temp) @result{} (#<PACKAGE "TEMP"> #<PACKAGE "TRASH">)
1897
(find-symbol "LAND-FILL" 'temp) @result{} TRASH:LAND-FILL, :INHERITED
1900
@subsubheading Side Effects::
1902
The @i{use list} of @i{package} may be modified.
1904
@subsubheading See Also::
1908
@ref{package-use-list}
1910
@ref{Package Concepts}
1912
@subsubheading Notes::
1914
It is permissible for a @i{package} P_1
1915
to @i{use} a @i{package} P_2
1916
even if P_2 already uses P_1.
1917
The using of @i{packages} is not transitive,
1918
so no problem results from the apparent circularity.
1920
@node defpackage, do-symbols, use-package, Packages Dictionary
1921
@subsection defpackage [Macro]
1923
@code{defpackage} @i{defined-package-name [[!@i{option}]]} @result{} @i{package}
1925
@w{@i{option} ::=@{@r{(}@t{:nicknames} @{@i{nickname}@}*@r{)}@}* | }
1926
@w{ @r{(}@t{:documentation} @i{string}@r{)} | }
1927
@w{ @{@r{(}@t{:use} @{@i{package-name}@}*@r{)}@}* | }
1928
@w{ @{@r{(}@t{:shadow} @{!@i{symbol-name}@}*@r{)}@}* | }
1929
@w{ @{@r{(}@t{:shadowing-import-from} @i{package-name} @{!@i{symbol-name}@}*@r{)}@}* | }
1930
@w{ @{@r{(}@t{:import-from} @i{package-name} @{!@i{symbol-name}@}*@r{)}@}* | }
1931
@w{ @{@r{(}@t{:export} @{!@i{symbol-name}@}*@r{)}@}* | }
1932
@w{ @{@r{(}@t{:intern} @{!@i{symbol-name}@}*@r{)}@}* | }
1933
@w{ @r{(}@t{:size} @i{integer}@r{)}}
1935
@w{@i{symbol-name} ::=(@i{symbol} | @i{string})}
1937
@subsubheading Arguments and Values::
1939
@i{defined-package-name}---a @i{string designator}.
1941
@i{package-name}---a @i{package designator}.
1943
@i{nickname}---a @i{string designator}.
1945
@i{symbol-name}---a @i{string designator}.
1947
@i{package}---the @i{package} named @i{package-name}.
1949
@subsubheading Description::
1951
@b{defpackage} creates a @i{package} as specified and returns
1954
If @i{defined-package-name} already refers to an existing
1955
@i{package}, the name-to-package mapping for that name is not changed.
1956
If the new definition is at variance with the current state of that
1957
@i{package}, the consequences are undefined; an implementation
1958
might choose to modify the existing @i{package} to reflect the
1959
new definition. If @i{defined-package-name} is a @i{symbol},
1960
its @i{name} is used.
1962
The standard @i{options} are described below.
1966
@item @t{:nicknames}
1967
The arguments to @t{:nicknames} set the @i{package}'s nicknames to the
1970
@item @t{:documentation}
1971
The argument to @t{:documentation} specifies a @i{documentation string};
1972
it is attached as a @i{documentation string} to the @i{package}.
1973
At most one @t{:documentation} option
1974
can appear in a single @b{defpackage} @i{form}.
1977
The arguments to @t{:use} set the @i{packages} that the @i{package}
1978
named by @i{package-name}
1979
will inherit from. If @t{:use} is not supplied,
1981
it defaults to the same @i{implementation-dependent} value as the @t{:use} @i{argument} to
1985
The arguments to @t{:shadow}, @i{symbol-names}, name @i{symbols}
1986
that are to be created in the @i{package} being defined.
1987
These @i{symbols} are added to the list of shadowing
1988
@i{symbols} effectively as if by @b{shadow}.
1990
@item @t{:shadowing-import-from}
1991
The @i{symbols} named by the argument @i{symbol-names}
1992
are found (involving a lookup as if by @b{find-symbol})
1993
in the specified @i{package-name}. The resulting @i{symbols}
1994
are @i{imported} into the @i{package} being defined, and
1995
placed on the shadowing symbols list as if by @b{shadowing-import}.
1996
In no case are @i{symbols} created in any @i{package}
1997
other than the one being defined.
1999
@item @t{:import-from}
2000
The @i{symbols} named by the argument @i{symbol-names}
2001
are found in the @i{package} named by @i{package-name} and
2002
they are @i{imported} into the @i{package} being defined.
2003
In no case are @i{symbols} created in any @i{package}
2004
other than the one being defined.
2007
The @i{symbols} named by
2008
the argument @i{symbol-names} are found
2009
or created in the @i{package} being defined
2011
The @t{:export} option interacts
2012
with the @t{:use} option, since inherited @i{symbols}
2013
can be used rather than new ones created.
2014
The @t{:export} option interacts
2016
@t{:import-from} and @t{:shadowing-import-from} options, since
2018
symbols can be used rather than new ones created.
2019
If an argument to the @t{:export} option is @i{accessible} as
2020
an (inherited) @i{internal symbol} via @b{use-package}, that the
2021
@i{symbol} named by @i{symbol-name}
2022
is first @i{imported} into the @i{package} being
2023
defined, and is then @i{exported} from that @i{package}.
2026
The @i{symbols} named by the argument @i{symbol-names}
2027
are found or created in the @i{package} being defined.
2028
The @t{:intern} option interacts with the
2029
@t{:use} option, since inherited @i{symbols}
2030
can be used rather than new ones created.
2033
The argument to the @t{:size} option
2034
declares the approximate number of @i{symbols} expected in the
2036
This is an efficiency hint only and might be ignored by an
2040
The order in which the options appear in a
2041
@b{defpackage} form is irrelevant.
2042
The order in which they are executed is as follows:
2046
@t{:shadow} and @t{:shadowing-import-from}.
2050
@t{:import-from} and @t{:intern}.
2055
Shadows are established first, since they might be necessary to block
2056
spurious name conflicts when the @t{:use}
2057
option is processed. The @t{:use} option is executed
2058
next so that @t{:intern} and @t{:export} options can refer to normally
2059
inherited @i{symbols}.
2060
The @t{:export} option is executed last so that it can refer to
2061
@i{symbols} created by any of the other options; in
2062
particular, @i{shadowing symbols} and
2063
@i{imported} @i{symbols} can be made external.
2065
If a @i{defpackage} @i{form} appears as a @i{top level form},
2066
all of the actions normally performed by this @i{macro}
2067
at load time must also be performed at compile time.
2069
@subsubheading Examples::
2072
(defpackage "MY-PACKAGE"
2073
(:nicknames "MYPKG" "MY-PKG")
2074
(:use "COMMON-LISP")
2075
(:shadow "CAR" "CDR")
2076
(:shadowing-import-from "VENDOR-COMMON-LISP" "CONS")
2077
(:import-from "VENDOR-COMMON-LISP" "GC")
2078
(:export "EQ" "CONS" "FROBOLA")
2081
(defpackage my-package
2082
(:nicknames mypkg :MY-PKG) ; remember Common Lisp conventions for case
2083
(:use common-lisp) ; conversion on symbols
2084
(:shadow CAR :cdr #:cons)
2085
(:export "CONS") ; this is the shadowed one.
2089
@subsubheading Affected By::
2091
Existing @i{packages}.
2093
@subsubheading Exceptional Situations::
2095
If one of the supplied @t{:nicknames} already
2096
refers to an existing @i{package},
2097
an error of @i{type} @b{package-error} is signaled.
2099
An error of @i{type} @b{program-error} should be signaled if @t{:size} or @t{:documentation}
2100
appears more than once.
2102
Since @i{implementations} might allow extended @i{options}
2103
an error of @i{type} @b{program-error} should be signaled
2104
if an @i{option} is present that is not
2105
actually supported in the host @i{implementation}.
2107
The collection of @i{symbol-name} arguments given to the options
2108
@t{:shadow}, @t{:intern},
2109
@t{:import-from}, and @t{:shadowing-import-from} must
2110
all be disjoint; additionally, the @i{symbol-name} arguments given to
2111
@t{:export} and @t{:intern}
2113
Disjoint in this context is defined as no two of the @i{symbol-names}
2114
being @b{string=} with each other. If either condition is
2115
violated, an error of @i{type} @b{program-error} should be signaled.
2117
For the @t{:shadowing-import-from} and @t{:import-from} options,
2118
a @i{correctable} @i{error} of @i{type} @b{package-error}
2119
is signaled if no @i{symbol} is
2120
@i{accessible} in the @i{package} named by
2121
@i{package-name} for one of the argument @i{symbol-names}.
2123
Name conflict errors are handled by the underlying calls to
2124
@b{make-package}, @b{use-package}, @b{import}, and
2125
@b{export}. See @ref{Package Concepts}.
2127
@subsubheading See Also::
2131
@ref{Package Concepts},
2134
@subsubheading Notes::
2136
The @t{:intern} option is useful if an @t{:import-from} or a
2137
@t{:shadowing-import-from} option in a subsequent call to @b{defpackage}
2138
(for some other @i{package}) expects to find
2139
these @i{symbols} @i{accessible} but not necessarily external.
2141
It is recommended that the entire @i{package} definition is put
2142
in a single place, and that all the @i{package} definitions of a
2143
program are in a single file. This file can be @i{loaded} before
2144
@i{loading} or compiling anything else that depends on those
2145
@i{packages}. Such a file can be read in the @t{COMMON-LISP-USER} @i{package},
2146
avoiding any initial state issues.
2148
@b{defpackage} cannot be used to create two ``mutually
2149
recursive'' packages, such as:
2152
(defpackage my-package
2153
(:use common-lisp your-package) ;requires your-package to exist first
2155
(defpackage your-package
2157
(:import-from my-package "MY-FUN") ;requires my-package to exist first
2161
However, nothing prevents the user from using the
2162
@i{package}-affecting functions
2163
such as @b{use-package},
2164
@b{import}, and @b{export} to establish such links
2165
after a more standard use of @b{defpackage}.
2167
The macroexpansion of @b{defpackage}
2168
could usefully canonicalize the names
2170
so that even if a source file has random @i{symbols} in the
2171
@b{defpackage} form, the compiled file would only contain
2174
Frequently additional @i{implementation-dependent} options take the
2175
form of a @i{keyword} standing by itself as an abbreviation for a list
2176
@t{(keyword T)}; this syntax should be properly reported as an unrecognized
2177
option in implementations that do not support it.
2179
@node do-symbols, intern, defpackage, Packages Dictionary
2180
@subsection do-symbols, do-external-symbols, do-all-symbols [Macro]
2182
@code{do-symbols} @i{@r{(}var @r{[}package @r{[}result-form@r{]}@r{]}@r{)}
2183
@{@i{declaration}@}*
2184
@{tag | statement@}*}@*
2185
@result{} @i{@{@i{result}@}*}
2187
@code{do-external-symbols} @i{@r{(}var @r{[}package @r{[}result-form@r{]}@r{]}@r{)}
2188
@{@i{declaration}@}*
2189
@{tag | statement@}*}@*
2190
@result{} @i{@{@i{result}@}*}
2192
@code{do-all-symbols} @i{@r{(}var @r{[}result-form@r{]}@r{)}
2193
@{@i{declaration}@}*
2194
@{tag | statement@}*}@*
2195
@result{} @i{@{@i{result}@}*}
2197
@subsubheading Arguments and Values::
2199
@i{var}---a @i{variable} @i{name}; not evaluated.
2201
@i{package}---a @i{package designator}; evaluated.
2203
The default in @b{do-symbols} and @b{do-external-symbols} is the @i{current package}.
2205
@i{result-form}---a @i{form}; evaluated as described below.
2206
The default is @b{nil}.
2208
@i{declaration}---a @b{declare} @i{expression}; not evaluated.
2210
@i{tag}---a @i{go tag}; not evaluated.
2212
@i{statement}---a @i{compound form}; evaluated as described below.
2214
@i{results}---the @i{values} returned by the @i{result-form}
2215
if a @i{normal return} occurs,
2216
or else, if an @i{explicit return} occurs, the @i{values} that were transferred.
2218
@subsubheading Description::
2221
@b{do-external-symbols}, and
2222
@b{do-all-symbols} iterate over the @i{symbols}
2224
For each @i{symbol} in the set of @i{packages} chosen,
2225
the @i{var} is bound to the @i{symbol},
2226
and the @i{statements} in the body are executed.
2227
When all the @i{symbols} have been processed,
2228
@i{result-form} is evaluated and returned as the value of the macro.
2230
@b{do-symbols} iterates
2231
over the @i{symbols} @i{accessible} in
2234
@i{Statements} may execute more than once for @i{symbols}
2235
that are inherited from multiple @i{packages}.
2237
@b{do-all-symbols} iterates on every @i{registered package}.
2238
@b{do-all-symbols} will not process every @i{symbol}
2239
whatsoever, because a @i{symbol} not @i{accessible} in any
2240
@i{registered package} will not be processed.
2241
@b{do-all-symbols} may cause a @i{symbol} that is @i{present} in
2242
several @i{packages} to be processed more than once.
2244
@b{do-external-symbols} iterates on the external symbols of @i{package}.
2246
When @i{result-form} is evaluated, @i{var} is bound and has the value @b{nil}.
2248
An @i{implicit block} named @b{nil} surrounds the entire @b{do-symbols},
2249
@b{do-external-symbols}, or @b{do-all-symbols} @i{form}.
2251
@b{return} or @b{return-from} may be used to terminate the
2252
iteration prematurely.
2254
If execution of the body affects which @i{symbols}
2255
are contained in the set of @i{packages} over which iteration
2256
is occurring, other than to
2257
remove the @i{symbol}
2258
currently the value of @i{var} by using @b{unintern},
2259
the consequences are undefined.
2261
For each of these macros, the
2262
@i{scope} of the name binding does not include any
2263
initial value form, but the optional result forms are included.
2265
Any @i{tag} in the body is treated as with @b{tagbody}.
2267
@subsubheading Examples::
2270
(make-package 'temp :use nil) @result{} #<PACKAGE "TEMP">
2271
(intern "SHY" 'temp) @result{} TEMP::SHY, NIL ;SHY will be an internal symbol
2272
;in the package TEMP
2273
(export (intern "BOLD" 'temp) 'temp) @result{} T ;BOLD will be external
2275
(do-symbols (s (find-package 'temp)) (push s lst))
2277
@result{} (TEMP::SHY TEMP:BOLD)
2278
@i{OR}@result{} (TEMP:BOLD TEMP::SHY)
2280
(do-external-symbols (s (find-package 'temp) lst) (push s lst))
2282
@result{} (TEMP:BOLD)
2284
(do-all-symbols (s lst)
2285
(when (eq (find-package 'temp) (symbol-package s)) (push s lst)))
2287
@result{} (TEMP::SHY TEMP:BOLD)
2288
@i{OR}@result{} (TEMP:BOLD TEMP::SHY)
2291
@subsubheading See Also::
2298
@ref{Traversal Rules and Side Effects}
2300
@node intern, package-name, do-symbols, Packages Dictionary
2301
@subsection intern [Function]
2303
@code{intern} @i{string @r{&optional} package} @result{} @i{symbol, status}
2305
@subsubheading Arguments and Values::
2307
@i{string}---a @i{string}.
2309
@i{package}---a @i{package designator}.
2311
The default is the @i{current package}.
2313
@i{symbol}---a @i{symbol}.
2315
@i{status}---one of @t{:inherited}, @t{:external}, @t{:internal}, or @b{nil}.
2317
@subsubheading Description::
2319
@b{intern} enters a @i{symbol} named @i{string} into @i{package}.
2320
If a @i{symbol} whose name is the same as @i{string}
2321
is already @i{accessible} in @i{package}, it is returned.
2322
If no such @i{symbol} is @i{accessible} in @i{package},
2323
a new @i{symbol} with the given name is created
2324
and entered into @i{package} as an @i{internal symbol},
2325
or as an @i{external symbol} if the @i{package} is the @t{KEYWORD} @i{package};
2326
@i{package} becomes the @i{home package} of the created @i{symbol}.
2328
The first value returned by @b{intern}, @i{symbol},
2329
is the @i{symbol} that was found or
2331
The meaning of the @i{secondary value}, @i{status}, is as follows:
2335
The @i{symbol} was found
2337
@i{present} in @i{package} as an @i{internal symbol}.
2340
The @i{symbol} was found
2342
@i{present} as an @i{external symbol}.
2344
@item @t{:inherited}
2345
The @i{symbol} was found
2346
and is inherited via @b{use-package}
2347
(which implies that the @i{symbol} is internal).
2350
No pre-existing @i{symbol} was found,
2353
It is @i{implementation-dependent} whether the @i{string}
2354
that becomes the new @i{symbol}'s @i{name} is the given
2355
@i{string} or a copy of it. Once a @i{string}
2356
has been given as the @i{string} @i{argument} to
2357
@i{intern} in this situation where a new @i{symbol} is created,
2358
the consequences are undefined if a
2359
subsequent attempt is made to alter that @i{string}.
2363
@subsubheading Examples::
2366
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
2367
(intern "Never-Before") @result{} |Never-Before|, NIL
2368
(intern "Never-Before") @result{} |Never-Before|, :INTERNAL
2369
(intern "NEVER-BEFORE" "KEYWORD") @result{} :NEVER-BEFORE, NIL
2370
(intern "NEVER-BEFORE" "KEYWORD") @result{} :NEVER-BEFORE, :EXTERNAL
2373
@subsubheading See Also::
2382
@ref{Symbols as Tokens}
2384
@subsubheading Notes::
2386
@b{intern} does not need to do any name conflict checking
2387
because it never creates a new @i{symbol}
2388
if there is already an @i{accessible} @i{symbol} with the name given.
2390
@node package-name, package-nicknames, intern, Packages Dictionary
2391
@subsection package-name [Function]
2393
@code{package-name} @i{package} @result{} @i{name}
2395
@subsubheading Arguments and Values::
2397
@i{package}---a @i{package designator}.
2399
@i{name}---a @i{string}
2403
@subsubheading Description::
2405
@b{package-name} returns the @i{string} that names @i{package},
2407
or @b{nil} if the @i{package} @i{designator}
2408
is a @i{package} @i{object} that has no name (see the @i{function} @b{delete-package}).
2410
@subsubheading Examples::
2413
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
2414
(package-name *package*) @result{} "COMMON-LISP-USER"
2415
(package-name (symbol-package :test)) @result{} "KEYWORD"
2416
(package-name (find-package 'common-lisp)) @result{} "COMMON-LISP"
2420
(defvar *foo-package* (make-package "FOO"))
2421
(rename-package "FOO" "FOO0")
2422
(package-name *foo-package*) @result{} "FOO0"
2425
@subsubheading Exceptional Situations::
2427
Should signal an error of @i{type} @b{type-error}
2428
if @i{package} is not a @i{package designator}.
2430
@node package-nicknames, package-shadowing-symbols, package-name, Packages Dictionary
2431
@subsection package-nicknames [Function]
2433
@code{package-nicknames} @i{package} @result{} @i{nicknames}
2435
@subsubheading Arguments and Values::
2437
@i{package}---a @i{package designator}.
2439
@i{nicknames}---a @i{list} of @i{strings}.
2441
@subsubheading Description::
2443
Returns the @i{list} of nickname @i{strings}
2444
for @i{package}, not including the name of @i{package}.
2446
@subsubheading Examples::
2449
(package-nicknames (make-package 'temporary
2450
:nicknames '("TEMP" "temp")))
2451
@result{} ("temp" "TEMP")
2454
@subsubheading Exceptional Situations::
2456
Should signal an error of @i{type} @b{type-error}
2457
if @i{package} is not a @i{package designator}.
2459
@node package-shadowing-symbols, package-use-list, package-nicknames, Packages Dictionary
2460
@subsection package-shadowing-symbols [Function]
2462
@code{package-shadowing-symbols} @i{package} @result{} @i{symbols}
2464
@subsubheading Arguments and Values::
2466
@i{package}---a @i{package designator}.
2468
@i{symbols}---a @i{list} of @i{symbols}.
2470
@subsubheading Description::
2472
Returns a @i{list} of @i{symbols} that have been declared
2473
as @i{shadowing symbols} in @i{package} by @b{shadow}
2474
or @b{shadowing-import} (or the equivalent @b{defpackage} options).
2475
All @i{symbols} on this @i{list} are @i{present} in @i{package}.
2477
@subsubheading Examples::
2480
(package-shadowing-symbols (make-package 'temp)) @result{} ()
2481
(shadow 'cdr 'temp) @result{} T
2482
(package-shadowing-symbols 'temp) @result{} (TEMP::CDR)
2483
(intern "PILL" 'temp) @result{} TEMP::PILL, NIL
2484
(shadowing-import 'pill 'temp) @result{} T
2485
(package-shadowing-symbols 'temp) @result{} (PILL TEMP::CDR)
2488
@subsubheading Exceptional Situations::
2490
Should signal an error of @i{type} @b{type-error}
2491
if @i{package} is not a @i{package designator}.
2493
@subsubheading See Also::
2497
@ref{shadowing-import}
2499
@subsubheading Notes::
2501
Whether the list of @i{symbols} is @i{fresh} is @i{implementation-dependent}.
2503
@node package-use-list, package-used-by-list, package-shadowing-symbols, Packages Dictionary
2504
@subsection package-use-list [Function]
2506
@code{package-use-list} @i{package} @result{} @i{use-list}
2508
@subsubheading Arguments and Values::
2510
@i{package}---a @i{package designator}.
2512
@i{use-list}---a @i{list} of @i{package} @i{objects}.
2514
@subsubheading Description::
2516
Returns a @i{list} of other @i{packages} used by @i{package}.
2518
@subsubheading Examples::
2521
(package-use-list (make-package 'temp)) @result{} (#<PACKAGE "COMMON-LISP">)
2522
(use-package 'common-lisp-user 'temp) @result{} T
2523
(package-use-list 'temp) @result{} (#<PACKAGE "COMMON-LISP"> #<PACKAGE "COMMON-LISP-USER">)
2526
@subsubheading Exceptional Situations::
2528
Should signal an error of @i{type} @b{type-error}
2529
if @i{package} is not a @i{package designator}.
2531
@subsubheading See Also::
2537
@node package-used-by-list, packagep, package-use-list, Packages Dictionary
2538
@subsection package-used-by-list [Function]
2540
@code{package-used-by-list} @i{package} @result{} @i{used-by-list}
2542
@subsubheading Arguments and Values::
2544
@i{package}---a @i{package designator}.
2546
@i{used-by-list}---a @i{list} of @i{package} @i{objects}.
2548
@subsubheading Description::
2550
@b{package-used-by-list} returns a @i{list}
2551
of other @i{packages} that use @i{package}.
2553
@subsubheading Examples::
2556
(package-used-by-list (make-package 'temp)) @result{} ()
2557
(make-package 'trash :use '(temp)) @result{} #<PACKAGE "TRASH">
2558
(package-used-by-list 'temp) @result{} (#<PACKAGE "TRASH">)
2561
@subsubheading Exceptional Situations::
2563
Should signal an error of @i{type} @b{type-error}
2564
if @i{package} is not a @i{package}.
2566
@subsubheading See Also::
2572
@node packagep, *package*, package-used-by-list, Packages Dictionary
2573
@subsection packagep [Function]
2575
@code{packagep} @i{object} @result{} @i{generalized-boolean}
2577
@subsubheading Arguments and Values::
2579
@i{object}---an @i{object}.
2581
@i{generalized-boolean}---a @i{generalized boolean}.
2583
@subsubheading Description::
2585
Returns @i{true} if @i{object} is of @i{type} @b{package};
2586
otherwise, returns @i{false}.
2588
@subsubheading Examples::
2590
(packagep *package*) @result{} @i{true}
2591
(packagep 'common-lisp) @result{} @i{false}
2592
(packagep (find-package 'common-lisp)) @result{} @i{true}
2595
@subsubheading Notes::
2598
(packagep @i{object}) @equiv{} (typep @i{object} 'package)
2601
@node *package*, package-error, packagep, Packages Dictionary
2602
@subsection *package* [Variable]
2604
@subsubheading Value Type::
2606
a @i{package} @i{object}.
2608
@subsubheading Initial Value::
2610
the @t{COMMON-LISP-USER} @i{package}.
2612
@subsubheading Description::
2614
Whatever @i{package} @i{object} is currently
2615
the @i{value} of @b{*package*} is referred to as the @i{current package}.
2617
@subsubheading Examples::
2620
(in-package "COMMON-LISP-USER") @result{} #<PACKAGE "COMMON-LISP-USER">
2621
*package* @result{} #<PACKAGE "COMMON-LISP-USER">
2622
(make-package "SAMPLE-PACKAGE" :use '("COMMON-LISP"))
2623
@result{} #<PACKAGE "SAMPLE-PACKAGE">
2626
(let ((*package* (find-package 'sample-package)))
2627
(setq *some-symbol* (read-from-string "just-testing"))))
2629
@result{} (#<PACKAGE "SAMPLE-PACKAGE"> #<PACKAGE "COMMON-LISP-USER">)
2630
(list (symbol-package (read-from-string "just-testing"))
2632
@result{} (#<PACKAGE "COMMON-LISP-USER"> #<PACKAGE "COMMON-LISP-USER">)
2633
(eq 'foo (intern "FOO")) @result{} @i{true}
2634
(eq 'foo (let ((*package* (find-package 'sample-package)))
2639
@subsubheading Affected By::
2645
@subsubheading See Also::
2655
@node package-error, package-error-package, *package*, Packages Dictionary
2656
@subsection package-error [Condition Type]
2658
@subsubheading Class Precedence List::
2661
@b{serious-condition},
2665
@subsubheading Description::
2667
The @i{type} @b{package-error} consists of @i{error} @i{conditions}
2668
related to operations on @i{packages}.
2669
The offending @i{package} (or @i{package} @i{name})
2670
is initialized by the @t{:package} initialization argument to @b{make-condition},
2671
and is @i{accessed} by the @i{function} @b{package-error-package}.
2673
@subsubheading See Also::
2675
@ref{package-error-package}
2679
@node package-error-package, , package-error, Packages Dictionary
2680
@subsection package-error-package [Function]
2682
@code{package-error-package} @i{condition} @result{} @i{package}
2684
@subsubheading Arguments and Values::
2686
@i{condition}---a @i{condition} of @i{type} @b{package-error}.
2688
@i{package}---a @i{package designator}.
2690
@subsubheading Description::
2692
Returns a @i{designator} for the offending @i{package}
2693
in the @i{situation} represented by the @i{condition}.
2695
@subsubheading Examples::
2698
(package-error-package
2699
(make-condition 'package-error
2700
:package (find-package "COMMON-LISP")))
2701
@result{} #<Package "COMMON-LISP">
2704
@subsubheading See Also::
2708
@c end of including dict-packages
2710
@c %**end of chapter
added
removed
info/chap-11.texi
