Fix bugs reported by Fengjing Xiao
[clqr.git] / clqr-packages-and-symbols.tex
blob4e25cbdfdf142583967ba1036f242e3c8366466c
1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2018
2 % Bert Burgemeister
4 % Permission is granted to copy, distribute and/or modify this
5 % document under the terms of the GNU Free Documentation License,
6 % Version 1.2; with no Invariant Sections, no Front-Cover Texts and
7 % no Back-Cover Texts. For details see file COPYING.
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Packages and Symbols}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13 The Loop Facility provides additional means of symbol handling; see \kwd{loop}, page \pageref{section:Loop Facility}.
15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16 \subsection{Predicates}
17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 \begin{LIST}{1cm}
20 \IT{\arrGOO{(\FU*{SYMBOLP} \VAR{ foo})\\
21 (\FU*{PACKAGEP} \VAR{ foo})\\
22 (\FU*{KEYWORDP} \VAR{ foo})}{.}}
24 \retval{\T} if \VAR{foo} is of indicated type.
27 \end{LIST}
30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
31 \subsection{Packages}
32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
33 \begin{LIST}{1cm}
35 \IT{\kwd*{:}\VAR{bar}\XOR\kwd*{keyword}\kwd{:}\VAR{bar}}
37 Keyword, evaluates to \retval{:\VAR{bar}}.
40 \IT{\VAR{package}\kwd*{:}\VAR{symbol}}
42 Exported \VAR{symbol} of \VAR{package}.
45 \IT{\VAR{package}\kwd*{::}\VAR{symbol}}
47 Possibly unexported \VAR{symbol} of \VAR{package}.
50 \IT{(\MC*{DEFPACKAGE}\VAR{ foo}
51 \orGOO{%
52 \OPn{(\kwd{:nicknames }\OPn{\VAR{nick}})}\\
53 (\kwd{:documentation }\VAR{string})\\
54 \OPn{(\kwd{:intern }\OPn{\VAR{interned-symbol}})}\\
55 \OPn{(\kwd{:use }\OPn{\VAR{used-package}})}\\
56 \OPn{(\kwd{:import-from }\VAR{pkg } \OPn{\VAR{imported-symbol}})}\\
57 \OPn{(\kwd{:shadowing-import-from}\VAR{ pkg}\OPn{\VAR{ shd-symbol}})}\\
58 \OPn{(\kwd{:shadow }\OPn{\VAR{shd-symbol}})}\\
59 \OPn{(\kwd{:export }\OPn{\VAR{exported-symbol}})}\\
60 (\kwd{:size }\VAR{int})%
61 }{\}})}
63 Create or modify \retval{package \VAR{foo}} with
64 \VAR{interned-symbol}s, symbols from \VAR{used-package}s,
65 \VAR{imported-symbol}s, and \VAR{shd-symbol}s. Add \VAR{shd-symbol}s
66 to \VAR{foo}'s shadowing list.
69 \IT{(\FU*{MAKE-PACKAGE} \VAR{foo}
70 \orGOO{\kwd{:nicknames }(\OPn{\VAR{nick}})\DF{\NIL}\\
71 \kwd{:use }(\OPn{\VAR{used-package}})}{\}})}
73 Create \retval{package \VAR{foo}}.
76 \IT{(\FU*{RENAME-PACKAGE} \VAR{package} \VAR{new-name}
77 \Op{\VAR{new-nicknames}\DF{\NIL}})}
79 Rename \VAR{package}. Return \retval{renamed package}.
82 \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
84 Make \retval{package \VAR{foo}} current.
87 \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
88 \FU*{UNUSE-PACKAGE}}{\}}
89 \VAR{other-packages}
90 \Op{\VAR{package}\DF{\V{\A package\A}}})}
92 Make exported symbols of \VAR{other-packages} available in
93 \VAR{package}, or remove them from \VAR{package},
94 respectively. Return \retval{\T}.
97 \IT{\arrGOO{%
98 (\FU*{PACKAGE-USE-LIST } \VAR{package})\\
99 (\FU*{PACKAGE-USED-BY-LIST } \VAR{package})}{.}}
101 \retval{List of other packages} used by/using \VAR{package}.
104 \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
106 Delete \VAR{package}. Return \retval{\T} if successful.
109 \IT{\V{\A package\A}\DF{\kwd{common-lisp-user}}\qquad\qquad}
110 {\index{*PACKAGE*@\A PACKAGE\A}
111 The current package.
114 \IT{(\FU*{LIST-ALL-PACKAGES})\qquad\qquad\qquad}
116 \retval{List of registered packages}.
119 \IT{(\FU*{PACKAGE-NAME} \VAR{package})}
121 \retval{Name of \VAR{package}}.
124 \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
126 \retval{Nicknames} of \VAR{package}.
129 \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
131 \retval{Package} with \VAR{name} (case-sensitive).
134 \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{foo})}
136 \retval{List of symbols} \VAR{foo} from all
137 registered packages.
140 \IT{(\xorGOO{\FU*{INTERN}\\
141 \FU*{FIND-SYMBOL}}{\}}
142 \VAR{foo} \Op{\VAR{package}\DF{\V{\A package\A}}})}
144 Intern or find, respectively, symbol \retval{\VAR{foo}} in
145 \VAR{package}. Second return value is one of
146 \retvalii{\kwd{:internal}}, \retvalii{\kwd{:external}}, or
147 \retvalii{\kwd{:inherited}} (or \retvalii{\NIL} if \FU{intern}
148 has created a fresh symbol).
151 \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}\DF{\V{\A package\A}}})}
153 Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
156 \IT{(\xorGOO{\FU*{IMPORT}\\
157 \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
158 \Op{\VAR{package}\DF{\V{\A package\A}}})}
160 Make \VAR{symbols} internal to \VAR{package}. Return \retval{\T}. In
161 case of a name conflict signal correctable \kwd{package-error} or shadow
162 the old symbol, respectively.
165 \IT{(\FU*{SHADOW} \VAR{symbols}
166 \Op{\VAR{package}\DF{\V{\A package\A}}})}
168 Make \VAR{symbols} of \VAR{package} shadow any otherwise
169 accessible, equally named symbols from other
170 packages. Return \retval{\T}.
173 \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})}
175 \retval{List of symbols} of \VAR{package} that shadow any
176 otherwise accessible, equally named symbols from other packages.
179 \IT{(\FU*{EXPORT} \VAR{symbols}
180 \Op{\VAR{package}\DF{\V{\A package\A}}})}
182 Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
185 \IT{(\FU*{UNEXPORT} \VAR{symbols} \Op{\VAR{package}\DF{\V{\A package\A}}})}
187 Revert \VAR{symbols} to internal status. Return \retval{\T}.
190 \IT{(\xorGOO{%
191 \arrGOO{%
192 \MC*{DO-SYMBOLS}\\
193 \MC*{DO-EXTERNAL-SYMBOLS}}{\}}\text{ }
194 (\NEV{\VAR{var}}\text{ } \OP{\VAR{package}\DF{\V{\A
195 package\A}}\text{ } \Op{\VAR{result}\DF{\NIL}}})\\
196 \MC*{DO-ALL-SYMBOLS } (\VAR{var }
197 \Op{\VAR{result}\DF{\NIL}})}{\}}
198 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
199 \OPn{\orGOO{\NEV{\VAR{tag}}\\
200 \VAR{form}}{\}}})}
202 Evaluate \SO{tagbody}-like body with \VAR{var} successively bound to every
203 symbol from \VAR{package}, to every external symbol from
204 \VAR{package}, or to every symbol from all registered packages,
205 respectively. Return \retval{values of \VAR{result}}. Implicitly,
206 the whole form is a \SO{block} named \NIL.
209 \IT{(\MC*{WITH-PACKAGE-ITERATOR} (\VAR{foo} \VAR{packages}
210 \Op{\kwd{:internal}\XOR\kwd{:external}\XOR\kwd{:inherited}})
211 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
213 Return \retval{values of \VAR{form}s}. In \VAR{form}s, successive
214 invocations of (\VAR{foo}) return: \T\ if a symbol is returned;
215 a symbol from \VAR{packages}; accessibility
216 (\kwd{:internal}, \kwd{:external}, or \kwd{:inherited}); and the
217 package the symbol belongs to.
220 \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{paths}\DF{\NIL}})}
222 If not in \V{\A modules\A}, try \VAR{paths} to load
223 \VAR{module} from. Signal \kwd{error} if
224 unsuccessful. Deprecated.
227 \IT{(\FU*{PROVIDE} \VAR{module})}
229 If not already there, add \VAR{module} to
230 \V{\A modules\A}. Deprecated.
233 \IT{\V{\A modules\A}}
234 {\index{*MODULES*@\A MODULES\A}
235 List of names of loaded modules.
238 \end{LIST}
241 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
242 \subsection{Symbols}
243 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
244 A \kwd*{symbol} has the attributes \VAR{name}, home \kwd{package}, property
245 list, and optionally value (of global constant or variable \VAR{name}) and
246 function (\kwd{function}, macro, or special operator \VAR{name}).
248 \begin{LIST}{1cm}
250 \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
252 Make fresh, uninterned \retval{symbol \VAR{name}}.
255 \IT{(\FU*{GENSYM} \Op{\VAR{s}\DF{\LIT{G}}})}
257 Return fresh, uninterned symbol \retval{\kwd{\#:}\VAR{s}\VAR{n}}
258 with \VAR{n} from \V{\A gensym-counter\A}. Increment \V{\A
259 gensym-counter\A}.%
260 \index{*GENSYM-COUNTER*@\A GENSYM-COUNTER\A}
263 \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
264 \Op{\VAR{package}\DF{\V{\A package\A}}}})}
266 Intern fresh \retval{symbol} in \retval{package}. Deprecated.
269 \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
271 Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
272 \T, give copy the same value, function and property list.
275 \IT{\arrGOO{%
276 (\FU*{SYMBOL-NAME} \VAR{ symbol})\\
277 (\FU*{SYMBOL-PACKAGE} \VAR{ symbol})}{.}}
279 \retval{Name} or \retval{package}, respectively,
280 of \VAR{symbol}.
283 \IT{\arrGOO{%
284 (\FU*{SYMBOL-PLIST} \VAR{ symbol})\\
285 (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
286 (\FU*{SYMBOL-FUNCTION} \VAR{ symbol})}{.}}
288 \retval{Property list}, \retval{value}, or \retval{function},
289 respectively, of \VAR{symbol}. \kwd{setf}able.
292 \IT{(\xorGOO{%
293 \GFU*{DOCUMENTATION}\\
294 (\kwd{SETF } \GFU{DOCUMENTATION})\VAR{ new-doc}}{\}}
295 \VAR{foo}
296 \xorGOO{%
297 \kwd{'variable}\XOR
298 \kwd{'function}\\
299 \kwd{'compiler-macro}\\
300 \kwd{'method-combination}\\
301 \kwd{'structure}\XOR
302 \kwd{'type}\XOR
303 \kwd{'setf}\XOR
304 \T}{\}})}
305 {\index{VARIABLE}\index{FUNCTION}\index{COMPILER-MACRO}\index{METHOD-COMBINATION}\index{STRUCTURE}\index{TYPE}\index{SETF}
306 Get/set \retval{documentation string} of \VAR{foo} of given
307 type.
310 \IT{\CNS*{T}}
312 Truth; the supertype of every type including \kwd{t}; the
313 superclass of every class except \kwd{t}; \V{\A terminal-io\A}.
316 \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
318 Falsity; the empty list; the empty type, subtype of every type;
319 \V{\A standard-input\A}; \V{\A standard-output\A}; the global
320 environment.
323 \end{LIST}
326 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
327 \subsection{Standard Packages}
328 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
329 \begin{LIST}{1cm}
331 \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
333 Exports the defined names of Common Lisp except for those in the
334 \kwd{keyword} package.
337 \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
339 Current package after startup; uses package \kwd{common-lisp}.
342 \IT{\kwd*{KEYWORD}}
344 Contains symbols which are defined to be of type \kwd{KEYWORD}.
347 \end{LIST}
349 %%% Local Variables:
350 %%% mode: latex
351 %%% TeX-master: "clqr"
352 %%% End: