clqr-compiler.tex

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