Unfinished work on figure Data Types.
[clqr.git] / clqr-packages-and-symbols.tex
blob323e5d535d339fa65b7a562ead678f635f3862be
1 % Copyright (C) 2008, 2009 Bert Burgemeister
3 % Permission is granted to copy, distribute and/or modify this
4 % document under the terms of the GNU Free Documentation License,
5 % Version 1.2 or any later version published by the Free Software
6 % Foundation; 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 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 \subsection{Predicates}
16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17 \begin{LIST}{1cm}
19 \IT{\arrGOO{(\FU*{SYMBOLP} \VAR{ foo})\\
20 (\FU*{PACKAGEP} \VAR{ foo})\\
21 (\FU*{KEYWORDP} \VAR{ foo})}{.}}
23 \retval{\T} if \VAR{foo} is of indicated type.
26 \end{LIST}
29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
30 \subsection{Packages}
31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
32 \begin{LIST}{1cm}
34 \IT{\kwd*{:}\VAR{bar}\XOR\kwd*{keyword}\kwd{:}\VAR{bar}}
36 Keyword, evaluates to \retval{:\VAR{bar}}.
39 \IT{\VAR{package}\kwd*{:}\VAR{symbol}}
41 Exported \VAR{symbol} of \VAR{package}.
44 \IT{\VAR{package}\kwd*{::}\VAR{symbol}}
46 Possibly unexported \VAR{symbol} of \VAR{package}.
49 \IT{(\MC*{DEFPACKAGE}\VAR{ foo}
50 \orGOO{%
51 \OPn{(\kwd{:nicknames }\OPn{\VAR{nick}})}\\
52 (\kwd{:documentation }\VAR{string})\\
53 \OPn{(\kwd{:intern }\OPn{\VAR{interned-symbol}})}\\
54 \OPn{(\kwd{:use }\OPn{\VAR{used-package}})}\\
55 \OPn{(\kwd{:import-from }\VAR{pkg } \OPn{\VAR{imported-symbol}})}\\
56 \OPn{(\kwd{:shadowing-import-from}\VAR{ pkg}\OPn{\VAR{ shd-symbol}})}\\
57 \OPn{(\kwd{:shadow }\OPn{\VAR{shd-symbol}})}\\
58 \OPn{(\kwd{:export }\OPn{\VAR{exported-symbol}})}\\
59 (\kwd{:size }\VAR{int})%
60 }{\}})}
62 Create or modify \retval{package \VAR{foo}} with
63 \VAR{interned-symbol}s, symbols from \VAR{used-package}s,
64 \VAR{imported-symbol}s, and \VAR{shd-symbol}s. Add \VAR{shd-symbol}s
65 to \VAR{foo}'s shadowing list.
68 \IT{(\FU*{MAKE-PACKAGE} \VAR{foo}
69 \orGOO{\kwd{:nicknames }(\OPn{\VAR{nick}})\DF{\NIL}\\
70 \kwd{:use }(\OPn{\VAR{used-package}})}{\}})}
72 Create \retval{package \VAR{foo}}.
75 \IT{(\FU*{RENAME-PACKAGE} \VAR{package} \VAR{new-name} \Op{\VAR{new-nicknames}\DF{\NIL}})}
77 Rename \VAR{package}. Return \retval{renamed package}.
80 \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
82 Make \retval{package \VAR{foo}} current.
85 \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
86 \FU*{UNUSE-PACKAGE}}{\}}
87 \VAR{other-packages}
88 \Op{\VAR{package}\DF{\V{\A package\A}}})}
90 Make exported symbols of \VAR{other-packages} available in \VAR{package}, or remove them
91 from \VAR{package}, respectively. Return \retval{\T}.
94 \IT{\arrGOO{%
95 (\FU*{PACKAGE-USE-LIST } \VAR{package})\\
96 (\FU*{PACKAGE-USED-BY-LIST } \VAR{package})}{.}}
98 \retval{List of other packages} used by/using \VAR{package}.
101 \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
103 Delete \VAR{package}. Return \retval{\T} if successful.
106 \IT{\V{\A package\A}\DF{\kwd{common-lisp-user}}\qquad\quad}
107 {\index{*PACKAGE*@\A PACKAGE\A}
108 The current package.
111 \IT{(\FU*{LIST-ALL-PACKAGES})\qquad\qquad\qquad}
113 \retval{List of registered packages}.
116 \IT{(\FU*{PACKAGE-NAME} \VAR{package})\qquad\quad}
118 \retval{Name of \VAR{package}}.
121 \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
123 \retval{List of nicknames} of \VAR{package}.
126 \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
128 \retval{Package object} with \VAR{name} (case-sensitive).
131 \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{name})}
133 Return \retval{list of symbols} with \VAR{name} from all
134 registered packages.
137 \IT{(\xorGOO{\FU*{INTERN}\\
138 \FU*{FIND-SYMBOL}}{\}} \VAR{foo} \Op{\VAR{package}\DF{\V{\A package\A}}})}
140 Intern or find, respectively, symbol \retval{\VAR{foo}} in
141 \VAR{package}. Second return value is one of
142 \retvalii{\kwd{:internal}}, \retvalii{\kwd{:external}}, or
143 \retvalii{\kwd{:inherited}} (or \retvalii{\NIL} if \FU{intern}
144 created a fresh symbol).
147 \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}\DF{\V{\A package\A}}})}
149 Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
152 \IT{(\xorGOO{\FU*{IMPORT}\\
153 \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
154 \Op{\VAR{package}\DF{\V{\A package\A}}})}
156 Make \VAR{symbols} internal to \VAR{package}. Return \retval{\T}. In
157 case of a name conflict signal correctable \kwd{package-error} or shadow
158 the old symbol, respectively.
161 \IT{(\FU*{SHADOW} \VAR{symbols}
162 \Op{\VAR{package}\DF{\V{\A package\A}}})}
164 Add \VAR{symbols} to shadowing list of \VAR{package} making equally
165 named inherited symbols shadowed. Return
166 \retval{\T}.
169 \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})}
171 \retval{List of shadowing symbols} of \VAR{package}.
174 \IT{(\FU*{EXPORT} \VAR{symbols}
175 \Op{\VAR{package}\DF{\V{\A package\A}}})}
177 Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
180 \IT{(\FU*{UNEXPORT} \VAR{symbols} \Op{\VAR{package}\DF{\V{\A package\A}}})}
182 Revert \VAR{symbols} to internal status. Return \retval{\T}.
185 \IT{(\xorGOO{%
186 \arrGOO{%
187 \MC*{DO-SYMBOLS}\\
188 \MC*{DO-EXTERNAL-SYMBOLS}}{\}}\text{ }
189 (\NEV{\VAR{var}}\text{ } \OP{\VAR{package}\DF{\V{\A package\A}}\text{ } \Op{\VAR{result}\DF{\NIL}}})\\
190 \MC*{DO-ALL-SYMBOLS } (\VAR{var } \Op{\VAR{result}\DF{\NIL}})}{\}}
191 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
192 \OPn{\orGOO{\NEV{\VAR{tag}}\\
193 \VAR{form}}{\}}})}
195 Evaluate \SO{tagbody}-like body with \VAR{var} successively bound to every
196 symbol from \VAR{package}, to every external symbol from
197 \VAR{package}, or to every symbol from all registered packages,
198 respectively. Return \retval{values of \VAR{result}}. Implicitly,
199 the whole form is a \SO{block} named \NIL.
202 \IT{(\MC*{WITH-PACKAGE-ITERATOR} (\VAR{foo} \VAR{packages}
203 \Op{\kwd{:internal}\XOR\kwd{:external}\XOR\kwd{:inherited}})
204 \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
206 Return \retval{values of \VAR{form}s}. In \VAR{form}s, successive
207 invocations of (\VAR{foo}) return: \T\ if a symbol is returned;
208 a symbol from \VAR{packages}; accessibility
209 (\kwd{:internal}, \kwd{:external}, or \kwd{:inherited}); and the
210 package the symbol belongs to.
213 \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{paths}\DF{\NIL}})}
215 If not in \V{\A modules\A}, try \VAR{paths} to load
216 \VAR{module} from. Signal \kwd{error} if unsuccessful. Deprecated.
219 \IT{(\FU*{PROVIDE} \VAR{module})}
221 If not already there, add \VAR{module} to
222 \V{\A modules\A}. Deprecated.
225 \IT{\V{\A modules\A}}
226 {\index{*MODULES*@\A MODULES\A}
227 List of names of loaded modules.
230 \end{LIST}
233 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
234 \subsection{Symbols}
235 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
236 A \kwd*{symbol} has the attributes \VAR{name}, home \kwd{package}, property
237 list, and optionally value (of global constant or variable \VAR{name}) and
238 function (\kwd{function}, macro, or special operator \VAR{name}).
240 \begin{LIST}{1cm}
242 \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
244 Make fresh, uninterned \retval{symbol \VAR{name}}.
247 \IT{(\FU*{GENSYM} \Op{\VAR{s}\DF{\LIT{G}}})}
249 Return fresh, uninterned symbol \retval{\kwd{\#:}\VAR{s}\VAR{n}} with \VAR{n} from
250 \V{\A gensym-counter\A}. Increment \V{\A gensym-counter\A}. \index{*GENSYM-COUNTER*@\A GENSYM-COUNTER\A}
253 \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
254 \Op{\VAR{package}\DF{\V{\A package\A}}}})}
256 Intern fresh \retval{symbol} in \retval{package}. Deprecated.
259 \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
261 Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
262 \T, give copy the same value, function and property list.
265 \IT{\arrGOO{%
266 (\FU*{SYMBOL-NAME} \VAR{ symbol})\\
267 (\FU*{SYMBOL-PACKAGE} \VAR{ symbol})\\
268 (\FU*{SYMBOL-PLIST} \VAR{ symbol})\\
269 (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
270 (\FU*{SYMBOL-FUNCTION} \VAR{ symbol})}{.}}
272 \retval{Name}, \retval{package}, \retval{property list},
273 \retval{value}, or \retval{function}, respectively,
274 of \VAR{symbol}. \kwd{setf}able.
277 \IT{(\xorGOO{%
278 \GFU*{DOCUMENTATION}\\
279 (\kwd{SETF } \GFU{DOCUMENTATION})\VAR{ new-doc}}{\}}
280 \VAR{foo}
281 \Goo{\kwd{'variable}%
282 \XOR\kwd{'function}%
283 \XOR\kwd{'compiler-macro}%
284 \XOR\kwd{'method-combination}%
285 \XOR\kwd{'structure}%
286 \XOR\kwd{'type}%
287 \XOR\kwd{'setf}%
288 \XOR\T})}
289 {\index{VARIABLE}\index{FUNCTION}\index{COMPILER-MACRO}\index{METHOD-COMBINATION}\index{STRUCTURE}\index{TYPE}\index{SETF}
290 Get/set \retval{documentation string} of \VAR{foo} of given
291 type.
294 \IT{\CNS*{T}}
296 Truth; the supertype of every type including \kwd{t}; the superclass of every
297 class except \kwd{t}; \V{\A terminal-io\A}.
300 \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
302 Falsity; the empty list; the empty type, subtype of every type; \V{\A standard-input\A};
303 \V{\A standard-output\A}; the global environment.
306 \end{LIST}
309 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
310 \subsection[Std Packages]{Standard Packages}
311 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
312 \begin{LIST}{1cm}
314 \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
316 Exports the defined names of Common Lisp except for those in the
317 \kwd{keyword} package.
320 \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
322 Current package after startup; uses package \kwd{common-lisp}.
325 \IT{\kwd*{KEYWORD}}
327 Contains symbols which are defined to be of type \kwd{KEYWORD}.
330 \end{LIST}
332 %%% Local Variables:
333 %%% mode: latex
334 %%% TeX-master: "clqr"
335 %%% End: