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
  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}
  76     \Op{\VAR{new-nicknames}\DF{\NIL}})}
  77   {
  78     Rename \VAR{package}. Return \retval{renamed package}.
  79   }
  80
  81   \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
  82   {
  83     Make \retval{package \VAR{foo}} current.
  84   }
  85
  86   \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
  87     \FU*{UNUSE-PACKAGE}}{\}}
  88     \VAR{other-packages}
  89     \Op{\VAR{package}\DF{\V{\A package\A}}})}
  90   {
  91     Make exported symbols of \VAR{other-packages} available in
  92     \VAR{package}, or remove them from \VAR{package},
  93     respectively. Return \retval{\T}.
  94   }
  95
  96   \IT{\arrGOO{%
  97       (\FU*{PACKAGE-USE-LIST } \VAR{package})\\
  98       (\FU*{PACKAGE-USED-BY-LIST } \VAR{package})}{.}}
  99   {
 100   \retval{List of other packages} used by/using \VAR{package}.
 101   }
 102
 103   \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
 104   {
 105     Delete \VAR{package}. Return \retval{\T} if successful.
 106   }
 107
 108   \IT{\V{\A package\A}\DF{\kwd{common-lisp-user}}\qquad\qquad}
 109   {\index{*PACKAGE*@\A PACKAGE\A}
 110     The current package.
 111   }
 112
 113   \IT{(\FU*{LIST-ALL-PACKAGES})\qquad\qquad\qquad}
 114   {
 115     \retval{List of registered packages}.
 116   }
 117
 118   \IT{(\FU*{PACKAGE-NAME} \VAR{package})}
 119   {
 120     \retval{Name of \VAR{package}}.
 121   }
 122
 123   \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
 124   {
 125     \retval{Nicknames} of \VAR{package}.
 126   }
 127
 128   \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
 129   {
 130     \retval{Package} with \VAR{name} (case-sensitive).
 131   }
 132
 133   \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{foo})}
 134   {
 135     \retval{List of symbols} \VAR{foo} from all
 136     registered packages.
 137   }
 138
 139   \IT{(\xorGOO{\FU*{INTERN}\\
 140       \FU*{FIND-SYMBOL}}{\}}
 141     \VAR{foo} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 142   {
 143     Intern or find, respectively, symbol \retval{\VAR{foo}} in
 144     \VAR{package}. Second return value is one of
 145     \retvalii{\kwd{:internal}}, \retvalii{\kwd{:external}}, or
 146     \retvalii{\kwd{:inherited}} (or \retvalii{\NIL} if \FU{intern}
 147     has created a fresh symbol).
 148   }
 149
 150   \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 151   {
 152     Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
 153   }
 154
 155   \IT{(\xorGOO{\FU*{IMPORT}\\
 156       \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
 157     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 158   {
 159     Make \VAR{symbols} internal  to \VAR{package}. Return \retval{\T}. In
 160     case of a name conflict signal correctable \kwd{package-error} or shadow
 161     the old symbol, respectively.
 162   }
 163
 164   \IT{(\FU*{SHADOW} \VAR{symbols}
 165     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 166   {
 167     Make \VAR{symbols} of \VAR{package} shadow any otherwise
 168     accessible, equally named symbols from other
 169     packages. Return \retval{\T}.
 170   }
 171
 172   \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})}
 173   {
 174     \retval{List of symbols} of \VAR{package} that shadow any
 175     otherwise accessible, equally named symbols from other packages.
 176   }
 177
 178   \IT{(\FU*{EXPORT} \VAR{symbols}
 179     \Op{\VAR{package}\DF{\V{\A package\A}}})}
 180   {
 181     Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
 182   }
 183
 184   \IT{(\FU*{UNEXPORT} \VAR{symbols} \Op{\VAR{package}\DF{\V{\A package\A}}})}
 185   {
 186     Revert \VAR{symbols} to internal status. Return \retval{\T}.
 187   }
 188
 189   \IT{(\xorGOO{%
 190       \arrGOO{%
 191         \MC*{DO-SYMBOLS}\\
 192         \MC*{DO-EXTERNAL-SYMBOLS}}{\}}\text{ }
 193       (\NEV{\VAR{var}}\text{ } \OP{\VAR{package}\DF{\V{\A
 194             package\A}}\text{ } \Op{\VAR{result}\DF{\NIL}}})\\
 195       \MC*{DO-ALL-SYMBOLS } (\VAR{var }
 196       \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 \SO{tagbody}-like body 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}}.  Implicitly,
 205     the whole form is a \SO{block} named \NIL.
 206   }
 207
 208   \IT{(\MC*{WITH-PACKAGE-ITERATOR} (\VAR{foo} \VAR{packages}
 209     \Op{\kwd{:internal}\XOR\kwd{:external}\XOR\kwd{:inherited}})
 210     \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
 211   {
 212     Return \retval{values of \VAR{form}s}. In \VAR{form}s, successive
 213     invocations of  (\VAR{foo}) return: \T\ if a symbol is returned;
 214     a symbol from \VAR{packages}; accessibility
 215     (\kwd{:internal}, \kwd{:external}, or \kwd{:inherited}); and the
 216     package the symbol belongs to.
 217   }
 218
 219   \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{paths}\DF{\NIL}})}
 220   {
 221     If not in \V{\A modules\A}, try \VAR{paths} to load
 222     \VAR{module} from. Signal \kwd{error} if
 223     unsuccessful. Deprecated.
 224   }
 225
 226   \IT{(\FU*{PROVIDE} \VAR{module})}
 227   {
 228     If not already there, add \VAR{module} to
 229     \V{\A modules\A}. Deprecated.
 230   }
 231
 232   \IT{\V{\A modules\A}}
 233   {\index{*MODULES*@\A MODULES\A}
 234     List of names of loaded modules.
 235   }
 236
 237 \end{LIST}
 238
 239
 240 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 241 \subsection{Symbols}
 242 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 243 A \kwd*{symbol} has the attributes \VAR{name}, home \kwd{package}, property
 244 list, and optionally value (of global constant or variable \VAR{name}) and
 245 function (\kwd{function}, macro, or special operator \VAR{name}).
 246
 247 \begin{LIST}{1cm}
 248
 249   \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
 250   {
 251     Make fresh, uninterned \retval{symbol \VAR{name}}.
 252   }
 253
 254   \IT{(\FU*{GENSYM} \Op{\VAR{s}\DF{\LIT{G}}})}
 255   {
 256     Return fresh, uninterned symbol \retval{\kwd{\#:}\VAR{s}\VAR{n}}
 257     with \VAR{n} from \V{\A gensym-counter\A}. Increment \V{\A
 258       gensym-counter\A}.%
 259     \index{*GENSYM-COUNTER*@\A GENSYM-COUNTER\A}
 260   }
 261
 262   \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
 263       \Op{\VAR{package}\DF{\V{\A package\A}}}})}
 264   {
 265     Intern fresh \retval{symbol} in \retval{package}. Deprecated.
 266   }
 267
 268   \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
 269   {
 270     Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
 271     \T, give copy the same value, function and property list.
 272   }
 273
 274   \IT{\arrGOO{%
 275       (\FU*{SYMBOL-NAME} \VAR{ symbol})\\
 276       (\FU*{SYMBOL-PACKAGE} \VAR{ symbol})\\
 277       (\FU*{SYMBOL-PLIST} \VAR{ symbol})\\
 278       (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
 279       (\FU*{SYMBOL-FUNCTION} \VAR{ symbol})}{.}}
 280   {
 281   \retval{Name}, \retval{package}, \retval{property list},
 282   \retval{value}, or \retval{function}, respectively,
 283   of \VAR{symbol}. \kwd{setf}able.
 284   }
 285
 286   \IT{(\xorGOO{%
 287       \GFU*{DOCUMENTATION}\\
 288       (\kwd{SETF } \GFU{DOCUMENTATION})\VAR{ new-doc}}{\}}
 289     \VAR{foo}
 290     \xorGOO{%
 291       \kwd{'variable}\XOR
 292       \kwd{'function}\\
 293       \kwd{'compiler-macro}\\
 294       \kwd{'method-combination}\\
 295       \kwd{'structure}\XOR
 296       \kwd{'type}\XOR
 297       \kwd{'setf}\XOR
 298       \T}{\}})}
 299   {\index{VARIABLE}\index{FUNCTION}\index{COMPILER-MACRO}\index{METHOD-COMBINATION}\index{STRUCTURE}\index{TYPE}\index{SETF}
 300     Get/set \retval{documentation string} of \VAR{foo} of given
 301     type.
 302   }
 303
 304   \IT{\CNS*{T}}
 305   {
 306     Truth; the supertype of every type including \kwd{t}; the
 307     superclass of every class except \kwd{t}; \V{\A terminal-io\A}.
 308   }
 309
 310   \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
 311   {
 312     Falsity; the empty list; the empty type, subtype of every type;
 313     \V{\A standard-input\A}; \V{\A standard-output\A}; the global
 314     environment.
 315   }
 316
 317 \end{LIST}
 318
 319
 320 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 321 \subsection[Std Packages]{Standard Packages}
 322 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 323 \begin{LIST}{1cm}
 324
 325   \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
 326   {
 327     Exports the defined names of Common Lisp except for those in the
 328     \kwd{keyword} package.
 329   }
 330
 331   \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
 332   {
 333     Current package after startup; uses package \kwd{common-lisp}.
 334   }
 335
 336   \IT{\kwd*{KEYWORD}}
 337   {
 338     Contains symbols which are defined to be of type \kwd{KEYWORD}.
 339   }
 340
 341 \end{LIST}
 342
 343 %%% Local Variables:
 344 %%% mode: latex
 345 %%% TeX-master: "clqr"
 346 %%% End: