clqr-packages-and-symbols.tex

   1 % Copyright (C) 2008 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
  14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  15 \subsection{Predicates}
  16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  17 \begin{LIST}{1cm}
  18
  19   \IT{\arrGOO{(\FU*{SYMBOLP} \VAR{ foo})\\
  20       (\FU*{PACKAGEP} \VAR{ foo})\\
  21       (\FU*{KEYWORDP} \VAR{ foo})}{.}}
  22   {
  23   \retval{\T} if \VAR{foo} is of indicated type.
  24   }
  25
  26 \end{LIST}
  27
  28
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30 \subsection{Packages}
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  32 \begin{LIST}{1cm}
  33
  34   \IT{\kwd*{:}\VAR{bar}\XOR\kwd*{keyword}\kwd{:}\VAR{bar}}
  35   {
  36   Keyword, evaluates to \retval{:\VAR{bar}}.
  37   }
  38
  39   \IT{\VAR{package}\kwd*{:}\VAR{symbol}}
  40   {
  41   Exported \VAR{symbol} of \VAR{package}.
  42   }
  43
  44   \IT{\VAR{package}\kwd*{::}\VAR{symbol}}
  45   {
  46   Possibly unexported \VAR{symbol} of \VAR{package}.
  47   }
  48
  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     }{\}})}
  61   {
  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.
  66   }
  67
  68   \IT{(\FU*{MAKE-PACKAGE} \VAR{foo}
  69     \orGOO{\kwd{:nicknames }(\OPn{\VAR{nick}})\DF{\NIL}\\
  70       \kwd{:use }(\OPn{\VAR{used-package}})}{\}})}
  71   {
  72   Create \retval{package \VAR{foo}}.
  73   }
  74
  75   \IT{(\FU*{RENAME-PACKAGE} \VAR{package} \VAR{new-name} \Op{\VAR{new-nicknames}\DF{\NIL}})}
  76   {
  77   Rename \VAR{package}. Return \retval{renamed package}.
  78   }
  79
  80   \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
  81   {
  82   Make \retval{package \VAR{foo}} current.
  83   }
  84
  85   \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
  86     \FU*{UNUSE-PACKAGE}}{\}}
  87     \VAR{other-packages}
  88     \Op{\VAR{package}\DF{\V{\A package\A}}})}
  89   {
  90   Make exported symbols of \VAR{other-packages} available in \VAR{package}, or remove them
  91   from \VAR{package}, respectively. Return \retval{\T}.
  92   }
  93
  94   \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
  95   {
  96   Delete \VAR{package}. Return \retval{\T} if successful.
  97   }
  98
  99   \IT{\V*{\A package\A}}
 100   {The current package.
 101   }
 102
 103   \IT{(\FU*{LIST-ALL-PACKAGES})}
 104   {
 105   \retval{List of registered packages}.
 106   }
 107
 108   \IT{(\FU*{PACKAGE-NAME} \VAR{package})}
 109   {
 110   \retval{Name of \VAR{package}}.
 111   }
 112
 113   \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
 114   {
 115   \retval{List of nicknames} of \VAR{package}.
 116   }
 117
 118   \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
 119   {
 120   \retval{Package object} with \VAR{name} (case-sensitive).
 121   }
 122
 123   \IT{(\FU*{PACKAGE-USE-LIST} \VAR{package})}
 124   {
 125   \retval{List of other packages} used by \VAR{package}.
 126   }
 127
 128   \IT{(\FU*{PACKAGE-USED-BY-LIST} \VAR{package})}
 129   {
 130   \retval{List of other packages} using \VAR{package}.
 131   }
 132
 133   \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{name})}
 134   {
 135   Return \retval{list of symbols} with \VAR{name} from all
 136   registered packages.
 137   }
 138
 139   \IT{(\FU*{SYMBOL-PACKAGE} \VAR{symbol})}
 140   {
 141   Return the \retval{package \VAR{symbol} came from}.
 142   }
 143
 144   \IT{(\xorGOO{\FU*{INTERN}\\
 145       \FU*{FIND-SYMBOL}}{\}} \VAR{symbol} \Op{\VAR{package}})}
 146   {
 147   Intern or find, respectively, \retval{\VAR{symbol}} in
 148   \VAR{package}. Second return value is one of
 149   \retvalii{\kwd{:internal}}, \retvalii{\kwd{:external}}, or
 150   \retvalii{\kwd{:inherited}}.
 151   }
 152
 153   \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}})}
 154   {
 155   Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
 156   }
 157
 158   \IT{(\xorGOO{\FU*{IMPORT}\\
 159       \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
 160     \Op{\VAR{package}\DF{\kwd{\A package\A}}})}
 161   {
 162   Make \VAR{symbols} internal  to \VAR{package}. Return \retval{\T}. In
 163   case of a name conflict, signal \kwd{package-error}, or shadow
 164   the old symbol, respectively.
 165   }
 166
 167   \IT{(\FU*{SHADOW} \VAR{symbols}
 168     \Op{\VAR{package}\DF{\kwd{\A package\A}}})}
 169   {
 170   Add \VAR{symbols} to shadowing list of \VAR{package} making equally
 171   named inherited symbols shadowed. Return
 172   \retval{\T}.
 173   }
 174
 175   \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})}
 176   {
 177   \retval{List of shadowing symbols} of \VAR{package}.
 178   }
 179
 180   \IT{(\FU*{EXPORT} \VAR{symbols}
 181     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 182   {
 183   Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
 184   }
 185
 186   \IT{(\FU*{UNEXPORT} \VAR{symbols} \VAR{package})}
 187   {
 188   Revert \VAR{symbols} to internal status. Return \retval{\T}.
 189   }
 190
 191   \IT{(\xorGOO{%
 192       \arrGOO{%
 193         \MC*{DO-SYMBOLS}\\
 194         \MC*{DO-EXTERNAL-SYMBOLS}}{\}}\text{ }
 195       (\NEV{\VAR{var}}\text{ } \OP{\VAR{package}\DF{\V{\A package\A}}\text{ } \Op{\VAR{result}\DF{\NIL}}})\\
 196       \MC*{DO-ALL-SYMBOLS } (\VAR{var } \Op{\VAR{result}\DF{\NIL}})}{\}}
 197     \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
 198     \OPn{\orGOO{\NEV{\VAR{tag}}\\
 199       \VAR{form}}{\}}})}
 200   {
 201   Evaluate \VAR{form}s with \VAR{var} successively bound to every
 202   symbol from \VAR{package}, to every external symbol from
 203   \VAR{package}, or to every symbol from all registered packages,
 204   respectively. Return \retval{values of \VAR{result}}.
 205   }
 206
 207   \IT{(\MC*{WITH-PACKAGE-ITERATOR} (\VAR{name} \VAR{packages}
 208     \Op{\kwd{:internal}\XOR\kwd{:external}\XOR\kwd{:inherited}})
 209     \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
 210   {
 211   Return \retval{values of \VAR{form}s}. In \VAR{form}s, successive
 212   invocations of  (\VAR{name}) return: \T\ if a symbol is returned;
 213   a symbol from \VAR{packages}; accessibility
 214   (\kwd{:internal}, \kwd{:external}, or \kwd{:inherited}); and the
 215   package the symbol belongs to.
 216   }
 217
 218   \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{path-list}})}
 219   {
 220   If not in \V{\A modules\A}, try paths in \VAR{path-list} to load
 221   module from. Signal \kwd{error} if unsuccessful. Deprecated.
 222   }
 223
 224   \IT{(\FU*{PROVIDE} \VAR{module})}
 225   {
 226   If not already there, add \VAR{module} to
 227   \V{\A modules\A}. Deprecated.
 228   }
 229
 230   \IT{\V*{\A modules\A}}
 231   {
 232   List of names of modules loaded into Lisp image.
 233   }
 234
 235 \end{LIST}
 236
 237
 238 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 239 \subsection{Symbols}
 240 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 241 A \kwd*{symbol} has the attributes \VAR{name}, home \kwd{package}, property
 242 list, and optionally value (of global constant or variable \VAR{name}) and
 243 function (of \kwd{function}, macro, or special operator \VAR{name}).
 244
 245 \begin{LIST}{1cm}
 246
 247   \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
 248   {
 249   Make fresh, uninterned \retval{symbol \VAR{name}}.
 250   }
 251
 252   \IT{(\FU*{GENSYM} \Op{\VAR{x}\DF{\LIT{G}}})}
 253   {
 254   Return fresh symbol \retval{\kwd{\#:}\VAR{x}\VAR{n}}, with \VAR{n} from
 255   \V*{\A gensym-counter\A} which is incremented only in case no \VAR{x}
 256   is given.
 257   }
 258
 259   \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
 260       \Op{\VAR{package}\DF{\V{\A package\A}}}})}
 261   {
 262   Intern fresh \retval{symbol} in \retval{package}. Deprecated.
 263   }
 264
 265   \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
 266   {
 267   Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
 268   \T, give copy the same value, function and property list.
 269   }
 270
 271   \IT{\arrGOO{(\FU*{SYMBOL-FUNCTION} \VAR{ symbol})\\
 272       (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
 273       (\FU*{SYMBOL-PLIST} \VAR{ symbol})}{.}}
 274   {
 275   \retval{Function}, \retval{value}, or \retval{property list}, respectively,
 276   of \VAR{symbol}. \kwd{setf}able.
 277   }
 278
 279   \IT{(\GFU*{DOCUMENTATION} \VAR{foo}
 280     \Goo{\kwd{'variable}%
 281       \XOR\kwd{'function}%
 282       \XOR\kwd{'compiler-macro}%
 283       \XOR\kwd{'method-combination}%
 284       \XOR\kwd{'structure}%
 285       \XOR\kwd{'type}%
 286       \XOR\kwd{'setf}%
 287       \XOR\T})}
 288   {
 289   Return \retval{documentation string} of \VAR{foo} of given
 290   type. \kwd{setf}\-able.
 291   }
 292
 293   \IT{(\FU*{SYMBOL-NAME} \VAR{ symbol})}
 294   {
 295   \retval{Name} of \VAR{symbol}.
 296   }
 297
 298   \IT{\CNS*{T}}
 299   {
 300   Truth; the supertype of every type including \kwd{t}; the superclass of every
 301   class except \kwd{t}; \V{\A terminal-io\A}.
 302   }
 303
 304   \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
 305   {
 306   Falsity; the empty list; the empty type, subtype of every type; \V{\A standard-input\A};
 307   \V{\A standard-output\A}; the global environment.
 308   }
 309
 310 \end{LIST}
 311
 312
 313 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 314 \subsection[Std Packages]{Standard Packages}
 315 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 316 \begin{LIST}{1cm}
 317
 318   \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
 319   {
 320   Contains the defined names of Common Lisp except for those in the
 321   \kwd{keyword} package.
 322   }
 323
 324   \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
 325   {
 326     Current package after startup; uses package \kwd{common-lisp}.
 327   }
 328
 329   \IT{\kwd*{KEYWORD}}
 330   {
 331     Contains symbols which are defined to be of type \kwd{KEYWORD}.
 332   }
 333
 334 \end{LIST}