continued work

[clqr.git] / clqr-control-structure.tex

% Copyright (C) 2008 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{Control Structure}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

  \IT{(\FU*{EQ} \VAR{foo bar})}
  {
  \retval{\T} if \VAR{foo} and \VAR{bar} are identical.
  }

  \IT{(\FU*{EQL} \VAR{foo bar})}
  {
  \retval{\T} if \VAR{foo} and \VAR{bar}
  are identical, or the same character, or the same number.
  }

  \IT{(\FU*{EQUAL} \VAR{foo bar})}
  {
  \retval{\T} if \VAR{foo} and \VAR{bar}
  are \FU{EQL}, or are conses with \FU{equal} cars and cdrs, or are
  strings or bit-vectors with  \FU{eql} elements, or are equivalent pathnames.
  }

  \IT{(\FU*{EQUALP} \VAR{foo bar})}
  {
  \retval{\T} if \VAR{foo} and \VAR{bar}
  are \FU{EQUAL}, or if they have corresponding components of the same
  type which are \kwd{equalp}.
  }

  \IT{(\FU*{NOT} \VAR{bool})}
  {
  \retval{\NIL} if \VAR{bool} is \T; \retval{\T} if \VAR{bool} is \NIL.
  }

  \IT{(\FU*{BOUNDP} \VAR{symbol})}
  {
  \retval{\T} if \VAR{symbol} is a special variable.
  }

  \IT{(\FU*{CONSTANTP} \VAR{foo} \Op{\VAR{environment}})}
  {
  \retval{\T} if \VAR{foo} is a constant form.
  }

  \IT{(\FU*{FUNCTIONP} \VAR{foo})}
  {
  \retval{\T} if \VAR{foo} is of type \kwd{function}.
  }

  \IT{(\FU*{FBOUNDP} \VAR{foo})}
  {
  \retval{\T} if \VAR{foo} is a global function or macro.
  }


\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Variables}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\kwd*{DEFVAR} \VAR{name} \OP{\VAR{form}
      \Op{\VAR{documentation}}})}
  {
  Unless bound already, assign value of \VAR{form} to dynamic variable
  \retval{\VAR{name}}. 
  }

  \IT{(\kwd*{DEFPARAMETER} \VAR{name} \VAR{form}
    \Op{\VAR{documentation}})}
  {
  Assign value of \VAR{form} to dynamic variable \retval{\VAR{name}}.
  }

  \IT{(\kwd*{DEFCONSTANT} \VAR{name} \VAR{form}
    \Op{\VAR{documentation}})}
  {
  Assign value of \VAR{form} to global constant \retval{\VAR{name}}.
  }

  \IT{(\xorGOO{\SF*{SETF}\\
      \SF*{PSETF}}{\}} \Goos{\VAR{place}
      \VAR{form}})}
  {
  Set \VAR{place}s to values of \VAR{form}s returning \retval{value
    of last \VAR{form}}. Work sequentially/in parallel, respectively. 
  }

  \IT{(\xorGOO{\SF*{SETQ}\\
      \SF*{PSETQ}}{\}} \Goos{\VAR{symbol}
      \VAR{form}})}
  {
  Set \VAR{symbol}s to values of \VAR{form}s returning \retval{value
    of last \VAR{form}}. Work sequentially/in parallel, respectively. 
  }

  \IT{(\FU*{SET} \VAR{symbol} \VAR{foo})}
  {
  Set \VAR{symbol}'s value cell to \retval{\VAR{foo}}.
  }

  \IT{(\SF*{MULTIPLE-VALUE-SETQ} \VAR{vars} \VAR{form})}
  {
  Set elements of \VAR{vars} to the values of
  \VAR{form}. Return \retval{\VAR{form}'s primary value}.
  }

  \IT{(\SF*{SHIFTF} \RP{\VAR{place}} \VAR{foo})}
  {
  Store valueof \VAR{foo} in rightmost \VAR{place} shifting values of
  \VAR{place}s left, returning \retval{first \VAR{place}}. 
  }

  \IT{(\SF*{ROTATEF} \OPn{\VAR{place}})}
  {
  Rotate values of \VAR{place}s left, old first becoming new last
  \VAR{place}'s value. Return \retval{\NIL}.
  }

  \IT{(\FU*{MAKUNBOUND} \VAR{symbol})}
  {
  Delete special variable \retval{\VAR{symbol}}.
  }

  \label{:property_lists}
  \IT{\arrGOO{(\FU*{GET} \VAR{ symbol} \VAR{ key }
      \OP{\VAR{default}\DF{\NIL}})\\ 
      (\FU*{GETF} \VAR{ place} \VAR{ key }
      \OP{\VAR{default}\DF{\NIL}})}{.}}
  {
  \retval{First entry \VAR{key}} from property list stored in
  \VAR{symbol}/in \VAR{place}, respectively, or \retval{\VAR{default}} if
  there was no \VAR{key}. \kwd{setf}able.
  }

  \IT{(\FU*{GET-PROPERTIES} \VAR{property-list} \VAR{keys})}
  {
  Return \retval{key} and \retvalii{value} of first entry from \VAR{property-list}
  matching a key from \VAR{keys}, and \retvaliii{tail of
    \VAR{property-list}} starting with that key. Return \retval{\NIL},
  \retvalii{\NIL}, and  \retvaliii{\NIL} if there was no matching key
  in \VAR{property-list}.
  }

  \IT{\arrGOO{(\FU*{REMPROP} \VAR{ symbol} \VAR{ key})\\
      (\SF*{REMF} \VAR{ place} \VAR{ key})}{.}}
  {
  Remove fist entry \VAR{key} from property list stored in
  \VAR{symbol}/in \VAR{place}, respectively. Return \retval{\T} if \VAR{key}
  was there, or \retval{\NIL} otherwise.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Functions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{section:Functions}


Below, lambda list (\OPn{\VAR{fu-arg}}) has the form\\
(\OPn{\VAR{var}}
\OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
      \Op{\VAR{supplied-p}}})}}
