clqr-packages-and-symbols.tex

   1 % Copyright (C) 2008, 2009, 2010, 2011, 2012 Bert Burgemeister
   2 %
   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.
   8 %
   9
  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}.
  14
  15 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  16 \subsection{Predicates}
  17 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  18 \begin{LIST}{1cm}
  19
  20   \IT{\arrGOO{(\FU*{SYMBOLP} \VAR{ foo})\\
  21       (\FU*{PACKAGEP} \VAR{ foo})\\
  22       (\FU*{KEYWORDP} \VAR{ foo})}{.}}
  23   {
  24     \retval{\T} if \VAR{foo} is of indicated type.
  25   }
  26
  27 \end{LIST}
  28
  29
  30 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  31 \subsection{Packages}
  32 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  33 \begin{LIST}{1cm}
  34
  35   \IT{\kwd*{:}\VAR{bar}\XOR\kwd*{keyword}\kwd{:}\VAR{bar}}
  36   {
  37     Keyword, evaluates to \retval{:\VAR{bar}}.
  38   }
  39
  40   \IT{\VAR{package}\kwd*{:}\VAR{symbol}}
  41   {
  42     Exported \VAR{symbol} of \VAR{package}.
  43   }
  44
  45   \IT{\VAR{package}\kwd*{::}\VAR{symbol}}
  46   {
  47     Possibly unexported \VAR{symbol} of \VAR{package}.
  48   }
  49
  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     }{\}})}
  62   {
  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.
  67   }
  68
  69   \IT{(\FU*{MAKE-PACKAGE} \VAR{foo}
  70     \orGOO{\kwd{:nicknames }(\OPn{\VAR{nick}})\DF{\NIL}\\
  71       \kwd{:use }(\OPn{\VAR{used-package}})}{\}})}
  72   {
  73     Create \retval{package \VAR{foo}}.
  74   }
  75
  76   \IT{(\FU*{RENAME-PACKAGE} \VAR{package} \VAR{new-name}
  77     \Op{\VAR{new-nicknames}\DF{\NIL}})}
  78   {
  79     Rename \VAR{package}. Return \retval{renamed package}.
  80   }
  81
  82   \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
  83   {
  84     Make \retval{package \VAR{foo}} current.
  85   }
  86
  87   \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
  88     \FU*{UNUSE-PACKAGE}}{\}}
  89     \VAR{other-packages}
  90     \Op{\VAR{package}\DF{\V{\A package\A}}})}
  91   {
  92     Make exported symbols of \VAR{other-packages} available in
  93     \VAR{package}, or remove them from \VAR{package},
  94     respectively. Return \retval{\T}.
  95   }
  96
  97   \IT{\arrGOO{%
  98       (\FU*{PACKAGE-USE-LIST } \VAR{package})\\
  99       (\FU*{PACKAGE-USED-BY-LIST } \VAR{package})}{.}}
 100   {
 101   \retval{List of other packages} used by/using \VAR{package}.
 102   }
 103
 104   \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
 105   {
 106     Delete \VAR{package}. Return \retval{\T} if successful.
 107   }
 108
 109   \IT{\V{\A package\A}\DF{\kwd{common-lisp-user}}\qquad\qquad}
 110   {\index{*PACKAGE*@\A PACKAGE\A}
 111     The current package.
 112   }
 113
 114   \IT{(\FU*{LIST-ALL-PACKAGES})\qquad\qquad\qquad}
 115   {
 116     \retval{List of registered packages}.
 117   }
 118
 119   \IT{(\FU*{PACKAGE-NAME} \VAR{package})}
 120   {
 121     \retval{Name of \VAR{package}}.
 122   }
 123
 124   \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
 125   {
 126     \retval{Nicknames} of \VAR{package}.
 127   }
 128
 129   \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
 130   {
 131     \retval{Package} with \VAR{name} (case-sensitive).
 132   }
 133
 134   \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{foo})}
 135   {
 136     \retval{List of symbols} \VAR{foo} from all
 137     registered packages.
 138   }
 139
 140   \IT{(\xorGOO{\FU*{INTERN}\\
 141       \FU*{FIND-SYMBOL}}{\}}
 142     \VAR{foo} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 143   {
 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).
 149   }
 150
 151   \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 152   {
 153     Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
 154   }
 155
 156   \IT{(\xorGOO{\FU*{IMPORT}\\
 157       \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
 158     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 159   {
 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.
 163   }
 164
 165   \IT{(\FU*{SHADOW} \VAR{symbols}
 166     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 167   {
 168     Make \VAR{symbols} of \VAR{package} shadow any otherwise
 169     accessible, equally named symbols from other
 170     packages. Return \retval{\T}.
 171   }
 172
 173   \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})}
 174   {
 175     \retval{List of symbols} of \VAR{package} that shadow any
 176     otherwise accessible, equally named symbols from other packages.
 177   }
 178
 179   \IT{(\FU*{EXPORT} \VAR{symbols}
 180     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 181   {
 182     Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
 183   }
 184
 185   \IT{(\FU*{UNEXPORT} \VAR{symbols} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 186   {
 187     Revert \VAR{symbols} to internal status. Return \retval{\T}.
 188   }
 189
 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}}{\}}})}
 201   {
 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.
 207   }
 208
 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}})}
 212   {
 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.
 218   }
 219
 220   \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{paths}\DF{\NIL}})}
 221   {
 222     If not in \V{\A modules\A}, try \VAR{paths} to load
 223     \VAR{module} from. Signal \kwd{error} if
 224     unsuccessful. Deprecated.
 225   }
 226
 227   \IT{(\FU*{PROVIDE} \VAR{module})}
 228   {
 229     If not already there, add \VAR{module} to
 230     \V{\A modules\A}. Deprecated.
 231   }
 232
 233   \IT{\V{\A modules\A}}
 234   {\index{*MODULES*@\A MODULES\A}
 235     List of names of loaded modules.
 236   }
 237
 238 \end{LIST}
 239
 240
 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}).
 247
 248 \begin{LIST}{1cm}
 249
 250   \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
 251   {
 252     Make fresh, uninterned \retval{symbol \VAR{name}}.
 253   }
 254
 255   \IT{(\FU*{GENSYM} \Op{\VAR{s}\DF{\LIT{G}}})}
 256   {
 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}
 261   }
 262
 263   \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
 264       \Op{\VAR{package}\DF{\V{\A package\A}}}})}
 265   {
 266     Intern fresh \retval{symbol} in \retval{package}. Deprecated.
 267   }
 268
 269   \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
 270   {
 271     Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
 272     \T, give copy the same value, function and property list.
 273   }
 274
 275   \IT{\arrGOO{%
 276       (\FU*{SYMBOL-NAME} \VAR{ symbol})\\
 277       (\FU*{SYMBOL-PACKAGE} \VAR{ symbol})\\
 278       (\FU*{SYMBOL-PLIST} \VAR{ symbol})\\
 279       (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
 280       (\FU*{SYMBOL-FUNCTION} \VAR{ symbol})}{.}}
 281   {
 282   \retval{Name}, \retval{package}, \retval{property list},
 283   \retval{value}, or \retval{function}, respectively,
 284   of \VAR{symbol}. \kwd{setf}able.
 285   }
 286
 287   \IT{(\xorGOO{%
 288       \GFU*{DOCUMENTATION}\\
 289       (\kwd{SETF } \GFU{DOCUMENTATION})\VAR{ new-doc}}{\}}
 290     \VAR{foo}
 291     \xorGOO{%
 292       \kwd{'variable}\XOR
 293       \kwd{'function}\\
 294       \kwd{'compiler-macro}\\
 295       \kwd{'method-combination}\\
 296       \kwd{'structure}\XOR
 297       \kwd{'type}\XOR
 298       \kwd{'setf}\XOR
 299       \T}{\}})}
 300   {\index{VARIABLE}\index{FUNCTION}\index{COMPILER-MACRO}\index{METHOD-COMBINATION}\index{STRUCTURE}\index{TYPE}\index{SETF}
 301     Get/set \retval{documentation string} of \VAR{foo} of given
 302     type.
 303   }
 304
 305   \IT{\CNS*{T}}
 306   {
 307     Truth; the supertype of every type including \kwd{t}; the
 308     superclass of every class except \kwd{t}; \V{\A terminal-io\A}.
 309   }
 310
 311   \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
 312   {
 313     Falsity; the empty list; the empty type, subtype of every type;
 314     \V{\A standard-input\A}; \V{\A standard-output\A}; the global
 315     environment.
 316   }
 317
 318 \end{LIST}
 319
 320
 321 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 322 \subsection[Std Packages]{Standard Packages}
 323 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 324 \begin{LIST}{1cm}
 325
 326   \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
 327   {
 328     Exports the defined names of Common Lisp except for those in the
 329     \kwd{keyword} package.
 330   }
 331
 332   \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
 333   {
 334     Current package after startup; uses package \kwd{common-lisp}.
 335   }
 336
 337   \IT{\kwd*{KEYWORD}}
 338   {
 339     Contains symbols which are defined to be of type \kwd{KEYWORD}.
 340   }
 341
 342 \end{LIST}
 343
 344 %%% Local Variables:
 345 %%% mode: latex
 346 %%% TeX-master: "clqr"
 347 %%% End: