clqr-packages-and-symbols.tex

% Copyright (C) 2008, 2009, 2010 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2 or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Packages and Symbols}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Predicates}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{\arrGOO{(\FU*{SYMBOLP} \VAR{ foo})\\
      (\FU*{PACKAGEP} \VAR{ foo})\\
      (\FU*{KEYWORDP} \VAR{ foo})}{.}}
  {
    \retval{\T} if \VAR{foo} is of indicated type.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Packages}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{\kwd*{:}\VAR{bar}\XOR\kwd*{keyword}\kwd{:}\VAR{bar}}
  {
    Keyword, evaluates to \retval{:\VAR{bar}}.
  }

  \IT{\VAR{package}\kwd*{:}\VAR{symbol}}
  {
    Exported \VAR{symbol} of \VAR{package}.
  }

  \IT{\VAR{package}\kwd*{::}\VAR{symbol}}
  {
    Possibly unexported \VAR{symbol} of \VAR{package}.
  }

  \IT{(\MC*{DEFPACKAGE}\VAR{ foo} 
    \orGOO{%
      \OPn{(\kwd{:nicknames }\OPn{\VAR{nick}})}\\
      (\kwd{:documentation }\VAR{string})\\
      \OPn{(\kwd{:intern }\OPn{\VAR{interned-symbol}})}\\
      \OPn{(\kwd{:use }\OPn{\VAR{used-package}})}\\
      \OPn{(\kwd{:import-from }\VAR{pkg } \OPn{\VAR{imported-symbol}})}\\
      \OPn{(\kwd{:shadowing-import-from}\VAR{ pkg}\OPn{\VAR{ shd-symbol}})}\\
      \OPn{(\kwd{:shadow }\OPn{\VAR{shd-symbol}})}\\
      \OPn{(\kwd{:export }\OPn{\VAR{exported-symbol}})}\\
      (\kwd{:size }\VAR{int})%
    }{\}})}
  {
    Create or modify \retval{package \VAR{foo}} with
    \VAR{interned-symbol}s, symbols from \VAR{used-package}s,
    \VAR{imported-symbol}s, and \VAR{shd-symbol}s. Add \VAR{shd-symbol}s
    to \VAR{foo}'s shadowing list.
  }

  \IT{(\FU*{MAKE-PACKAGE} \VAR{foo}
    \orGOO{\kwd{:nicknames }(\OPn{\VAR{nick}})\DF{\NIL}\\
      \kwd{:use }(\OPn{\VAR{used-package}})}{\}})}
  {
    Create \retval{package \VAR{foo}}.
  }

  \IT{(\FU*{RENAME-PACKAGE} \VAR{package} \VAR{new-name}
    \Op{\VAR{new-nicknames}\DF{\NIL}})}
  {
    Rename \VAR{package}. Return \retval{renamed package}.
  }

  \IT{(\MC*{IN-PACKAGE }\NEV{\VAR{foo}})}
  {
    Make \retval{package \VAR{foo}} current.
  }

  \IT{(\xorGOO{\FU*{USE-PACKAGE}\\
    \FU*{UNUSE-PACKAGE}}{\}} 
    \VAR{other-packages}
    \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Make exported symbols of \VAR{other-packages} available in
    \VAR{package}, or remove them from \VAR{package},
    respectively. Return \retval{\T}. 
  }

  \IT{\arrGOO{%
      (\FU*{PACKAGE-USE-LIST } \VAR{package})\\
      (\FU*{PACKAGE-USED-BY-LIST } \VAR{package})}{.}}
  {
  \retval{List of other packages} used by/using \VAR{package}.
  }

  \IT{(\FU*{DELETE-PACKAGE} \DES{\VAR{package}})}
  {
    Delete \VAR{package}. Return \retval{\T} if successful.
  }

  \IT{\V{\A package\A}\DF{\kwd{common-lisp-user}}\qquad\quad}
  {\index{*PACKAGE*@\A PACKAGE\A}
    The current package.
  }

  \IT{(\FU*{LIST-ALL-PACKAGES})\qquad\qquad\qquad}
  {
    \retval{List of registered packages}.
  }

  \IT{(\FU*{PACKAGE-NAME} \VAR{package})\qquad\quad}
  {
    \retval{Name of \VAR{package}}.
  }

  \IT{(\FU*{PACKAGE-NICKNAMES} \VAR{package})}
  {
    \retval{List of nicknames} of \VAR{package}.
  }

  \IT{(\FU*{FIND-PACKAGE} \VAR{name})}
  {
    \retval{Package} with \VAR{name} (case-sensitive). 
  }

  \IT{(\FU*{FIND-ALL-SYMBOLS} \VAR{foo})}
  {
    \retval{List of symbols} \VAR{foo} from all
    registered packages.
  }

  \IT{(\xorGOO{\FU*{INTERN}\\
      \FU*{FIND-SYMBOL}}{\}} \VAR{foo} \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Intern or find, respectively, symbol \retval{\VAR{foo}} in
    \VAR{package}. Second return value is one of
    \retvalii{\kwd{:internal}}, \retvalii{\kwd{:external}}, or
    \retvalii{\kwd{:inherited}} (or \retvalii{\NIL} if \FU{intern}
    created a fresh symbol).
  }

  \IT{(\FU*{UNINTERN} \VAR{symbol} \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Remove \VAR{symbol} from \VAR{package}, return \retval{\T} on success.
  }

  \IT{(\xorGOO{\FU*{IMPORT}\\
      \FU*{SHADOWING-IMPORT}}{\}} \VAR{symbols}
    \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Make \VAR{symbols} internal  to \VAR{package}. Return \retval{\T}. In
    case of a name conflict signal correctable \kwd{package-error} or shadow
    the old symbol, respectively.
  }

  \IT{(\FU*{SHADOW} \VAR{symbols}
    \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Make \VAR{symbols} of \VAR{package} shadow any otherwise
    accessible, equally named symbols from other
    packages. Return \retval{\T}.
  }

  \IT{(\FU*{PACKAGE-SHADOWING-SYMBOLS} \VAR{package})} 
  {
    \retval{List of symbols} of \VAR{package} that shadow any
    otherwise accessible, equally named symbols from other packages.
  }

  \IT{(\FU*{EXPORT} \VAR{symbols}
    \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Make \VAR{symbols} external to \VAR{package}. Return \retval{\T}.
  }

  \IT{(\FU*{UNEXPORT} \VAR{symbols} \Op{\VAR{package}\DF{\V{\A package\A}}})}
  {
    Revert \VAR{symbols} to internal status. Return \retval{\T}.
  }
  
  \IT{(\xorGOO{%
      \arrGOO{%
        \MC*{DO-SYMBOLS}\\
        \MC*{DO-EXTERNAL-SYMBOLS}}{\}}\text{ }
      (\NEV{\VAR{var}}\text{ } \OP{\VAR{package}\DF{\V{\A
            package\A}}\text{ } \Op{\VAR{result}\DF{\NIL}}})\\
      \MC*{DO-ALL-SYMBOLS } (\VAR{var }
      \Op{\VAR{result}\DF{\NIL}})}{\}}
    \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
    \OPn{\orGOO{\NEV{\VAR{tag}}\\
      \VAR{form}}{\}}})}
  {
    Evaluate \SO{tagbody}-like body with \VAR{var} successively bound to every
    symbol from \VAR{package}, to every external symbol from
    \VAR{package}, or to every symbol from all registered packages, 
    respectively. Return \retval{values of \VAR{result}}.  Implicitly,
    the whole form is a \SO{block} named \NIL. 
  }

  \IT{(\MC*{WITH-PACKAGE-ITERATOR} (\VAR{foo} \VAR{packages}
    \Op{\kwd{:internal}\XOR\kwd{:external}\XOR\kwd{:inherited}})
    \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})} \PROGN{\VAR{form}})}
  {
    Return \retval{values of \VAR{form}s}. In \VAR{form}s, successive
    invocations of  (\VAR{foo}) return: \T\ if a symbol is returned;
    a symbol from \VAR{packages}; accessibility
    (\kwd{:internal}, \kwd{:external}, or \kwd{:inherited}); and the
    package the symbol belongs to.
  }

  \IT{(\FU*{REQUIRE} \VAR{module} \Op{\VAR{paths}\DF{\NIL}})}
  {
    If not in \V{\A modules\A}, try \VAR{paths} to load
    \VAR{module} from. Signal \kwd{error} if
    unsuccessful. Deprecated. 
  }

  \IT{(\FU*{PROVIDE} \VAR{module})}
  {
    If not already there, add \VAR{module} to
    \V{\A modules\A}. Deprecated. 
  }

  \IT{\V{\A modules\A}}
  {\index{*MODULES*@\A MODULES\A}
    List of names of loaded modules.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Symbols}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