\Op{\kwd*{\&rest} \VAR{var}}
\OP{\kwd*{\&key} \GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
      \VAR{var})}
    \OP{\VAR{init }\Op{\VAR{supplied-p}}})}
  \Op{\kwd*{\&allow-other-keys}}}
\OP{\kwd*{\&aux} \Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}}).\\
\VAR{supplied-p} is \T\ if there is a corresponding argument.

\begin{LIST}{1cm}

  \IT{(\xorGOO{\SF*{DEFUN} \VAR{ foo}\\ \SF*{LAMBDA}}{\}}
    (\VAR{\OPn{fu-arg}}) \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \Op{\VAR{documentation}} 
    \OPn{\VAR{form}})}
  {
  Define function with \retval{name \VAR{foo}} or an anonymous
  function, respectively, which
  applies \VAR{form}s to \VAR{fu-arg}s.
  }

  \IT{(\xorGOO{\SF*{FLET}\\
      \SF*{LABELS}}{\}}
    (\OPn{(\VAR{foo}
      (\OPn{\VAR{fu-arg}}) 
      \OPn{(\kwd{declare} \OPn{\VAR{local-decl}})}%
      \Op{\VAR{documentation}}
      \OPn{\VAR{local-form}})}) \OPn{(\kwd{declare} \VAR{decl})}
    \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with
  locally defined functions \VAR{foo}. Only for \SF{LABELS},
  \VAR{foo}s are visible inside \VAR{local-forms}. Return
  \retval{values of \VAR{form}s}.
  }

  \IT{(\SF*{FUNCTION} \VAR{foo})}
  {Return \retval{function named \VAR{foo}}.
    }

  \IT{(\FU*{APPLY} \VAR{function} \RP{\VAR{arg}})}
  {
  Return \retval{value of \VAR{function}} called on
  \VAR{arg}s. Last \VAR{arg} must be a list.
  }

  \IT{(\FU*{FUNCALL} \VAR{function} \OPn{arg})}
  {
  Return \retval{value of \VAR{function}} called with \VAR{arg}s.
  }

  \IT{(\SF*{MULTIPLE-VALUE-CALL} \VAR{foo} \OPn{\VAR{form}})}
  {Call function
  \VAR{foo} with values of \VAR{form}s as its arguments.  Return
  \retval{values returned by \VAR{foo}}.
  }

  \IT{(\FU*{VALUES-LIST} \VAR{list})}
  {
  Return \retval{elements of \VAR{list}}.
  }

  \IT{(\FU*{VALUES} \OPn{\VAR{foo}})}
  {
  Return \retval{\VAR{foo}s} as multiple values. \kwd{setf}able.
  }

  \IT{(\FU*{MULTIPLE-VALUE-LIST} \VAR{form})}
  {
  Return in a \retval{list} values of \VAR{form}.
  }

  \IT{(\FU*{NTH-VALUE} \VAR{n} \VAR{form})}
  {
  Zero-based \retval{\VAR{n}th return value} of \VAR{form}.
  }

  \IT{(\FU*{COMPLEMENT} \VAR{function})}
  {
  Return \retval{new function} with same arguments and same side effects
  as \VAR{function}, but with complementary truth value.
  }

  \IT{(\FU*{CONSTANTLY} \VAR{foo})}
  {
  Return \retval{function} of any number of arguments returning \VAR{foo}.
  }

  \IT{(\FU*{IDENTITY} \VAR{foo})}
  {
  Return \retval{\VAR{foo}}.
  }

  \IT{(\FU*{FUNCTION-LAMBDA-EXPRESSION} \VAR{function})}
  {
  If available, return \retval{lambda expression} of \VAR{function},
  \retvalii{\NIL} if \VAR{function} was defined in an environment
  without bindings, and \retvaliii{name} of \VAR{function}. 
  }

  \IT{(\FU*{FDEFINITION} \VAR{foo})}
  {
  \retval{Definition} of function \VAR{foo}. \kwd{setf}able.
  }

  \IT{(\FU*{FMAKUNBOUND} \VAR{foo})}
  {
  Remove global function or macro definition \retval{\VAR{foo}}.
  }

  \IT{\arrGOO{\CNS*{CALL-ARGUMENTS-LIMIT}\\
      \CNS*{LAMBDA-PARAMETERS-LIMIT}}{.}}
  {
  Upper bound of the number of function arguments or lambda list
  parameters, respectively; $\geq50$. 
  }

  \IT{\CNS*{MULTIPLE-VALUES-LIMIT}}
  {
  Upper bound of the number of values a function can return; $\geq20$.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Macros}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Below, macro lambda list (\OPn{\VAR{macro-arg}}) has the form of either\\
