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