clqr-compiler.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{Compiler}
  12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  13
  14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  15 \subsection{Predicates}
  16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  17
  18 \begin{LIST}{1cm}
  19
  20   \IT{(\FU*{SPECIAL-OPERATOR-P} \VAR{foo})}
  21   {
  22   \retval{\T} if \VAR{foo} is a special operator.
  23   }
  24
  25   \IT{(\FU*{COMPILED-FUNCTION-P} \VAR{foo})}
  26   {
  27   \retval{\T} if \VAR{foo} is of type \kwd{compiled-function}.
  28   }
  29
  30 \end{LIST}
  31
  32
  33 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  34 \subsection{Compilation}
  35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  36
  37 \begin{LIST}{1cm}
  38
  39   \IT{(\FU*{COMPILE}
  40     \xorGOO{\NIL\VAR{ definition}\\
  41       \VAR{name }\Op{\VAR{definition}}}{\}}
  42     )}
  43   {
  44   Return \retval{compiled function} or replace \retval{\VAR{name}}'s
  45   function definition with the compiled function. Return \retvalii{\T} in case
  46   of warnings or errors, and \retvaliii{\T} in case of warnings
  47   or errors excluding style warnings.
  48   }
  49
  50   \IT{(\FU*{COMPILE-FILE} \VAR{file}
  51     \orGOO{\kwd{:output-file}\VAR{ out-path}\\
  52       \kwd{:verbose} \VAR{ bool}\DF{\V{\A compile-verbose\A}}\\
  53       \kwd{:print}\VAR{ bool}\DF{\V{\A compile-print\A}}\\
  54       \kwd{:external-format} \VAR{
  55         file-format}\DF{\kwd{:default}}}{\}})}
  56   {
  57   Write compiled contents of \VAR{file} to \VAR{out-path}.
  58   Return \retval{true output path} or \retval{\NIL}, \retvalii{\T}
  59   in case of warnings or errors, \retvaliii{\T} in case of warnings
  60   or errors excluding style warnings.
  61   }
  62
  63   \IT{\arrGOO{\V*{\A compile-file-pathname\A}\DF{\NIL}\\
  64       \V*{\A compile-file-truename\A}\DF{\NIL}}{.}}
  65   {
  66   Input file used by \FU{compile-file}.
  67   }
  68
  69   \IT{\arrGOO{\V*{\A compile-print\A}\\
  70       \V*{\A compile-verbose\A}}{.}}
  71   {
  72   Defaults used in \FU{compile-file}.
  73   }
  74
  75   \IT{(\FU*{COMPILE-FILE-PATHNAME} \VAR{file} \Op{\kwd{:output-file}
  76       \VAR{path}} \Op{\VAR{other-keyargs}})}
  77   {
  78   \retval{Pathname} \FU{COMPILE-FILE} writes to if invoked with the
  79   same arguments.
  80   }
  81
  82   \IT{(\FU*{LOAD} \VAR{path}
  83     \orGOO{\kwd{:verbose} \VAR{ bool}\DF{\V{\A load-verbose\A}}\\
  84       \kwd{:print} \VAR{ bool}\DF{\V{\A load-print\A}}\\
  85       \kwd{:if-does-not-exist} \VAR{ bool}\DF{\T}\\
  86       \kwd{:external-format} \VAR{
  87         file-format}\DF{\kwd{:default}}}{\}})}
  88   {
  89   Load source file or compiled file into Lisp environment. Return
  90   \retval{\T} if successful.
  91   }
  92
  93   \IT{\arrGOO{\V*{\A load-pathname\A}\DF{\NIL}\\
  94       \V*{\A load-truename\A}\DF{\NIL}}{.}}
  95   {
  96   Input file used by \FU{load}.
  97   }
  98
  99   \IT{\arrGOO{\V*{\A load-print\A}\DF{\NIL}\\
 100       \V*{\A load-verbose\A}}{.}}
 101   {
 102   Defaults used in \FU{load}.
 103   }
 104
 105   \IT{(\SO*{EVAL-WHEN} (%
 106     \orGOO{\Goo{\kwd{:compile-toplevel}\XOR\kwd{compile}}\\
 107       \Goo{\kwd{:load-toplevel}\XOR\kwd{load}}\\
 108       \Goo{\kwd{:execute}\XOR\kwd{eval}}}{\}}) \PROGN{\VAR{form}})}
 109   {
 110   Return \retval{values of \VAR{form}s} if
 111   \SO{EVAL-WHEN} is in the top-level of a file being compiled, in the
 112   top-level of a compiled file being loaded, or anywhere,
 113   respectively. Return \retval{\NIL} if \VAR{form}s are not
 114   evaluated. (\kwd{compile}, \kwd{load} and \kwd{eval} deprecated.)
 115   }
 116
 117   \IT{(\MC*{WITH-COMPILATION-UNIT} (\Op{\kwd{:override}
 118       \VAR{bool}\DF{\NIL}}) \PROGN{\VAR{form}})}
 119   {
 120   Return \retval{values of \VAR{form}s}. Warnings deferred by the
 121   compiler until end of compilation are deferred until the end of
 122   evaluation of \VAR{form}s.
 123   }
 124
 125   \IT{(\SO*{LOAD-TIME-VALUE} \VAR{form}
 126     \Op{\VAR{read-only}\DF{\NIL}})}
 127   {
 128   Evaluate \VAR{form} at compile time and treat \retval{its value} as
 129   literal at run time.
 130   }
 131
 132   \IT{(\SO*{QUOTE} \VAR{foo})}
 133   {
 134   Return \retval{unevaluated \VAR{foo}}.
 135   }
 136
 137   \IT{(\GFU*{MAKE-LOAD-FORM} \VAR{foo} \Op{\VAR{environment}})}
 138   {
 139   Its methods are to return a \retval{creation form} which on
 140   evaluation at \FU{load} time returns an object equivalent to
 141   \VAR{foo}, and an optional \retvalii{initialization form} which on
 142   evaluation performs some initialization of the object.
 143   }
 144
 145   \IT{(\FU*{MAKE-LOAD-FORM-SAVING-SLOTS} \VAR{foo}
 146     \orGOO{\kwd{:slot-names} \VAR{ slots}\\
 147       \kwd{:environment}  \VAR{ environment}}{\}})}
 148   {
 149   Return a \retval{creation form} and an \retvalii{initialization
 150     form} which on evaluation construct an object equivalent to
 151   \VAR{foo} with \VAR{slots} initialized with the corresponding values
 152   from \VAR{foo}.
 153   }
 154
 155   \IT{\arrGOO{(\FU*{MACRO-FUNCTION} \VAR{ symbol }
 156       \Op{\VAR{environment}})\\
 157       (\FU*{COMPILER-MACRO-FUNCTION} \VAR{ name }
 158       \Op{\VAR{environment}})}{.}}
 159   {
 160   Return specified \retval{macro function}, or \retval{compiler mac\-ro
 161     func\-tion}, respectively, if any. Return \retval{\NIL}
 162   otherwise. \kwd{setf}able.
 163   }
 164
 165   \IT{(\FU*{EVAL} \VAR{arg})}
 166   {
 167   Return \retval{values of value of \VAR{arg}} evaluated in global environment.
 168   }
 169
 170 \end{LIST}
 171
 172
 173 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 174 \subsection[REPL~\&~Debug]{REPL and Debugging}
 175 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 176
 177 \begin{LIST}{1cm}
 178
 179   \IT{\arrGOO{\V*{+}\XOR\V*{++}\XOR\V*{+++}\\[1pt]
 180       \V*{\A}\text{ }\XOR\text{ }\V*{\A\A}\text{ }\XOR\text{ }\V*{\A\A\A}\\[1pt]
 181       \V*{/}\text{ }\XOR\text{ }\V*{//}\text{ }\XOR\text{ }\V*{///}}{.}}
 182   {
 183   Last, penultimate, or antepenultimate \retval{form} evaluated in the REPL, or
 184   their respective \retval{primary value}, or a \retval{list} of their respective
 185   values.
 186   }
 187
 188   \IT{\V*{--}}
 189   {
 190   \retval{Form} currently being evaluated by the REPL.
 191   }
 192
 193   \IT{(\FU*{APROPOS} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
 194   {
 195   Print interned symbols containing \VAR{string}.
 196   }
 197
 198   \IT{(\FU*{APROPOS-LIST} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
 199   {
 200   \retval{List of interned symbols} containing \VAR{string}.
 201   }
 202
 203   \IT{(\FU*{DRIBBLE} \Op{\VAR{path}})}
 204   {
 205   Save a record of interactive session to file at \VAR{path}. Without
 206   \VAR{path}, close that file.
 207   }
 208
 209   \IT{(\FU*{ED} \Op{\VAR{file-or-function}\DF{\NIL}})}
 210   {
 211   Invoke editor if possible.
 212   }
 213
 214   \IT{(\xorGOO{\FU*{MACROEXPAND-1}\\
 215       \FU*{MACROEXPAND}}{\}} \VAR{form} \Op{\VAR{environment}})}
 216   {
 217   Return \retval{macro expansion}, once or entirely, respectively, of
 218   \VAR{form} and \retvalii{\T} if \VAR{form} is a macro form.
 219   Return \retval{\VAR{form}} and \retvalii{\NIL} otherwise.
 220   }
 221
 222   \IT{\V*{\A macroexpand-hook\A}}
 223   {
 224   Function called by \FU{macroexpand-1} to generate macro expansions.
 225   }
 226
 227   \IT{(\MC*{TRACE} \OPn{\VAR{function}})}
 228   {
 229   Cause \VAR{function}s to be traced. With no arguments,
 230   return \retval{list of traced functions}.
 231   }
 232
 233   \IT{(\MC*{UNTRACE} \OPn{\VAR{function}})}
 234   {
 235   Stop \VAR{function}s, or each currently traced function, from being
 236   traced.
 237   }
 238
 239   \IT{\V*{\A trace-output\A}}
 240   {
 241   Stream \MC{trace} and \MC{time} print their output on.
 242   }
 243
 244   \IT{(\MC*{STEP} \VAR{form})}
 245   {
 246   Step through evaluation of \VAR{form}. Return \retval{values of
 247     \VAR{form}}.
 248   }
 249
 250   \IT{(\FU*{BREAK} \Op{\VAR{control} \OPn{\VAR{arg}}})}
 251   {
 252   Jump directly into debugger; return \retval{\NIL}.
 253   See p.\ \pageref{section:Format}, \FU{format}, for \VAR{control}
 254   and \VAR{arg}s.
 255   }
 256
 257   \IT{(\MC*{TIME} \VAR{form})}
 258   {
 259   Evaluate \VAR{form}s and print timing information to
 260   \V{\A trace-output\A}. Return \retval{values of \VAR{form}s}.
 261   }
 262   \IT{(\FU*{INSPECT} \VAR{foo})}
 263   {
 264     Interactively give information about \VAR{foo}.
 265   }
 266
 267   \IT{(\FU*{DESCRIBE} \VAR{foo}
 268     \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
 269   {
 270   Send information about \VAR{foo} to \VAR{stream}.
 271   }
 272
 273   \IT{(\GFU*{DESCRIBE-OBJECT} \VAR{foo} \Op{\DES{\VAR{stream}}})}
 274   {
 275   Send information about \VAR{foo} to \VAR{stream}. Not to be
 276   called by user.
 277   }
 278
 279   \IT{(\FU*{DISASSEMBLE} \VAR{function})}
 280   {
 281   Send disassembled representation of \VAR{function} to
 282   \V{\A standard-output\A}. Return \retval{\NIL}.
 283   }
 284
 285 \end{LIST}
 286
 287
 288 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 289 \subsection{Declarations}
 290 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 291 \begin{LIST}{1cm}
 292
 293   \IT{\arrGOO{(\FU*{PROCLAIM} \VAR{ decl})\\
 294       (\MC*{DECLAIM } \OPn{\NEV{\VAR{decl}}})}{.}} % FIXME:DECLARATION-ID-LIST
 295   {
 296   Globally make declaration(s) \VAR{decl}. \VAR{decl} can be:
 297   \kwd{declaration},
 298   \kwd{type},
 299   \kwd{ftype},
 300   \kwd{inline},
 301   \kwd{notinline},
 302   \kwd{optimize}, or
 303   \kwd{special}.
 304   See below.
 305   }
 306
 307   \IT{(\kwd*{DECLARE} \OPn{\NEV{\VAR{decl}}})}
 308   {
 309   Inside certain forms, locally make declarations \OPn{\VAR{decl}}. \VAR{decl} can be:
 310   \kwd{dynamic-extent},
 311   \kwd{type},
 312   \kwd{ftype},
 313   \kwd{ignorable},
 314   \kwd{ignore},
 315   \kwd{inline},
 316   \kwd{notinline},
 317   \kwd{optimize}, or
 318   \kwd{special}.
 319   See below.
 320   }
 321
 322   \begin{LIST}{.5cm}
 323
 324     \IT{(\kwd*{DECLARATION} \OPn{foo})}
 325     {
 326     Make \VAR{foo}s names of declarations.
 327    }
 328
 329     \IT{(\kwd*{DYNAMIC-EXTENT} \OPn{\VAR{variable}} \OPn{(\kwd{function}
 330         \VAR{function})})}
 331     {
 332     Declare lifetime of \VAR{variable}s and/or \VAR{function}s to end
 333     when control leaves enclosing block.
 334   }
 335
 336
 337     \IT{\arrGOO{(\kwd*{TYPE} \VAR{ type} \OPn{\VAR{ variable}})\\
 338         (\kwd*{FTYPE} \VAR{ type} \OPn{\VAR{ function}})}{.}}
 339     {
 340     Declare \VAR{variable}s or \VAR{function}s to be of \VAR{type}.
 341   }
 342
 343     \IT{(\xorGOO{\kwd*{IGNORABLE}\\
 344         \kwd*{IGNORE}}{\}}
 345       \xorGOO{%
 346         \VAR{var}\\
 347         (\kwd{function} \VAR{ function})}{\}^{\!\!*}})}
 348     {
 349     Suppress warnings about used/unused bindings.
 350   }
 351
 352     \IT{\arrGOO{(\kwd*{INLINE} \OPn{\VAR{ function}})\\
 353         (\kwd*{NOTINLINE} \OPn{\VAR{ function}})}{.}}
 354     {
 355     Tell compiler to integrate/not to integrate, respectively, called
 356     \VAR{function}s into the calling routine.
 357   }
 358
 359     \IT{(\kwd*{OPTIMIZE} \orGOO{%
 360         \kwd*{COMPILATION-SPEED}\XOR(\kwd*{COMPILATION-SPEED}\VAR{ n}\DF{\LIT{3}})\\
 361         \kwd*{DEBUG}\XOR(\kwd*{DEBUG}\VAR{ n}\DF{\LIT{3}})\\
 362         \kwd*{SAFETY}\XOR(\kwd*{SAFETY}\VAR{ n}\DF{\LIT{3}})\\
 363         \kwd*{SPACE}\XOR(\kwd*{SPACE}\VAR{ n}\DF{\LIT{3}})\\
 364         \kwd*{SPEED}\XOR(\kwd*{SPEED}\VAR{ n}\DF{\LIT{3}})}{\}})}
 365     {
 366     Tell compiler how to optimize. $n=0$ means unimportant, $n=1$ is
 367     neutral, $n=3$ means important.
 368   }
 369
 370     \IT{(\kwd*{SPECIAL} \OPn{\VAR{var}})}
 371     {
 372     Declare \VAR{var}s being dynamic.
 373   }
 374
 375   \end{LIST}
 376 \end{LIST}
 377
 378
 379
 380
 381 % LocalWords:  mac ro func tion