(\Op{\kwd*{\&whole} \VAR{var}}
\Op{\kwd*{\&environment} \VAR{var}}
\OPn{\VAR{var}}
\Op{\kwd*{\&environment} \VAR{var}}
\Op{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
      \Op{\VAR{supplied-p}}})}}
\Op{\kwd*{\&environment} \VAR{var}}
\Op{\Goo{\kwd*{\&rest}\XOR\kwd*{\&body}} \VAR{var}}
\Op{\kwd*{\&environment} \VAR{var}}
\OP{\kwd*{\&key} \GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
      \VAR{var})}%
    \OP{\VAR{init} \Op{\VAR{supplied-p}}})}%
  \Op{\kwd*{\&environment} \VAR{var}}
  \Op{\kwd*{\&allow-other-keys}}}
\Op{\kwd*{\&aux} \Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}}
\Op{\kwd*{\&environment} \VAR{var}})\\
or\\
(\Op{\kwd*{\&whole} \VAR{var}}
\Op{\kwd*{\&environment} \VAR{var}}
\OPn{\VAR{var}}
\Op{\kwd*{\&environment} \VAR{var}}
\Op{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
      \Op{\VAR{supplied-p}}})}}
\Op{\kwd*{\&environment} \VAR{var}}
\kwd{.} \VAR{var}).\\
\kwd*{\&environment} \VAR{var} may appear only once.
\VAR{supplied-p} is \T\ if there is a corresponding argument.