A \kwd*{symbol} has the attributes \VAR{name}, home \kwd{package}, property
list, and optionally value (of global constant or variable \VAR{name}) and
function (\kwd{function}, macro, or special operator \VAR{name}).

\begin{LIST}{1cm}

  \IT{(\FU*{MAKE-SYMBOL} \VAR{name})}
  {
    Make fresh, uninterned \retval{symbol \VAR{name}}.
  }

  \IT{(\FU*{GENSYM} \Op{\VAR{s}\DF{\LIT{G}}})}
  {
    Return fresh, uninterned symbol \retval{\kwd{\#:}\VAR{s}\VAR{n}}
    with \VAR{n} from \V{\A gensym-counter\A}. Increment \V{\A
      gensym-counter\A}.%
    \index{*GENSYM-COUNTER*@\A GENSYM-COUNTER\A}
  }

  \IT{(\FU*{GENTEMP} \OP{\VAR{prefix}\DF{\LIT{T}}
      \Op{\VAR{package}\DF{\V{\A package\A}}}})}
  {
    Intern fresh \retval{symbol} in \retval{package}. Deprecated.
  }

  \IT{(\FU*{COPY-SYMBOL} \VAR{symbol} \Op{\VAR{props}\DF{\NIL}})}
  {
    Return uninterned \retval{copy of \VAR{symbol}}. If \VAR{props} is
    \T, give copy the same value, function and property list.
  }

  \IT{\arrGOO{%
      (\FU*{SYMBOL-NAME} \VAR{ symbol})\\
      (\FU*{SYMBOL-PACKAGE} \VAR{ symbol})\\
      (\FU*{SYMBOL-PLIST} \VAR{ symbol})\\
      (\FU*{SYMBOL-VALUE} \VAR{ symbol})\\
      (\FU*{SYMBOL-FUNCTION} \VAR{ symbol})}{.}}
  {
  \retval{Name}, \retval{package}, \retval{property list},
  \retval{value}, or \retval{function}, respectively,
  of \VAR{symbol}. \kwd{setf}able. 
  }

  \IT{(\xorGOO{%
      \GFU*{DOCUMENTATION}\\
      (\kwd{SETF } \GFU{DOCUMENTATION})\VAR{ new-doc}}{\}}
    \VAR{foo}
    \xorGOO{%
      \kwd{'variable}\XOR
      \kwd{'function}\\
      \kwd{'compiler-macro}\\
      \kwd{'method-combination}\\
      \kwd{'structure}\XOR
      \kwd{'type}\XOR
      \kwd{'setf}\XOR
      \T}{\}})}
  {\index{VARIABLE}\index{FUNCTION}\index{COMPILER-MACRO}\index{METHOD-COMBINATION}\index{STRUCTURE}\index{TYPE}\index{SETF}
    Get/set \retval{documentation string} of \VAR{foo} of given
    type.
  }

  \IT{\CNS*{T}}
  {
    Truth; the supertype of every type including \kwd{t}; the
    superclass of every class except \kwd{t}; \V{\A terminal-io\A}.
  }

  \IT{\CNS*{NIL}\XOR{\CNS*{()}}}
  {
    Falsity; the empty list; the empty type, subtype of every type;
    \V{\A standard-input\A}; \V{\A standard-output\A}; the global
    environment. 
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection[Std Packages]{Standard Packages}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{\kwd*{COMMON-LISP}\XOR\kwd*{CL}}
  {
    Exports the defined names of Common Lisp except for those in the
    \kwd{keyword} package.
  }

  \IT{\kwd*{COMMON-LISP-USER}\XOR\kwd*{CL-USER}}
  {
    Current package after startup; uses package \kwd{common-lisp}. 
  }

  \IT{\kwd*{KEYWORD}}
  {
    Contains symbols which are defined to be of type \kwd{KEYWORD}.
  }

\end{LIST}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "clqr"
%%% End: