clqr-control-structure.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{Control Structure}
  12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  13
  14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  15 \subsection{Predicates}
  16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  17 \begin{LIST}{1cm}
  18
  19   \IT{(\FU*{EQ} \VAR{foo bar})}
  20   \retval{\T} if \VAR{foo} and \VAR{bar} are identical.
  21
  22   \IT{(\FU*{EQL} \VAR{foo bar})}
  23   \retval{\T} if \VAR{foo} and \VAR{bar}
  24   are identical, or are the same character, or are the same number.
  25
  26   \IT{(\FU*{EQUAL} \VAR{foo bar})}
  27   \retval{\T} if \VAR{foo} and \VAR{bar}
  28   are \FU{EQL}, or are conses with \FU{equal} cars and cdrs, or are
  29   strings or bit-vectors with  \FU{eql} elements, or are equivalent pathnames.
  30
  31   \IT{(\FU*{EQUALP} \VAR{foo bar})}
  32   \retval{\T} if \VAR{foo} and \VAR{bar}
  33   are \FU{EQUAL}, or if they have corresponding components of the same
  34   type which are \kwd{equalp}.
  35
  36   \IT{(\FU*{CONSTANTP} \VAR{foo} \Op{\VAR{environment}})}
  37   \retval{\T} if \VAR{foo} is a constant form.
  38
  39   \IT{(\FU*{NOT} \VAR{bool})}
  40   Return \retval{\NIL} if \VAR{bool} is \T, return \retval{\T} if \VAR{bool} is \NIL.
  41
  42   \IT{(\FU*{FUNCTIONP} \VAR{foo})}
  43   \retval{\T} if \VAR{foo} is of type \kwd{function}.
  44
  45   \IT{(\FU*{FBOUNDP} \VAR{foo})}
  46   \retval{\T} if \VAR{foo} is the name of a global function or macro..
  47
  48
  49 \end{LIST}
  50
  51
  52 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  53 \subsection{Variables}
  54 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  55
  56 \begin{LIST}{1cm}
  57
  58   \IT{(\kwd*{DEFVAR} \VAR{name} \OP{\VAR{value} \Op{\VAR{documentation}}} )} Unless bound
  59   already, assign \VAR{value} to dynamic variable \retval{\VAR{name}}.
  60
  61   \IT{(\kwd*{DEFPARAMETER} \VAR{name} \VAR{value} \Op{\VAR{documentation}} )} Assign
  62   \VAR{value} to dynamic variable \retval{\VAR{name}}.
  63
  64   \IT{(\kwd*{DEFCONSTANT} \VAR{name} \VAR{value} \Op{\VAR{documentation}} )} Assign
  65   \VAR{value} to global constant \retval{\VAR{name}}.
  66
  67   \IT{(\FU*{NTH-VALUE} \VAR{n} \VAR{form})}
  68   \retval{\VAR{n}th return value} of \VAR{form}.
  69
  70   \IT{(\xorGOO{\SF*{SETF}\\\SF*{PSETF}}{\}} \Goos{\VAR{place}
  71       \VAR{value}})}
  72   Set \VAR{place}s to \retval{\VAR{value}s}, resp. Work sequentially/in
  73   parallel, resp.
  74
  75   \IT{(\xorGOO{\SF*{SETQ}\\\SF*{PSETQ}}{\}} \Goos{\VAR{symbol}
  76       \VAR{value}})}
  77   Set \VAR{symbol}s to \retval{\VAR{value}s}, resp. Work sequentially/in
  78   parallel, resp.
  79
  80   \IT{(\SF*{MULTIPLE-VALUE-SETQ} \VAR{vars} \VAR{form})}
  81   Set \VAR{vars} to the respective values returned by
  82   \VAR{form}. Return \retval{\VAR{form}'s primary value}.
  83
  84   \IT{(\SF*{SHIFTF} \RP{\VAR{place}} \VAR{foo})} Store \VAR{foo} in
  85   rightmost \VAR{place} shifting values of \VAR{place}s left, returning
  86   \retval{first \VAR{place}}.
  87
  88   \IT{(\SF*{ROTATEF} \OPn{\VAR{place}})} Rotate values of \VAR{place}s left,
  89   old first becoming new last \VAR{place}. Return \retval{\NIL}.
  90
  91   \label{:property_lists}
  92   \IT{\arrGOO{(\FU*{GET} \VAR{ symbol} \VAR{ key } \OP{\VAR{default}\DF{\NIL}})\\
  93       (\FU*{GETF} \VAR{ place} \VAR{ key } \OP{\VAR{default}\DF{\NIL}})}{\}}}
  94   \retval{First entry \VAR{key}} from property list stored in
  95   \VAR{symbol}/in \VAR{place}, resp., or \retval{\VAR{default}} if
  96   there was no \VAR{key}. \kwd{setf}able.
  97
  98   \IT{(\FU*{GET-PROPERTIES} \VAR{plist} \VAR{key-list})}
  99   Return \retval{Key} and \retvalii{value} of first entry from \VAR{plist}
 100   matching a key from \VAR{key-list}, and \retvaliii{tail of
 101     \VAR{plist}} starting with \VAR{key}. Return \retval{\NIL},
 102   \retvalii{\NIL}, and  \retvaliii{\NIL} if there was no \VAR{key}.
 103
 104   \IT{\arrGOO{(\FU*{REMPROP} \VAR{ symbol} \VAR{ key})\\
 105       (\SF*{REMF} \VAR{ place} \VAR{ key})}{\}}}
 106   Remove fist entry \VAR{key} from property list stored in
 107   \VAR{symbol}/in \VAR{place}, resp. Return \retval{\T} if \VAR{key}
 108   was there, or \retval{\NIL} otherwise.
 109
 110 \end{LIST}
 111
 112
 113 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 114 \subsection{Functions}
 115 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 116 \label{section:Functions}
 117
 118
 119 Below, lambda list \OPn{\VAR{fu-arg}} has the form
 120 (\OPn{\VAR{var}}
 121 \OP{\kwd*{\&optional} \Goos{\VAR{var}\XOR(\VAR{var} \OP{\VAR{init}
 122       \Op{\VAR{supplied-p}}})}}
 123 \Op{\kwd*{\&rest} \VAR{var}}
 124 \OP{\kwd*{\&key} \GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
 125       \VAR{var})}
 126     \OP{\VAR{init}\Op{\VAR{supplied-p}}})}
 127   \Op{\kwd*{\&allow-other-keys}}}
 128 \OP{\kwd*{\&aux}\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}}
 129 ). \VAR{supplied-p} is \T\ if there is a corresponding argument.
 130
 131 \begin{LIST}{1cm}
 132
 133   \IT{(\xorGOO{\SF*{DEFUN} \VAR{ foo}\\ \SF*{LAMBDA}}{\}}
 134     (\VAR{\OPn{fu-arg}}) \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 135     \Op{\VAR{documentation}}
 136     \OPn{\VAR{form}})}
 137   Define function with \retval{name \VAR{foo}} or an anonymous
 138   function, resp., which
 139   applies \VAR{form}s to \VAR{fu-arg}s.
 140
 141   \IT{(\xorGOO{\SF*{FLET}\\ \SF*{LABELS}}{\}}%
 142     (\OPn{(\VAR{name}
 143       (\OPn{\VAR{fu-arg}})
 144       \OPn{(\kwd{declare} \OPn{\VAR{local-decl}})}%
 145       \Op{\VAR{documentation}}
 146       \OPn{\VAR{local-form}})})\OPn{(\kwd{declare} \VAR{decl})}
 147     \OPn{\VAR{form}})}
 148   Evaluate \VAR{form}s with
 149   locally defined functions \OPn{\VAR{name}}. Only for \SF{LABELS},
 150   \VAR{name}s are visible inside \VAR{local-forms}. Return
 151   \retval{values of \VAR{form}s}.
 152
 153   \IT{(\SF*{FUNCTION} \VAR{foo})} Return \retval{function named \VAR{foo}}.
 154
 155   \IT{(\FU*{APPLY} \VAR{function} \RP{\VAR{arg}})}
 156   Return \retval{value of \VAR{function}} called with
 157   \VAR{arg}s. Last \VAR{arg} must be a list.
 158
 159   \IT{(\FU*{FUNCALL} \VAR{function} \OPn{arg})}
 160   Return \retval{value of \VAR{function}} called with \VAR{arg}s.
 161
 162   \IT{(\SF*{MULTIPLE-VALUE-CALL} \VAR{foo} \OPn{\VAR{form}})} Call function
 163   \VAR{foo} with values of \VAR{form}s as its arguments.  Return
 164   \retval{values returned by \VAR{foo}}.
 165
 166   \IT{(\FU*{VALUES-LIST} \VAR{list})}
 167   Return \retval{elements of \VAR{list}}.
 168
 169   \IT{(\FU*{VALUES} \OPn{\VAR{foo}})}
 170   Return \retval{\VAR{foo}s} as multiple values. \kwd{setf}able.
 171
 172   \IT{(\FU*{MULTIPLE-VALUE-LIST} \OPn{\VAR{form}})}
 173   Return \retval{values of \VAR{form}s}.
 174
 175   \IT{(\FU*{COMPLEMENT} \VAR{function})}
 176   Return \retval{new function} with same arguments and same side effects
 177   as \VAR{function}, but with complementary truth value.
 178
 179   \IT{(\FU*{CONSTANTLY} \VAR{foo})}
 180   Return \retval{function} returning \VAR{foo}.
 181
 182   \IT{(\FU*{IDENTITY} \VAR{foo})}
 183   Return \retval{\VAR{foo}}.
 184
 185   \IT{(\FU*{FUNCTION-LAMBDA-EXPRESSION} \VAR{function})}
 186   If available, return \retval{Lambda expression} of \VAR{function},
 187   \retvalii{\NIL} if \VAR{function} was
 188   defined in null environment, and \retvaliii{name} of \VAR{function}.
 189
 190   \IT{(\FU*{FDEFINITION} \VAR{foo})}
 191   \retval{Definition} of function \VAR{foo}. \kwd{setf}able.
 192
 193   \IT{(\FU*{FMAKUNBOUND} \VAR{name})}
 194   Remove global function or macro definition \retval{\VAR{name}}.
 195
 196   \IT{\arrGOO{\CNS*{CALL-ARGUMENTS-LIMIT}\\
 197       \CNS*{LAMBDA-PARAMETERS-LIMIT}}{\}}}
 198   Upper bound of the number of function arguments or lambda list parameters, resp.; $>=50$.
 199
 200   \IT{\CNS*{MULTIPLE-VALUES-LIMIT}}
 201   Upper bound of the number of values a function can return; $>20$.
 202
 203 \end{LIST}
 204
 205
 206 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 207 \subsection{Macros}
 208 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 209
 210 Below, macro lambda list \OPn{\VAR{macro-arg}} has the form of either
 211 (\Op{\kwd*{\&whole} \VAR{var}}%
 212 \Op{\kwd*{\&environment} \VAR{var}}
 213 \OPn{\VAR{var}}
 214 \Op{\kwd*{\&environment} \VAR{var}}
 215 \Op{\kwd*{\&optional}\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}
 216       \Op{\VAR{supplied-p}}})}}
 217 \Op{\kwd*{\&environment} \VAR{var}}
 218 \Op{\Goo{\kwd*{\&rest}\XOR\kwd*{\&body}} \VAR{var}}
 219 \Op{\kwd*{\&environment} \VAR{var}}
 220 \OP{\kwd*{\&key}\GOos{\VAR{var}\XOR(\Goo{\VAR{var}\XOR(\kwd{:}\VAR{key}
 221       \VAR{var})}%
 222     \OP{\VAR{init}\Op{\VAR{supplied-p}}})}%
 223   \Op{\kwd*{\&environment} \VAR{var}}
 224   \Op{\kwd*{\&allow-other-keys}}}
 225 \Op{\kwd*{\&aux}\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}})}}%
 226 \Op{\kwd*{\&environment} \VAR{var}}
 227 )
 228 or\\
 229 (\Op{\kwd*{\&whole} \VAR{var}}%
 230 \Op{\kwd*{\&environment} \VAR{var}}
 231 \OPn{\VAR{var}}
 232 \Op{\kwd*{\&environment} \VAR{var}}
 233 \Op{\kwd*{\&optional}\Goos{\VAR{var}\XOR(\VAR{var} \Op{\VAR{init}
 234       \Op{\VAR{supplied-p}}})}}
 235 \Op{\kwd*{\&environment} \VAR{var}}
 236 . \VAR{var}).
 237 \kwd*{\&environment} \VAR{var} may appear only once.
 238 \VAR{supplied-p} is \T\ if there is a corresponding argument.
 239
 240
 241 \begin{LIST}{1cm}
 242
 243   \IT{(\xorGOO{\SF*{DEFMACRO}\\\FU*{DEFINE-COMPILER-MACRO}}{\}}
 244     \VAR{name} \OPn{\VAR{macro-arg}}
 245     \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Op{\VAR{documentation}}
 246     \OPn{\VAR{form}})}
 247   Define macro \retval{\VAR{name}}.
 248
 249   \IT{(\SF*{MACROLET} (\OPn{(\OPn{name} \OPn{\VAR{macro-arg}}
 250       \OPn{(\kwd{declare} \OPn{\VAR{local-decl}})}
 251       \Op{\VAR{documentation}} \OPn{form})}) \OPn{(\kwd{declare}
 252       \OPn{\VAR{decl}})} \OPn{\VAR{body}})}
 253   Evaluate \retval{\OPn{\VAR{body}}} with \VAR{name}s locally defined
 254   as corresponding macros which are invisible to each other.
 255
 256   \IT{(\SF*{SYMBOL-MACROLET} (\OPn{(\VAR{name}
 257       \OPn{\VAR{form}})})\OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 258     \OPn{body})}
 259   Evaluate \retval{\OPn{\VAR{body}}} with \VAR{name}s locally defined as
 260   corresponding symbol-macros.
 261
 262   \IT{(\SF*{DEFSETF} \VAR{function}\xorGOO{\VAR{update} \Op{\VAR{documentation}}\\
 263     \OPn{\VAR{arg} (\OPn{\VAR{var}}) \OPn{(\kwd{declare} \OPn{\VAR{
 264             decl}})} \Op{\VAR{documentation}}}}{\}})}
 265   Specify how to \kwd{setf} a place accessed by
 266   \retval{\VAR{function}} if \VAR{function} evaluates all its
 267   arguments.
 268
 269   \IT{(\SF*{DEFINE-SETF-EXPANDER} \VAR{function} \OPn{\VAR{macro-arg}}
 270     \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Op{\VAR{documentation}}
 271     \OPn{\VAR{form}})}
 272   Specify how to \kwd{setf} a place accessed by \retval{\VAR{function}}.
 273
 274   \IT{(\SF*{DEFINE-MODIFY-MACRO} \VAR{name} (\kwd{\&optional}
 275     \OPn{\VAR{var}} \kwd{\&rest} \OPn{\VAR{var}}) \VAR{function}
 276     \Op{documentation})}
 277   Define macro \retval{\VAR{name}} able to read and write a place. On
 278   invokation, after applying \VAR{function} to place its return value
 279   is stored there.
 280
 281   \IT{(\FU*{GET-SETF-EXPANSION} \VAR{place} \Op{\VAR{environment}})}
 282   Return five values describing how to \kwd{setf} place.
 283
 284   \IT{\CNS*{LAMBDA-LIST-KEYWORDS}} List of macro lambda list keywords.
 285
 286 \end{LIST}
 287
 288
 289 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 290 \subsection{Control Flow}
 291 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 292 \begin{LIST}{1cm}
 293
 294   \IT{(\SF*{IF} \VAR{test} \VAR{then} \Op{\VAR{else}})} Evaluate and return
 295   \retval{\VAR{then}} if \VAR{test} returns \T, evaluate and return
 296   \retval{\VAR{else}} otherwise.
 297
 298   \IT{(\SF*{COND} \OPn{(\VAR{test} \OPn{\VAR{then}})})}
 299   Evaluate and return the
 300   \retval{\VAR{then}s} whose \VAR{test} returns \T, return
 301   \retval{\NIL} if all \VAR{test}s return \NIL.
 302
 303   \IT{(\xorGOO{\SF*{WHEN}\\\SF*{UNLESS}}{\}} \VAR{test} \OPn{\VAR{foo}})}
 304   Evaluate \VAR{foo}s and return \retval{value of last \VAR{foo}} if
 305   \VAR{test} returns \T\ or \NIL, resp. Return \retval{\NIL} otherwise.
 306
 307   \IT{(\SF*{CASE} \VAR{object} \GOOs{(\GOop{\VAR{key}}\Goos{\VAR{foo}})}
 308     \Op{(\Goo{\LIT{t}\XOR\kwd*{OTHERWISE}}\Goos{\VAR{foo}})})}
 309   Evaluate first \VAR{foo}s whose unevaluated \VAR{key} is either \kwd{eql} evaluated
 310   \VAR{object} or \LIT{t} or \LIT{otherwise}. Return \retval{value of
 311     last evaluated \VAR{foo}}.
 312
 313   \IT{(\Goo{\SF*{CCASE}\XOR\SF*{ECASE}} \VAR{object} \Goos{(\GOop{\VAR{key}}\Goos{\VAR{foo}})})}
 314   Evaluate first \VAR{foo}s whose unevaluated \VAR{key} is \kwd{eql} evaluated
 315   \VAR{object}. Return \retval{value of last evaluated
 316     \VAR{foo}}. Signal correctible error/non-correctible error,
 317   resp., if no \VAR{key} matches and return \retval{\NIL} then.
 318
 319   \IT{(\SF*{AND} \OPn{\VAR{form}})} Evaluate \VAR{form}s from left to
 320   right. Immediately return \retval{\NIL} if one \VAR{form}'s value is \NIL. Return
 321   \retval{value of last \VAR{form}} otherwise. Without any \VAR{form}
 322   return \retval{\NIL}
 323
 324   \IT{(\SF*{OR} \OPn{\VAR{form}})} Evaluate \VAR{form}s from left to
 325   right. Immediately return \retval{value of first non-\NIL-evaluating
 326     form}. Return \retval{\NIL} if no \VAR{form} returns true.
 327   Return \retval{value of last \VAR{form}} otherwise.
 328
 329   \IT{(\kwd*{PROGN} \OPn{\VAR{form}})} Sequence \VAR{form}s. Return
 330   \retval{value of last \VAR{form}}.
 331
 332   \IT{(\xorGOO{\SF*{PROG}\\
 333       \SF*{PROG*}}{\}}
 334     (\orGOO{%
 335       \VAR{var}\\
 336       (\VAR{var } \Op{ \VAR{value}})}{\}^{\!\!*}})
 337     \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 338     \xorGOO{\VAR{tag}\\\VAR{form}}{\}^{\!\!*}})}
 339   Evaluate \kwd{TAGBODY}-like body with locally bound
 340   \VAR{var}s. Return \retval{\NIL} or explicitly \retval{\kwd{return}ed value}.
 341
 342   \IT{\arrGOO{%
 343       (\SF*{MULTIPLE-VALUE-PROG1} \VAR{ form-r} \OPn{\VAR{ form}})\\
 344       (\SF*{PROG1} \VAR{ form-r} \OPn{\VAR{ form}})\\
 345       (\SF*{PROG2} \VAR{ form-a} \VAR{ form-r} \OPn{\VAR{ form}})}{\}}}
 346   Evaluate all forms in order. Return \retval{values/1st value of \VAR{form-r}}.
 347
 348   \IT{(\SF*{PROGV} \VAR{symbols} \VAR{values} \OPn{form})}
 349   Evaluate \VAR{form}s with \VAR{symbols} dynamically bound to \VAR{values} or
 350   \NIL. Return \retval{values returned by \VAR{form}s}.
 351
 352   \IT{(\SF*{DESTRUCTURING-BIND} \VAR{foo} \VAR{bar}  \OPn{(\kwd{declare}
 353       \OPn{\VAR{decl}})} \OPn{\VAR{form}})} Evaluate \VAR{form}s, and return
 354   \retval{value of last \VAR{form}}, with
 355   variables from tree \VAR{foo} bound to corresponding elements of tree \VAR{bar}.
 356
 357   \IT{(\kwd*{MULTIPLE-VALUE-BIND} (\OPn{\VAR{var}}) \VAR{values-form}
 358     \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \OPn{\VAR{body-form}})} Evaluate
 359   body with \VAR{var}s bound to the return values of
 360   \VAR{values-form}. Return \retval{values returned by \VAR{body-form}s}.
 361
 362   \IT{(\xorGOO{\SF*{LET}\\
 363       \SF*{LET*}}{\}}(%
 364     \orGOO{\VAR{name}\\
 365       (\VAR{name}\Op{\VAR{value}})}{\}^{\!\!*}})
 366     \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 367     \OPn{\VAR{body}})}
 368   Evaluate \OPn{\VAR{body}} with \VAR{name}s bound to \VAR{value}s or
 369   \NIL. Return \retval{values returned by \OPn{\VAR{body}}}. In \SF{LET*},
 370   \VAR{value}s can refer to previous \VAR{name}s.
 371
 372   \IT{(\SF*{LOCALLY} \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 373     \OPn{\VAR{body}})}
 374   Evaluate \OPn{\VAR{body}} with declarations \VAR{decl} in
 375   effect. Return \retval{values returned by \OPn{\VAR{body}}}.
 376
 377   \IT{(\SF*{RETURN-FROM} \VAR{foo} \Op{result})} Have nearest enclosing
 378   \kwd{block} \VAR{foo} return with \VAR{result}.
 379
 380   \IT{(\SF*{RETURN} \Op{result})}
 381   Have enclosing block return with \retval{\VAR{result}}.
 382
 383   \IT{(\SF*{BLOCK} \VAR{name} \OPn{\VAR{form}})} Evaluate \VAR{form}s returning
 384   \retval{value of last \VAR{form}} unless interrupted by \SF{RETURN-FROM}.
 385
 386   \IT{(\SF*{TAGBODY} \Goos{\VAR{tag}\XOR\VAR{form}})}
 387   Evaluate \VAR{form}s. \VAR{tag}s (symbols or integers) are targets
 388   for \SF{GO}. Return \retval{\NIL}.
 389
 390   \IT{(\SF*{GO} \VAR{tag})} Jump within a \SF{tagbody} to nearest
 391   lexically enclosing \kwd{eql} \VAR{tag}.
 392
 393   \IT{(\SF*{CATCH} \VAR{tag} \OPn{\VAR{form}})}  Evaluate \VAR{form}s returning
 394   \retval{value of last \VAR{form}} unless interrupted by \SF{THROW}.
 395
 396   \IT{(\SF*{THROW} \VAR{tag form})} Have the nearest dynamically
 397   enclosing \SF{CATCH} with a tag \kwd{eq} \VAR{tag} return with the
 398   value of \VAR{form}.
 399
 400   \IT{(\FU*{BREAK} \VAR{control} \OPn{args})}
 401   Jump into debugger, return \retval{\NIL}.
 402   See p.\ \pageref{section:Format}, \kwd{format}, for \VAR{control}
 403   and \VAR{args}.
 404
 405   \IT{(\FU*{SLEEP} \VAR{n})} Wait \VAR{n} seconds, return \retval{\NIL}.
 406
 407 \end{LIST}
 408
 409
 410
 411 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 412 \subsection{Iteration}
 413 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 414
 415 \begin{LIST}{1cm}
 416
 417   \IT{(\xorGOO{\SF*{DO}\\\SF*{DO*}}{\}}
 418     (\orGOO{%
 419       \VAR{var}\\
 420       (\VAR{var} \Op{ \VAR{start} \Op{\VAR{step}}})}{\}^{\!\!*}})
 421     (\VAR{stop} \OPn{\VAR{result}})
 422     \OPn{(\kwd{declare} \OPn{\VAR{decl}})}
 423     \xorGOO{\VAR{tag}\\\VAR{form}}{\}^{\!\!*}})}
 424   Evaluate \SF{TAGBODY}-like body with \VAR{var}s successively bound according
 425   to the values of the corresponding \VAR{start} and \VAR{step}
 426   forms. \VAR{var}s are bound in parallel/sequentially, resp.
 427   Stop iteration when \VAR{stop} is \T. Return \retval{value of
 428     last \VAR{result}}.
 429
 430   \IT{(\SF*{DOTIMES} (\VAR{var} \VAR{integer} \Op{\VAR{result}})
 431     \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Goos{\VAR{tag}\XOR\VAR{form}})}
 432   Evaluate \SF{TAGBODY}-like body with \VAR{var} successively bound
 433   to integers from 0 to $\mbox{\VAR{integer}} - 1$. Upon evaluation of
 434   \retval{\VAR{result}}, \VAR{var} is \NIL.
 435
 436   \IT{(\SF*{DOLIST}(\VAR{var} \VAR{list} \Op{\VAR{result}})
 437     \OPn{(\kwd{declare} \OPn{\VAR{decl}})} \Goos{\VAR{tag}\XOR\VAR{form}})}
 438   Evaluate \SF{TAGBODY}-like body with \VAR{var} successively bound
 439   to the elements of \VAR{list}. Upon evaluation of
 440   \retval{\VAR{result}}, \VAR{var} is \NIL.
 441
 442
 443 \end{LIST}
 444
 445 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 446 \subsection{Loop Facility}
 447 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 448
 449 \begin{figure}%
 450   \label{loop-overview}%
 451   \begin{center}%
 452     \begin{sideways}%
 453       (%
 454       \arraycolsep0pt
 455       \(
 456       \text{\kwd{loop}}
 457       \left[
 458         \text{\LKWD{named} \VAR{n}}
 459         \right]
 460       \left\{
 461       \begin{array}{l}
 462         \text{\LKWD{with} \VAR{var} [\VAR{type}] \LKWD{=} \VAR{foo }}
 463         \{\text{\LKWD{and} \VAR{var-n} [\VAR{type}] \LKWD{=} \VAR{bar}\}}^{*} \\
 464         \left.
 465         \begin{array}{l}
 466           \text{\LKWD{for}}  \\
 467           \text{\LKWD{as}}
 468         \end{array}\right\}
 469         \boxed{
 470           \text{\VAR{var} [\VAR{type}]}
 471           \left\{
 472           \begin{array}{l}
 473             \left.
 474             \begin{array}{l}
 475               \left[
 476                 \left\{
 477                 \begin{array}{l}
 478                   \text{\LKWD{upfrom}}\\
 479                   \text{\LKWD{from}}
 480                 \end{array}
 481                 \right\}
 482                 \text{\VAR{start}\DF{0}}
 483                 \right]
 484               \left[
 485                 \left\{
 486                 \begin{array}{l}
 487                   \text{\LKWD{upto}}\\
 488                   \text{\LKWD{to}}\\
 489                   \text{\LKWD{below}}
 490                 \end{array}
 491                 \right\}
 492                 \text{\VAR{form}}
 493                 \right]\\
 494               \text{\LKWD{from} \VAR{start}}
 495               \left\{
 496               \begin{array}{l}
 497                 \text{\LKWD{downto}}\\
 498                 \text{\LKWD{above}}
 499               \end{array}
 500               \right\}
 501               \text{\VAR{form }}\\
 502               \text{\LKWD{downfrom} \VAR{start}}
 503               \left[
 504                 \left\{
 505                 \begin{array}{l}
 506                   \text{\LKWD{downto}}\\
 507                   \text{\LKWD{to}}\\
 508                   \text{\LKWD{above}}
 509                 \end{array}
 510                 \right\}
 511                 \text{\VAR{form}}
 512                 \right]
 513             \end{array}
 514             \right\}
 515             \left[
 516               \text{\LKWD{by} \VAR{step}\DF{1}}
 517               \right]\\
 518             \left.
 519             \begin{array}{l}
 520               \text{\LKWD{in}} \\
 521               \text{\LKWD{on}}
 522             \end{array}
 523             \right\}
 524             \text{\VAR{list}}
 525             \left[
 526               \text{\LKWD{by} \VAR{form}\DF{\kwd{\#'cdr}}}
 527               \right]\\
 528             \text{\LKWD{=} \VAR{foo }}
 529             \left[
 530               \text{\LKWD{then} \VAR{bar}}
 531               \right] \\
 532             \text{\LKWD{across} \VAR{vector}}\\
 533             \text{\LKWD{being}}
 534             \left\{
 535             \begin{array}{l}
 536               \text{\LKWD{the}}\\
 537               \text{\LKWD{each}}
 538             \end{array}
 539             \right\}
 540             \left\{
 541             \begin{array}{{l}}
 542               \left.
 543               \begin{array}{l}
 544                 \left.
 545                 \begin{array}{l}
 546                   \text{\LKWD{hash-key}}\\
 547                   \text{\LKWD{hash-keys}}
 548                 \end{array}
 549                 \right\}
 550                 \left\{
 551                 \begin{array}{l}
 552                   \text{\LKWD{of}}\\
 553                   \text{\LKWD{in}}
 554                 \end{array}
 555                 \right\}
 556                 \text{\VAR{hash }}
 557                 \left[
 558                   \text{\LKWD{using} (\LKWD{hash-value} \VAR{v})}
 559                   \right]\\
 560                 \left.
 561                 \begin{array}{l}
 562                   \text{\LKWD{hash-value}}\\
 563                   \text{\LKWD{hash-values}}
 564                 \end{array}
 565                 \right\}
 566                 \left\{
 567                 \begin{array}{l}
 568                   \text{\LKWD{of}}\\
 569                   \text{\LKWD{in}}
 570                 \end{array}
 571                 \right\}
 572                 \text{\VAR{hash }}
 573                 \left[
 574                   \text{\LKWD{using} (\LKWD{hash-key} \VAR{k})}
 575                   \right.\\
 576               \end{array}
 577               \right.\\
 578               \left.
 579               \begin{array}{l}
 580                 \text{\LKWD{symbol\Op{s}}}\\
 581                 \text{\LKWD{present-symbol\Op{s}}}\\
 582                 \text{\LKWD{external-symbol\Op{s}}}
 583               \end{array}
 584               \right\}
 585               \left[
 586                 \left\{
 587                 \begin{array}{l}
 588                   \text{\LKWD{of}}\\
 589                   \text{\LKWD{in}}
 590                 \end{array}
 591                 \right\} \text{\VAR{package}\DF{\V{*package*}}}
 592                 \right]
 593             \end{array}
 594             \right.
 595           \end{array}
 596           \right\}_{\displaystyle{\mathbb{F}_0}}
 597                 }%boxed
 598                 \left\{
 599                 \text{\LKWD{and} }\boxed{\mathbb{F}_i}
 600                 \right\}^{\!*}\\
 601                 \left.%
 602                 \begin{array}{l}
 603                   \text{\LKWD{initially}} \\
 604                   \text{\LKWD{finally}}
 605                 \end{array}
 606                 \right\}
 607                 \text{\VAR{form}}^{+} \\
 608
 609       \end{array}
 610       \right\}^{\!\!\displaystyle{*}}
 611       %Bottleneck
 612       \left\{
 613       \begin{array}{l}
 614         \text{\LKWD{repeat} \VAR{num}}\\
 615         \left.
 616         \begin{array}{l}
 617           \text{\LKWD{while}}\\
 618           \text{\LKWD{until}}\\
 619           \text{\LKWD{always}}\\
 620           \text{\LKWD{never}}\\
 621           \text{\LKWD{thereis}}
 622         \end{array}
 623         \right\}
 624         \text{\VAR{test}}\\
 625         \boxed{
 626           \left.
 627           \begin{array}{l}
 628             \left.
 629             \begin{array}{l}
 630               \text{\LKWD{do}}\\
 631               \text{\LKWD{doing}}
 632             \end{array}
 633             \right\}
 634             \text{\VAR{form}}^{+}\\
 635             \text{\LKWD{return}}
 636             \left\{
 637             \begin{array}{l}
 638               \text{\VAR{form}}\\
 639               \text{\LKWD{it}}
 640             \end{array}
 641             \right.\\
 642             \left.
 643             \begin{array}{l}
 644               \text{\LKWD{collect\Op{ing}}}\\
 645               \text{\LKWD{append\Op{ing}}}\\
 646               \text{\LKWD{nconc\Op{ing}}}
 647             \end{array}
 648             \right\}
 649             \left\{
 650             \begin{array}{l}
 651               \text{\VAR{form}}\\
 652               \text{\LKWD{it}}
 653             \end{array}
 654             \right\} [\text{\LKWD{into }\VAR{var}}]\\
 655             \left.
 656             \begin{array}{l}
 657               \text{\LKWD{count\Op{ing}}}\\
 658               \text{\LKWD{sum\Op{ming}}}\\
 659               \text{\LKWD{maximize}}\\
 660               \text{\LKWD{maximizing}}\\
 661               \text{\LKWD{minimize}}\\
 662               \text{\LKWD{minimizing}}
 663             \end{array}
 664             \right\}
 665             \left\{
 666             \begin{array}{l}
 667               \text{\VAR{form}}\\
 668               \text{\LKWD{it}}
 669             \end{array}
 670             \right\}
 671                 [\text{\LKWD{into }\VAR{n}}]
 672                 [\text{\VAR{type}}]\\
 673                 \left.
 674                 \begin{array}{l}
 675                   \text{\LKWD{if}}\\
 676                   \text{\LKWD{when}}\\
 677                   \text{\LKWD{unless}}
 678                 \end{array}
 679                 \right\}
 680                 \text{\VAR{test }}
 681                 \boxed{\mathbb{S}_i}\{\text{\LKWD{and}}%
 682                 \boxed{\mathbb{S}_j}\}^{*}[\text{\LKWD{else}}%
 683                   \boxed{\mathbb{S}_k}\{\text{\LKWD{and}}%
 684                   \boxed{\mathbb{S}_l}\}^{*}][\text{\LKWD{end}}]
 685           \end{array}
 686           \right._{\displaystyle{\mathbb{S}_0}}
 687         }%boxed
 688         \\
 689         \left.
 690         \begin{array}{l}
 691           \text{\LKWD{initially}} \\
 692           \text{\LKWD{finally}}
 693         \end{array}
 694         \right\}
 695         \text{\VAR{form}}^{+}
 696       \end{array}
 697       \right\}^{\displaystyle{\!\!*}}
 698       \)%
 699       \!)%
 700     \end{sideways}%
 701   \end{center}\vspace{-1em}
 702   \caption{Loop Facility, Overview.}%
 703 \end{figure}
 704
 705
 706 \begin{LIST}{1cm}
 707
 708   \IT{(\SF*{LOOP} \OPn{\VAR{form}})}
 709   Simple Loop. If \VAR{form}s do
 710   not include any keywords of the Loop Facility, evaluate them forever.
 711
 712   \IT{(\SF*{LOOP} \OPn{\VAR{form}})}
 713   Loop Facility. If there are loop facility keywords in \VAR{form}s
 714   see below and p.\ \pageref{loop-overview}.
 715
 716   \begin{LIST}{.5cm}
 717
 718     \IT{\LKWD*{named} \VAR{n}}
 719     Gives implicit \kwd{block} of loop a name.
 720
 721     \IT{\LKWD*{with} \VAR{var} \LKWD*{=} \VAR{foo} \Op{\VAR{type}} \Goo{\LKWD*{and}
 722         \VAR{var-n} \Op{\VAR{type}} \LKWD*{=} \VAR{bar}}}
 723     Initialize local variables in parallel.
 724
 725     \IT{\Goo{\LKWD*{initially}\XOR\LKWD*{finally}} \RP{\VAR{form}}}
 726     Evaluate \VAR{form} before begin, or after end, resp., of iterations.
 727
 728     \IT{\Goo{\LKWD*{for}\XOR\LKWD*{as}} \VAR{var} \VAR{type}}
 729     Begin of iteration control clause.
 730
 731     \begin{LIST}{.25cm}
 732
 733       \IT{\Goo{\LKWD*{upfrom}\XOR\LKWD*{from}\XOR\LKWD*{downfrom}} \VAR{start}}
 734       Start stepping with \VAR{form}
 735
 736       \IT{\Goo{\LKWD*{upto}\XOR\LKWD*{downto}\XOR\LKWD*{to}\XOR\LKWD*{below}\XOR\LKWD*{above}} \VAR{form}}
 737       Specify \VAR{form} as the end value for stepping.
 738
 739       \IT{\Goo{\LKWD*{in}\XOR\LKWD*{on}} \VAR{list}}
 740       Bind \VAR{var} to successive elements/tails, resp., of \VAR{list}.
 741
 742       \IT{\LKWD*{by} \VAR{step}\DF{1}}
 743       Specify the (positive) decrement or increment.
 744
 745       \IT{\LKWD*{=} \VAR{foo} \Op{\LKWD*{then} \VAR{bar}\DF{\VAR{foo}}}}
 746       Bind \VAR{var} in the first iteration to  \VAR{foo} and later to \VAR{bar}.
 747
 748       \IT{\LKWD*{across} \VAR{vector}}
 749       Bind \VAR{var} to successive elements of \VAR{vector}.
 750
 751       \IT{\LKWD*{being}\Goo{\LKWD*{the}\XOR\LKWD*{each}}}
 752       Iterate over a hash table or a package.
 753
 754       \begin{LIST}{.5cm}
 755
 756         \IT{\Goo{\LKWD*{hash-key}\XOR\LKWD*{hash-keys}}\Goo{\LKWD*{of}\XOR\LKWD*{in}} \VAR{hash-table}
 757           \Op{\LKWD*{using} (\LKWD*{hash-value} \VAR{value})}}
 758         Bind \VAR{var} successively to the keys of \VAR{hash-table}; bind corresponding values to \VAR{value}.
 759
 760         \IT{\Goo{\LKWD*{hash-value}\XOR\LKWD*{hash-values}}\Goo{\LKWD*{of}\XOR\LKWD*{in}} \VAR{hash-table}
 761           \Op{\LKWD*{using} (\LKWD*{hash-key} \VAR{key})}}
 762         Bind \VAR{var} successively to the values of \VAR{hash-table}; bind corresponding keys to \VAR{key}.
 763
 764         \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}}}
 765         Bind \VAR{var} successively to the symbols, or the present symbols, or the external symbols, resp., of \VAR{package}.
 766
 767       \end{LIST}
 768     \end{LIST}
 769
 770     \IT{\LKWD*{and} \VAR{var}}
 771     Begin of another iteration control clause with variables initialized and stepped in parallel.
 772
 773     \IT{\Goo{\LKWD*{do}\XOR\LKWD*{doing}} \RP{\VAR{form}}}
 774     Evaluate \VAR{form}s in every iteration.
 775
 776     \IT{\LKWD*{return} \Goo{\VAR{form}\XOR\LKWD*{it}}}
 777     Return immediately with return value \VAR{form}.
 778
 779     \IT{\Goo{\LKWD*{collect}\XOR\LKWD*{collecting}}\Goo{\VAR{form}\XOR\LKWD*{it}}\Op{\LKWD*{into} \VAR{list}}}
 780     Collect values of \VAR{form} into \VAR{list}. If no \VAR{list} is given, collect into an anonymous list
 781     which is returned after termination.
 782
 783     \IT{\Goo{\LKWD*{append}\XOR\LKWD*{appending}\XOR\LKWD*{nconc}\XOR\LKWD*{nconcing}}\Goo{\VAR{form}\XOR\LKWD*{it}}\Op{\LKWD*{into} \VAR{list}}}
 784     Concatenate values of \VAR{form}, which must be lists, into \VAR{list} by the means of \FU{append}
 785     or \FU{nconc}, resp.  If no \VAR{list} is given, collect into an anonymous list
 786     which is returned after termination.
 787
 788     \IT{\Goo{\LKWD*{count}\XOR\LKWD*{counting}}\Goo{\VAR{form}\XOR\LKWD*{it}}\Op{\LKWD*{into} \VAR{n}}}
 789     Count the number of times \VAR{form} returns \T.
 790
 791     \IT{\Goo{\LKWD*{sum}\XOR\LKWD*{summing}}\Goo{\VAR{form}\XOR\LKWD*{it}}\Op{\LKWD*{into} \VAR{sum}}}
 792     Calculate the sum of the values of \VAR{form}.
 793
 794     \IT{\Goo{\LKWD*{maximize}\XOR\LKWD*{maximizing}\XOR
 795         \LKWD*{minimize}\XOR
 796         \LKWD*{minimizing}}\Goo{\VAR{form}\XOR\LKWD*{it}}\Op{\LKWD*{into}
 797         \VAR{max-min}}}
 798     Determine the maximum or minimum, resp., of all values of
 799     \VAR{form}.
 800
 801     \IT{\Goo{\LKWD*{if}\XOR\LKWD*{when}\XOR\LKWD*{unless}}\VAR{ test}
 802       \VAR{form-i} \Goos{\LKWD*{and}
 803         \VAR{form-j}}\Op{\LKWD*{else} \VAR{form-k} \Goos{\LKWD*{and}
 804           \VAR{form-l}}} \Op{\LKWD*{end}}}
 805     If \VAR{test} returns \T, \T, or \NIL, resp., evaluate
 806     \VAR{form-i} and \VAR{form-j}s; otherwise, evaluate \VAR{form-k}
 807     and \VAR{form-l}s. Inside \VAR{form-i} and \VAR{form-k}, the value
 808     of \VAR{test} is accessible by \LKWD*{it}.
 809
 810     \IT{\LKWD*{repeat} \VAR{num}}
 811     Terminate \SF{loop} after \VAR{num} times; \VAR{num} is evaluated once.
 812
 813     \IT{\Goo{\LKWD*{while}\XOR\LKWD*{until}} \VAR{test}}
 814     Continue iteriation until \VAR{test} returns \NIL, or \T, resp.
 815
 816     \IT{\Goo{\LKWD*{always}\XOR\LKWD{never}} \VAR{test}}
 817     Terminate \SF{loop} returning \NIL\ and skipping any \LKWD*{finally} parts as soon as \VAR{test} is \NIL, or \T, resp. Otherwise continue \SF{loop} with its default return value set to \T.
 818
 819     \IT{\LKWD*{thereis} \VAR{test}}
 820     Terminate \SF{loop} when \VAR{test} is \T\ and return value of \VAR{form}, skipping any \LKWD*{finally} parts. Otherwise continue \SF{loop} with its default return value set to \T.
 821
 822     \IT{\LKWD*{loop-finish}}
 823     Terminate \SF{loop} immediately; skip any \LKWD*{finally} parts
 824   \end{LIST}
 825 \end{LIST}
 826
 827