\begin{LIST}{1cm}

  \IT{(\xorGOO{\SF*{DEFMACRO}\\\FU*{DEFINE-COMPILER-MACRO}}{\}}
    \VAR{foo} (\OPn{\VAR{macro-arg}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Op{\VAR{documentation}}
    \OPn{\VAR{form}})}
  {
  Define macro \retval{\VAR{foo}}.
  }

  \IT{(\SF*{DEFINE-SYMBOL-MACRO} \VAR{name} \VAR{expansion-form})}
  {
  Make \retval{\VAR{name}} a macro call.
  }

  \IT{(\SF*{MACROLET} (\OPn{(\VAR{name} (\OPn{\VAR{macro-arg}})
      \OPn{(\kwd{declare} \OPn{\VAR{local-decl}})} 
      \Op{\VAR{documentation}} \OPn{\VAR{macro-form}})}) \OPn{(\kwd{declare}
      \OPn{\VAR{decl}})} \OPn{\VAR{form}})}
  {
  Evaluate \retval{\VAR{form}s} with \VAR{name}s locally defined
  as macros which are invisible to each other.  
  }

  \IT{(\SF*{SYMBOL-MACROLET} (\OPn{(\VAR{name}
      \VAR{expansion-form})}) \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \OPn{\VAR{form}})}
  {
  Evaluate \retval{\VAR{form}s} with \VAR{name}s locally defined as
  symbol-macros. 
  }

  \IT{(\SF*{DEFSETF} \VAR{function} \xorGOO{\VAR{update } \Op{\VAR{documentation}}\\
    \OPn{\VAR{arg } (\OPn{\VAR{var}})\text{ } \OPn{(\kwd{declare} \OPn{\VAR{
            decl}})}\text{ } \Op{\VAR{documentation}}}}{\}})}
  {
  Specify how to \kwd{setf} a place accessed by
  \retval{\VAR{function}}.
  }

  \IT{(\SF*{DEFINE-SETF-EXPANDER} \VAR{function} (\OPn{\VAR{macro-arg}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Op{\VAR{documentation}}
    \OPn{\VAR{form}})}
  {
  Specify how to \kwd{setf} a place accessed by \retval{\VAR{function}}.
  }

  \IT{(\FU*{GET-SETF-EXPANSION} \VAR{place} \Op{\VAR{environment}})}
  {
  Return five values describing how to \kwd{setf} place.
  }

  \IT{(\SF*{DEFINE-MODIFY-MACRO} \VAR{foo} (\kwd{\&optional}
    \OPn{\VAR{var}} \kwd{\&rest} \OPn{\VAR{var}}) \VAR{function}
    \Op{\VAR{documentation}})}
  {
  Define macro \retval{\VAR{foo}} able to read and write a place.
  }

  \IT{\CNS*{LAMBDA-LIST-KEYWORDS}}
  {List of macro lambda list keywords.
    }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Control Flow}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{(\SF*{IF} \VAR{test} \VAR{then} \Op{\VAR{else}\DF{\NIL}})}
  {Return value of
  \retval{\VAR{then}} if \VAR{test} returns \T; return value of
  \retval{\VAR{else}} otherwise.
  }

  \IT{(\SF*{COND} \OPn{(\VAR{test} \OPn{\VAR{then}}\DF{\VAR{test}})})}
  {
  Return the \retval{values} of the first
  \VAR{then}s whose \VAR{test} returns \T; return
  \retval{\NIL} if each \VAR{test} returns \NIL.
  }

  \IT{(\xorGOO{\SF*{WHEN}\\
      \SF*{UNLESS}}{\}} \VAR{test}
    \OPn{\VAR{foo}}\DF{\NIL})}
  {
  Evaluate \VAR{foo}s and return \retval{values of last \VAR{foo}} if
  \VAR{test} returns \T\ or \NIL, respectively. Return \retval{\NIL} otherwise.
  }

  \IT{(\SF*{CASE} \VAR{test} \OPn{(\VAR{keys} \OPn{\VAR{foo}})}
    \Op{(\Goo{\T\XOR\kwd*{OTHERWISE}} \OPn{\VAR{bar}})\DF{\NIL}})}
  {
  Evaluate first \VAR{foo}s one of whose unevaluated \VAR{keys} is
  \kwd{eql} evaluated \VAR{test} and return \retval{their values}.
  Return \retval{values of \VAR{bar}s} if no \VAR{keys} match. 
  }

  \IT{(\Goo{\SF*{CCASE}\XOR\SF*{ECASE}} \VAR{test}
    \OPn{(\VAR{keys} \OPn{\VAR{foo}})})}
  {
  Evaluate first \VAR{foo}s one of whose unevaluated \VAR{keys} is \kwd{eql} evaluated
  \VAR{test} and return \retval{their values}. Signal correctible error/non-correctible \kwd{type-error},
  respectively, if no \VAR{keys} match and return \retval{\NIL} then.
  }

  \IT{(\SF*{AND} \OPn{\VAR{form}}\DF{\T})}
  {
  Evaluate \VAR{form}s from left to
  right. Immediately return \retval{\NIL} if one \VAR{form}'s value is \NIL. Return
  \retval{values of last \VAR{form}} otherwise.
  }

  \IT{(\SF*{OR} \OPn{\VAR{form}}\DF{\NIL})}
  {
  Evaluate \VAR{form}s from left to
  right. Immediately return \retval{primary value} of first
  non-\NIL-evaluating form, or \retval{all values} if last \VAR{form}
  is reached. Return \retval{\NIL} if no \VAR{form} returns \T.
  }

  \IT{(\kwd*{PROGN} \OPn{\VAR{form}}\DF{\NIL})}
  {Evaluate \VAR{form}s sequentially. Return
  \retval{values of last \VAR{form}}.
  }

  \IT{(\xorGOO{\SF*{PROG}\\
      \SF*{PROG*}}{\}}
    (\orGOO{%
      \VAR{var}\\
      (\VAR{var } \Op{ \VAR{value}})}{\}^{\!\!*}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} 
    \xorGOO{\VAR{tag}\\\VAR{form}}{\}^{\!\!*}})}
  {
  Evaluate \kwd{TAGBODY}-like body with \VAR{var}s locally bound (in parallel or sequentially, respectively) to
  \VAR{value}s. Return \retval{\NIL} or explicitly
  \retval{\kwd{return}ed value}. 
  }

  \IT{\arrGOO{%
      (\SF*{MULTIPLE-VALUE-PROG1} \VAR{ form-r} \OPn{\VAR{ form}})\\
      (\SF*{PROG1} \VAR{ form-r} \OPn{\VAR{ form}})\\
      (\SF*{PROG2} \VAR{ form-a} \VAR{ form-r} \OPn{\VAR{ form}})}{.}}
  {
  Evaluate forms in order. Return \retval{values/1st value},
  respectively, of \VAR{form-r}. 
  }

  \IT{(\SF*{PROGV} \VAR{symbols} \VAR{values} \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with \VAR{symbols} dynamically bound to \VAR{values} or
  \NIL. Return \retval{values returned by \VAR{form}s}.
  }

  \IT{(\SF*{DESTRUCTURING-BIND} \VAR{foo} \VAR{bar}  \OPn{(\kwd{declare}
      \OPn{\VAR{decl}})} \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s, and return \retval{values of last \VAR{form}},
  with variables from tree \VAR{foo} bound to corresponding elements
  of tree \VAR{bar}. 
  }

  \IT{(\kwd*{MULTIPLE-VALUE-BIND} (\OPn{\VAR{var}}) \VAR{values-form}
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \OPn{\VAR{body-form}})}
  {Evaluate
  \VAR{body-form}s with \VAR{var}s bound to the return values of
  \VAR{values-form}. Return \retval{values returned by \VAR{body-form}s}.
  }

  \IT{(\xorGOO{\SF*{LET}\\ 
      \SF*{LET*}}{\}}(%
    \orGOO{\VAR{name}\\
      (\VAR{name }\Op{\VAR{value}})}{\}^{\!\!*}}) 
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} 
    \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with \VAR{name}s bound (in parallel or
  sequentially, respectively) to \VAR{value}s or \NIL. Return
  \retval{values of \VAR{form}s}. 
  }

  \IT{(\SF*{LOCALLY} \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s with declarations \VAR{decl} in
  effect. Return \retval{values of \VAR{form}s}. 
  }

  \IT{(\SF*{RETURN-FROM} \VAR{foo} \Op{\VAR{result}\DF{\NIL}})}
  {
  Have nearest enclosing \kwd{block} \VAR{foo} return with
  values of \VAR{result}. 
  }

  \IT{(\SF*{RETURN} \Op{\VAR{result}\DF{\NIL}})}
  {
  Have nearest enclosing block \NIL\ return with values of \VAR{result}.
  }

  \IT{(\SF*{BLOCK} \VAR{name} \OPn{\VAR{form}})}
  {Evaluate \VAR{form}s returning
  \retval{values of last \VAR{form}} unless interrupted by \SF{RETURN-FROM}.
  }

  \IT{(\SF*{TAGBODY} \Goos{\VAR{tag}\XOR\VAR{form}})}
  {
  Evaluate \VAR{form}s. \VAR{tag}s (symbols or integers) are targets
  for \SF{GO}. Return \retval{\NIL}. 
  }

  \IT{(\SF*{GO} \VAR{tag})}
  {Jump within a \SF{tagbody} to nearest
  lexically enclosing \kwd{eql} \VAR{tag}.
  }

  \IT{(\SF*{CATCH} \VAR{tag} \OPn{\VAR{form}})}
  {Evaluate \VAR{form}s returning
  \retval{values of last \VAR{form}} unless interrupted by \SF{THROW}.
  }

  \IT{(\SF*{THROW} \VAR{tag form})}
  {Have the nearest dynamically
  enclosing \SF{CATCH} with a tag \kwd{eq} \VAR{tag} return with the
  values of \VAR{form}.
  }

  \IT{(\FU*{SLEEP} \VAR{n})}
  {Wait \VAR{n} seconds, return \retval{\NIL}.
    }

\end{LIST}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Iteration}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}
  
  \IT{(\xorGOO{\SF*{DO}\\\SF*{DO*}}{\}}
    (\orGOO{%
      \VAR{var}\\
      (\VAR{var } \Op{ \VAR{start } \Op{\VAR{step}}})}{\}^{\!\!*}})
    (\VAR{stop} \OPn{\VAR{result}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})} 
    \xorGOO{\VAR{tag}\\\VAR{form}}{\}^{\!\!*}})}
  {
  Evaluate \SF{TAGBODY}-like body with \VAR{var}s successively bound according
  to the values of the corresponding \VAR{start} and \VAR{step}
  forms. \VAR{var}s are bound in parallel/sequentially, respectively.
  Stop iteration when \VAR{stop} is \T. Return \retval{value of
    last \VAR{result}}.
  }

  \IT{(\SF*{DOTIMES} (\VAR{var} \VAR{integer} \Op{\VAR{result}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \Goos{\VAR{tag}\XOR\VAR{form}})}
  {
  Evaluate \SF{TAGBODY}-like body with \VAR{var} successively bound
  to integers from 0 to $\mbox{\VAR{integer}} - 1$. Upon evaluation of
  \retval{\VAR{result}}, \VAR{var} is \NIL.
  }

  \IT{(\SF*{DOLIST }(\VAR{var} \VAR{list} \Op{\VAR{result}})
    \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
    \Goos{\VAR{tag}\XOR\VAR{form}})}
  {
  Evaluate \SF{TAGBODY}-like body with \VAR{var} successively bound
  to the elements of \VAR{list}. Upon evaluation of
  \retval{\VAR{result}}, \VAR{var} is \NIL.
  }


\end{LIST}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Loop Facility}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{figure}%
  \label{loop-overview}%
  \begin{center}%
    \begin{sideways}%
      (%  
      \arraycolsep0pt
      \(
      \text{\kwd{loop}}
      \left[
        \text{\LKWD{named} \VAR{n}}
        \right]
      \left\{
      \begin{array}{l}
        \text{\LKWD{with} \VAR{var} [\VAR{type}] \LKWD{=} \VAR{foo }} 
        \{\text{\LKWD{and} \VAR{var-n} [\VAR{type}] \LKWD{=} \VAR{bar}\}}^{*} \\
        \left.\!
        \begin{array}{l}
          \text{\LKWD{for}}  \\
          \text{\LKWD{as}} 
        \end{array}\right\}
        \boxed{
          \text{\VAR{var} [\VAR{type}]}
          \left\{
          \begin{array}{l}
            \left.\!
            \begin{array}{l}
              \left[
                \left\{
                \begin{array}{l}
                  \text{\LKWD{upfrom}}\\
                  \text{\LKWD{from}}
                \end{array}
                \right\}
                \text{\VAR{start}\DF{0}}
                \right]
              \left[
                \left\{
                \begin{array}{l}
                  \text{\LKWD{upto}}\\
                  \text{\LKWD{to}}\\
                  \text{\LKWD{below}}
                \end{array}
                \right\}
                \text{\VAR{form}}
                \right]\\
              \text{\LKWD{from} \VAR{start}}
              \left\{
              \begin{array}{l}
                \text{\LKWD{downto}}\\
                \text{\LKWD{above}}
              \end{array}
              \right\}              
              \text{\VAR{form }}\\
              \text{\LKWD{downfrom} \VAR{start}}
              \left[
                \left\{
                \begin{array}{l}
                  \text{\LKWD{downto}}\\
                  \text{\LKWD{to}}\\
                  \text{\LKWD{above}}
                \end{array}
                \right\}            
                \text{\VAR{form}}
                \right]
            \end{array}
            \right\}
            \left[   
              \text{\LKWD{by} \VAR{step}\DF{1}}
              \right]\\
            \left.\!
            \begin{array}{l}
              \text{\LKWD{in}} \\
              \text{\LKWD{on}}
            \end{array}
            \right\}
            \text{\VAR{list}} 
            \left[
              \text{\LKWD{by} \VAR{form}\DF{\kwd{cdr}}}
              \right]\\
            \text{\LKWD{=} \VAR{foo }} 
            \left[
              \text{\LKWD{then} \VAR{bar}}
              \right] \\
            \text{\LKWD{across} \VAR{vector}}\\
            \text{\LKWD{being}}
            \left\{
            \begin{array}{l}
              \text{\LKWD{the}}\\          
              \text{\LKWD{each}}
            \end{array}
            \right\}%
            \left\{
            \begin{array}{{l}}
              \left.\!
              \begin{array}{l}
                \left.\!
                \begin{array}{l}
                  \text{\LKWD{hash-key}}\\
                  \text{\LKWD{hash-keys}}
                \end{array}
                \right\}%
                \left\{
                \begin{array}{l}
                  \text{\LKWD{of}}\\
                  \text{\LKWD{in}}
                \end{array}
                \right\}
                \text{\VAR{hash }} 
                \left[
                  \text{\LKWD{using} (\LKWD{hash-value} \VAR{v})}
                  \right]\\
                \left.\!
                \begin{array}{l}
                  \text{\LKWD{hash-value}}\\
                  \text{\LKWD{hash-values}}
                \end{array}
                \right\}%
                \left\{
                \begin{array}{l}
                  \text{\LKWD{of}}\\
                  \text{\LKWD{in}}
                \end{array}
                \right\}
                \text{\VAR{hash }}
                \left[
                  \text{\LKWD{using} (\LKWD{hash-key} \VAR{k})}
                  \right.\\
              \end{array}
              \right.\\
              \left.\!
              \begin{array}{l}
                \text{\LKWD{symbol\Op{s}}}\\
                \text{\LKWD{present-symbol\Op{s}}}\\
                \text{\LKWD{external-symbol\Op{s}}}
              \end{array}
              \right\}%
              \left[
                \left\{
                \begin{array}{l}
                  \text{\LKWD{of}}\\
                  \text{\LKWD{in}}
                \end{array}
                \right\} \text{\VAR{package}\DF{\V{*package*}}}
                \right]
            \end{array}
            \right.
          \end{array}
          \right\}_{\displaystyle{\mathbb{F}_0}}
                }%boxed
                \left\{
                \text{\LKWD{and} }\boxed{\mathbb{F}_i}
                \right\}^{\!*}\\
                \left.\!%
                \begin{array}{l}
                  \text{\LKWD{initially}} \\
                  \text{\LKWD{finally}} 
                \end{array} 
                \right\} 
                \text{\VAR{form}}^{+} \\
                
      \end{array}
      \right\}^{\!\!\displaystyle{*}}
      %Bottleneck
      \left\{
      \begin{array}{l}
        \text{\LKWD{repeat} \VAR{num}}\\
        \left.\!
        \begin{array}{l}
          \text{\LKWD{while}}\\
          \text{\LKWD{until}}\\
          \text{\LKWD{always}}\\
          \text{\LKWD{never}}\\
          \text{\LKWD{thereis}}
        \end{array}
        \right\} 
        \text{\VAR{test}}\\
        \boxed{
          \left.\!
          \begin{array}{l}
            \left.\!
            \begin{array}{l}
              \text{\LKWD{do}}\\
              \text{\LKWD{doing}}
            \end{array}
            \right\}
            \text{\VAR{form}}^{+}\\
            \text{\LKWD{return}}
            \left\{
            \begin{array}{l}
              \text{\VAR{form}}\\
              \text{\LKWD{it}}
            \end{array}
            \right.\\
            \left.\!
            \begin{array}{l}
              \text{\LKWD{collect\Op{ing}}}\\
              \text{\LKWD{append\Op{ing}}}\\
              \text{\LKWD{nconc\Op{ing}}}
            \end{array}
            \right\}
            \left\{
            \begin{array}{l}
              \text{\VAR{form}}\\
              \text{\LKWD{it}}
            \end{array}
            \right\} [\text{\LKWD{into }\VAR{var}}]\\
            \left.\!
            \begin{array}{l}
              \text{\LKWD{count\Op{ing}}}\\
              \text{\LKWD{sum\Op{ming}}}\\
              \text{\LKWD{maximize}}\\
              \text{\LKWD{maximizing}}\\
              \text{\LKWD{minimize}}\\
              \text{\LKWD{minimizing}}
            \end{array}
            \right\}
            \left\{
            \begin{array}{l}
              \text{\VAR{form}}\\
              \text{\LKWD{it}}
            \end{array}
            \right\} 
                [\text{\LKWD{into }\VAR{n}}]
                [\text{\VAR{type}}]\\
                \left.\!
                \begin{array}{l}
                  \text{\LKWD{if}}\\
                  \text{\LKWD{when}}\\
                  \text{\LKWD{unless}}
                \end{array}
                \right\}%
                \text{\VAR{test }}
                \boxed{\mathbb{S}_i}\{\text{\LKWD{and}}%
                \boxed{\mathbb{S}_j}\}^{*}[\text{\LKWD{else}}%
                  \boxed{\mathbb{S}_k}\{\text{\LKWD{and}}%
                  \boxed{\mathbb{S}_l}\}^{*}][\text{\LKWD{end}}]
          \end{array}
          \right._{\!\!\!\!\displaystyle{\mathbb{S}_0}}
        }%boxed
        \\
        \left.\!
        \begin{array}{l}
          \text{\LKWD{initially}} \\
          \text{\LKWD{finally}} 
        \end{array} 
        \right\}
        \text{\VAR{form}}^{+}
      \end{array}
      \right\}^{\displaystyle{\!\!*}}
      \)%
      \!)%
    \end{sideways}%
  \end{center}\vspace{-1em}
  \caption{Loop Facility, Overview.}%
\end{figure}


\begin{LIST}{1cm}

  \IT{(\SF*{LOOP} \OPn{\VAR{form}})}
  {
  Simple Loop. If \VAR{form}s do
  not include any keywords of the Loop Facility, evaluate them forever. 
  }

  \IT{(\SF*{LOOP} \OPn{\VAR{form}})}
  {
  Loop Facility. If there are loop facility keywords in \VAR{form}s
  see below and p.\ \pageref{loop-overview}.
  }

  \begin{LIST}{.5cm}
    
    \IT{\LKWD*{named} \VAR{n}}
    {
    Give implicit \kwd{block} of loop a name.
    }

    \IT{\LKWD*{with} \VAR{var} \Op{\VAR{type}} \LKWD*{=} \VAR{foo} \Goos{\LKWD*{and}
        \VAR{var-n} \Op{\VAR{type}} \LKWD*{=} \VAR{bar}}}
    {
    Initialize local variables in parallel.
    }

    \IT{\Goo{\LKWD*{initially}\XOR\LKWD*{finally}} \RP{\VAR{form}}}
    {
    Evaluate \VAR{form}s before begin, or after end, respectively, of iterations.
    }

    \IT{\Goo{\LKWD*{for}\XOR\LKWD*{as}} \VAR{var} \Op{\VAR{type}}}
    {
    Begin of iteration control clause.
    }

    \begin{LIST}{.5cm}

      \IT{\Goo{\LKWD*{upfrom}\XOR\LKWD*{from}\XOR\LKWD*{downfrom}}
        \VAR{start}}
      {
      Start stepping with \VAR{start}
      }

      \IT{\Goo{\LKWD*{upto}\XOR\LKWD*{downto}\XOR\LKWD*{to}\XOR\LKWD*{below}\XOR\LKWD*{above}}
        \VAR{form}}
      {
      Specify \VAR{form} as the end value for stepping.
      }

      \IT{\Goo{\LKWD*{in}\XOR\LKWD*{on}} \VAR{list}}
      {
      Bind \VAR{var} to successive elements/tails, respectively, of \VAR{list}.
      }

      \IT{\LKWD*{by} \Goo{\VAR{step}\DF{1}\XOR\VAR{function}\DF{\kwd{cdr}}}}
      {
      Specify the (positive) decrement or increment or the
      \VAR{function} to apply to the list.
      }

      \IT{\LKWD*{=} \VAR{foo} \Op{\LKWD*{then}
          \VAR{bar}\DF{\VAR{foo}}}}
      {
      Bind \VAR{var} in the first iteration to  \VAR{foo} and later to \VAR{bar}.
      }

      \IT{\LKWD*{across} \VAR{vector}}
      {
      Bind \VAR{var} to successive elements of \VAR{vector}.
      }

      \IT{\LKWD*{being} \Goo{\LKWD*{the}\XOR\LKWD*{each}}}
      {
      Iterate over a hash table or a package.
      }

      \begin{LIST}{.5cm}

        \IT{\Goo{\LKWD*{hash-key}\XOR\LKWD*{hash-keys}} \Goo{\LKWD*{of}\XOR\LKWD*{in}} \VAR{hash-table}
          \Op{\LKWD*{using} (\LKWD*{hash-value} \VAR{value})}}
        {
        Bind \VAR{var} successively to the keys of \VAR{hash-table}; bind \VAR{value} to corresponding values.
        }

        \IT{\Goo{\LKWD*{hash-value}\XOR\LKWD*{hash-values}} \Goo{\LKWD*{of}\XOR\LKWD*{in}} \VAR{hash-table}
          \Op{\LKWD*{using} (\LKWD*{hash-key} \VAR{key})}}
        {
        Bind \VAR{var} successively to the values of \VAR{hash-table}; bind \VAR{key} to corresponding keys.
        }

        \IT{\Goo{\LKWD*{symbol}\XOR\LKWD*{symbols}\XOR\LKWD*{present-symbol}\XOR\LKWD*{present-symbols}\XOR\LKWD*{external-symbol}\XOR\LKWD*{external-symbols}}
          \Op{\Goo{\LKWD*{of}\XOR\LKWD*{in}}
            \VAR{package}\DF{\V{*package*}}}}
        {
        Bind \VAR{var} successively to the symbols, or the present symbols, or the external symbols, respectively, of \VAR{package}.
        }

      \end{LIST}
    \end{LIST}
    
    \IT{\LKWD*{and} \VAR{var} \Op{\VAR{type}}}
    {
    Begin of another iteration control clause with variables initialized and stepped in parallel.
    }

    \IT{\Goo{\LKWD*{do}\XOR\LKWD*{doing}} \RP{\VAR{form}}}
    {
    Evaluate \VAR{form}s in every iteration.
    }

    \IT{\LKWD*{it}}
    {
      Value of the test form of an enclosing \LKWD{if}, \LKWD{when},
      or \LKWD{unless} clause.
    }

    \IT{\LKWD*{return} \Goo{\VAR{form}\XOR\LKWD*{it}}}
    {
    Return immediately with value of \VAR{form} or \LKWD{it}.
    }

    \IT{\Goo{\LKWD*{collect}\XOR\LKWD*{collecting}}
      \Goo{\VAR{form}\XOR\LKWD*{it}} \Op{\LKWD*{into} \VAR{list}}}
    {
    Collect values of \VAR{form} or \LKWD{it} into \VAR{list}. If no \VAR{list} is given, collect into an anonymous list
    which is returned after termination.
    }

    \IT{\Goo{\LKWD*{append}\XOR\LKWD*{appending}\XOR\LKWD*{nconc}\XOR\LKWD*{nconcing}}
      \Goo{\VAR{form}\XOR\LKWD*{it}} \Op{\LKWD*{into}
        \VAR{list}}}
    {
    Concatenate values of \VAR{form} or \LKWD{it}, which should be lists, into \VAR{list} by the means of \FU{append} 
    or \FU{nconc}, respectively.  If no \VAR{list} is given, collect into an anonymous list
    which is returned after termination.
    }

    \IT{\Goo{\LKWD*{count}\XOR\LKWD*{counting}}
      \Goo{\VAR{form}\XOR\LKWD*{it}} \Op{\LKWD*{into}
        \VAR{n}} \Op{\VAR{type}}}
    {
    Count the number of times the value of \VAR{form} or of \LKWD{it} is \T.
    If no \VAR{n} is given, count into an anonymous variable
    which is returned after termination.
    }

    \IT{\Goo{\LKWD*{sum}\XOR\LKWD*{summing}}
      \Goo{\VAR{form}\XOR\LKWD*{it}} \Op{\LKWD*{into}
        \VAR{sum}} \Op{\VAR{type}}} 
    {
    Calculate the sum of the values of \VAR{form} or of \LKWD{it}.
    If no \VAR{sum} is given, sum into an anonymous variable
    which is returned after termination.
    }

    \IT{\Goo{\LKWD*{maximize}\XOR\LKWD*{maximizing}\XOR
        \LKWD*{minimize}\XOR
        \LKWD*{minimizing}} \Goo{\VAR{form}\XOR\LKWD*{it}} \Op{\LKWD*{into}
        \VAR{max-min}} \Op{\VAR{type}}} 
    {
    Determine the maximum or minimum, respectively, of the values of
    \VAR{form} or of \LKWD{it}. 
    If no \VAR{max-min} is given, use an anonymous variable
    which is returned after termination.
    }

    \IT{\Goo{\LKWD*{if}\XOR\LKWD*{when}\XOR\LKWD*{unless}} \VAR{ test}
      \VAR{form-i} \Goos{\LKWD*{and} 
        \VAR{form-j}} \Op{\LKWD*{else} \VAR{form-k} \Goos{\LKWD*{and} 
          \VAR{form-l}}} \Op{\LKWD*{end}}} 
    {
    If \VAR{test} returns \T, \T, or \NIL, respectively, evaluate
    \VAR{form-i} and \VAR{form-j}s; otherwise, evaluate \VAR{form-k}
    and \VAR{form-l}s. Inside \VAR{form-i} and \VAR{form-k}, the value
    of \VAR{test} is accessible by \LKWD*{it}. 
    }

    \IT{\LKWD*{repeat} \VAR{num}}
    {
    Terminate \SF{loop} after \VAR{num} times; \VAR{num} is evaluated once.
    }

    \IT{\Goo{\LKWD*{while}\XOR\LKWD*{until}} \VAR{test}}
    {
    Continue iteration until \VAR{test} returns \NIL, or \T, respectively.
    }

    \IT{\Goo{\LKWD*{always}\XOR\LKWD{never}} \VAR{test}}
    {
    Terminate \SF{loop} returning \NIL\ and skipping any
    \LKWD*{finally} parts as soon as \VAR{test} is \NIL, or \T,
    respectively. Otherwise continue \SF{loop} with its default return
    value set to \T. 
    }

    \IT{\LKWD*{thereis} \VAR{test}}
    {
    Terminate \SF{loop} when \VAR{test} is \T\ and return value of
    \VAR{test}, skipping any \LKWD*{finally} parts. Otherwise continue
    \SF{loop} with its default return value set to \NIL. 
    }

    \IT{\LKWD*{loop-finish}}
    {
    Terminate \SF{loop} immediately; skip any \LKWD*{finally} parts.
    }
  \end{LIST}
\end{LIST}