clqr-compiler.tex

   1 % Copyright (C) 2008, 2009, 2010, 2011, 2012, 2014, 2018
   2 % Bert Burgemeister
   3 %
   4 % Permission is granted to copy, distribute and/or modify this
   5 % document under the terms of the GNU Free Documentation License,
   6 % Version 1.2; 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
  46     \retvalii{\T} in case of \kwd{warning}s or \kwd{error}s, and
  47     \retvaliii{\T} in case of \kwd{warning}s or \kwd{error}s excluding
  48     \kwd{style-warning}s.
  49   }
  50
  51   \IT{(\FU*{COMPILE-FILE} \VAR{file}
  52     \orGOO{\kwd{:output-file}\VAR{ out-path}\\
  53       \kwd{:verbose} \VAR{ bool}\DF{\V{\A compile-verbose\A}}\\
  54       \kwd{:print}\VAR{ bool}\DF{\V{\A compile-print\A}}\\
  55       \kwd{:external-format} \VAR{
  56         file-format}\DF{\kwd{:default}}}{\}})}
  57   {
  58     Write compiled contents of \VAR{file} to \VAR{out-path}.  Return
  59     \retval{true output path} or \retval{\NIL}, \retvalii{\T} in case
  60     of \kwd{warning}s or \kwd{error}s, \retvaliii{\T} in case of
  61     \kwd{warning}s or \kwd{error}s excluding \kwd{style-warning}s.
  62   }
  63
  64   \IT{(\FU*{COMPILE-FILE-PATHNAME} \VAR{file} \Op{\kwd{:output-file}
  65       \VAR{path}} \Op{\VAR{other-keyargs}})}
  66   {
  67     \retval{Pathname} \FU{COMPILE-FILE} writes to if invoked with the
  68     same arguments.
  69   }
  70
  71   \IT{(\FU*{LOAD} \VAR{path}
  72     \orGOO{\kwd{:verbose} \VAR{ bool}\DF{\V{\A load-verbose\A}}\\
  73       \kwd{:print} \VAR{ bool}\DF{\V{\A load-print\A}}\\
  74       \kwd{:if-does-not-exist} \VAR{ bool}\DF{\T}\\
  75       \kwd{:external-format} \VAR{
  76         file-format}\DF{\kwd{:default}}}{\}})}
  77   {
  78     Load source file or compiled file into Lisp environment. Return
  79     \retval{\T} if successful.
  80   }
  81
  82   \IT{\arrGOO{\V{\A compile-file}\\
  83       \V{\A load}}{\}}\kwd{-}%
  84     \xorGOO{\kwd{pathname\A}\DF{\NIL}\\
  85       \kwd{truename\A}\DF{\NIL}}{.}}
  86   {\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}
  87     Input file used by \FU{compile-file}/by \FU{load}.
  88   }
  89
  90   \IT{\arrGOO{\V{\A compile}\\
  91       \V{\A load}}{\}}\kwd{-}%
  92     \xorGOO{\kwd{print\A}\\
  93       \kwd{verbose\A}}{.}}
  94   {\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}
  95     Defaults used by \FU{compile-file}/by \FU{load}.
  96   }
  97
  98   \IT{(\SO*{EVAL-WHEN} (%
  99     \orGOO{\Goo{\kwd{:compile-toplevel}\XOR\kwd{compile}}\\
 100       \Goo{\kwd{:load-toplevel}\XOR\kwd{load}}\\
 101       \Goo{\kwd{:execute}\XOR\kwd{eval}}}{\}}) \PROGN{\VAR{form}})}
 102   {
 103     Return \retval{values of \VAR{form}s} if
 104     \SO{EVAL-WHEN} is in the top-level of a file being compiled, in the
 105     top-level of a compiled file being loaded, or anywhere,
 106     respectively. Return \retval{\NIL} if \VAR{form}s are not
 107     evaluated. (\kwd{compile}, \kwd{load} and \kwd{eval} deprecated.)
 108   }
 109
 110   \IT{(\SO*{LOCALLY} \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
 111     \PROGN{\VAR{form}})}
 112   {
 113     Evaluate \VAR{form}s in a lexical environment with declarations
 114     \VAR{decl} in effect. Return \retval{values of \VAR{form}s}.
 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{\NEV{\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} \NEV{\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}\DF{all local 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}\text{ }
 158       \xorGOO{\VAR{name}\\
 159         (\kwd{setf } \VAR{name})}{\}}\text{ }
 160       \Op{\VAR{environment}})}{.}}
 161   {
 162     Return specified \retval{macro function}, or \retval{compiler mac\-ro
 163       func\-tion}, respectively, if any. Return \retval{\NIL}
 164     otherwise. \kwd{setf}able.
 165   }
 166
 167   \IT{(\FU*{EVAL} \VAR{arg})}
 168   {
 169     Return \retval{values of value of \VAR{arg}} evaluated in global environment.
 170   }
 171
 172 \end{LIST}
 173
 174
 175 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 176 \subsection{REPL and Debugging}
 177 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 178
 179 \begin{LIST}{1cm}
 180
 181   \IT{\arrGOO{\V*{+}\XOR\V*{++}\XOR\V*{+++}\\[1pt]
 182       \V{\A}\text{ }\XOR\text{ }\V{\A\A}\text{ }\XOR\text{ }\V{\A\A\A}\\[1pt]
 183       \V*{/}\text{ }\XOR\text{ }\V*{//}\text{ }\XOR\text{ }\V*{///}}{.}}
 184   {\index{*@\A}\index{**@\A\A}\index{***@\A\A\A}
 185     Last, penultimate, or antepenultimate \retval{form} evaluated in the REPL, or
 186     their respective \retval{primary value}, or a \retval{list} of their respective
 187     values.
 188   }
 189
 190   \IT{\V*{--}}
 191   {
 192     \retval{Form} currently being evaluated by the REPL.
 193   }
 194
 195   \IT{(\FU*{APROPOS} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
 196   {
 197     Print interned symbols containing \VAR{string}.
 198   }
 199
 200   \IT{(\FU*{APROPOS-LIST} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
 201   {
 202     \retval{List of interned symbols} containing \VAR{string}.
 203   }
 204
 205   \IT{(\FU*{DRIBBLE} \Op{\VAR{path}})}
 206   {
 207     Save a record of interactive session to file at \VAR{path}. Without
 208     \VAR{path}, close that file.
 209   }
 210
 211   \IT{(\FU*{ED} \Op{\VAR{file-or-function}\DF{\NIL}})}
 212   {
 213     Invoke editor if possible.
 214   }
 215
 216   \IT{(\xorGOO{\FU*{MACROEXPAND-1}\\
 217       \FU*{MACROEXPAND}}{\}} \VAR{form} \Op{\VAR{environment}\DF{\NIL}})}
 218   {
 219     Return \retval{macro expansion}, once or entirely, respectively, of
 220     \VAR{form} and \retvalii{\T} if \VAR{form} was a macro form.
 221     Return \retval{\VAR{form}} and \retvalii{\NIL} otherwise.
 222   }
 223
 224   \IT{\V{\A macroexpand-hook\A}}
 225   {\index{*MACROEXPAND-HOOK*@\A MACROEXPAND-HOOK\A}
 226     Function of arguments expansion function, macro form, and
 227     environment called by \FU{macroexpand-1} to generate macro
 228     expansions.
 229   }
 230
 231   \IT{(\MC*{TRACE} \xorGOO{\VAR{function}\\
 232       (\kwd{setf } \VAR{function})}{\}^{\!\!*}})}
 233   {
 234     Cause \VAR{function}s to be traced. With no arguments,
 235     return \retval{list of traced functions}.
 236   }
 237
 238   \IT{(\MC*{UNTRACE} \xorGOO{\VAR{function}\\
 239       (\kwd{setf } \VAR{function})}{\}^{\!\!*}})}
 240   {
 241     Stop \VAR{function}s, or each currently traced function, from being
 242     traced.
 243   }
 244
 245   \IT{\V{\A trace-output\A}}
 246   {\index{*TRACE-OUTPUT*@\A TRACE-OUTPUT\A}
 247     Output stream \MC{trace} and \MC{time} send their output to.
 248   }
 249
 250   \IT{(\MC*{STEP} \VAR{form})}
 251   {
 252     Step through evaluation of \VAR{form}. Return \retval{values of
 253       \VAR{form}}.
 254   }
 255
 256   \IT{(\FU*{BREAK} \Op{\VAR{control} \OPn{\VAR{arg}}})}
 257   {
 258     Jump directly into debugger; return \retval{\NIL}.
 259     See page \pageref{section:Format}, \FU{format}, for \VAR{control}
 260     and \VAR{arg}s.
 261   }
 262
 263   \IT{(\MC*{TIME} \VAR{form})}
 264   {
 265     Evaluate \VAR{form}s and print timing information to
 266     \V{\A trace-output\A}. Return \retval{values of \VAR{form}}.
 267   }
 268   \IT{(\FU*{INSPECT} \VAR{foo})}
 269   {
 270     Interactively give information about \VAR{foo}.
 271   }
 272
 273   \IT{(\FU*{DESCRIBE} \VAR{foo}
 274     \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
 275   {
 276     Send information about \VAR{foo} to \VAR{stream}.
 277   }
 278
 279   \IT{(\GFU*{DESCRIBE-OBJECT} \VAR{foo} \Op{\DES{\VAR{stream}}})}
 280   {
 281     Send information about \VAR{foo} to \VAR{stream}.  Called by
 282     \FU{describe}.
 283   }
 284
 285   \IT{(\FU*{DISASSEMBLE} \VAR{function})}
 286   {
 287     Send disassembled representation of \VAR{function} to
 288     \V{\A standard-output\A}. Return \retval{\NIL}.
 289   }
 290
 291   \IT{(\FU*{ROOM} \Op{\Goo{\NIL\XOR\kwd{:default}\XOR\T}\DF{\kwd{:default}}})}
 292   {
 293     Print information about internal storage management to \kwd{\A
 294       standard-output\A}.
 295   }
 296
 297
 298
 299 \end{LIST}
 300
 301
 302 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 303 \subsection{Declarations}
 304 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 305 \begin{LIST}{1cm}
 306
 307   \IT{\arrGOO{(\FU*{PROCLAIM} \VAR{ decl})\\
 308       (\MC*{DECLAIM } \OPn{\NEV{\VAR{decl}}})}{.}}
 309   {
 310     Globally make declaration(s) \VAR{decl}. \VAR{decl} can be:
 311     \kwd{declaration},
 312     \kwd{type},
 313     \kwd{ftype},
 314     \kwd{inline},
 315     \kwd{notinline},
 316     \kwd{optimize}, or
 317     \kwd{special}.
 318     See below.
 319   }
 320
 321   \IT{(\kwd*{DECLARE} \OPn{\NEV{\VAR{decl}}})}
 322   {
 323     Inside certain forms, locally make declarations
 324     \OPn{\VAR{decl}}. \VAR{decl} can be:
 325     \kwd{dynamic-extent},
 326     \kwd{type},
 327     \kwd{ftype},
 328     \kwd{ignorable},
 329     \kwd{ignore},
 330     \kwd{inline},
 331     \kwd{notinline},
 332     \kwd{optimize}, or
 333     \kwd{special}.
 334     See below.
 335   }
 336
 337   \begin{LIST}{.5cm}
 338
 339     \IT{(\kwd*{DECLARATION} \OPn{foo})}
 340     {
 341       Make \VAR{foo}s names of declarations.
 342     }
 343
 344     \IT{(\kwd*{DYNAMIC-EXTENT} \OPn{\VAR{variable}} \OPn{(\kwd{function}
 345         \VAR{function})})}
 346     {
 347       Declare lifetime of \VAR{variable}s and/or \VAR{function}s to end
 348       when control leaves enclosing block.
 349     }
 350
 351
 352     \IT{\arrGOO{(\Op{\kwd*{TYPE}} \VAR{ type} \OPn{\VAR{ variable}})\\
 353         (\kwd*{FTYPE} \VAR{ type} \OPn{\VAR{ function}})}{.}}
 354     {
 355       Declare \VAR{variable}s or \VAR{function}s to be of \VAR{type}.
 356     }
 357
 358     \IT{(\xorGOO{\kwd*{IGNORABLE}\\
 359         \kwd*{IGNORE}}{\}}
 360       \xorGOO{%
 361         \VAR{var}\\
 362         (\kwd{function} \VAR{ function})}{\}^{\!\!*}})}
 363     {
 364       Suppress warnings about used/unused bindings.
 365     }
 366
 367     \IT{\arrGOO{(\kwd*{INLINE} \OPn{\VAR{ function}})\\
 368         (\kwd*{NOTINLINE} \OPn{\VAR{ function}})}{.}}
 369     {
 370       Tell compiler to integrate/not to integrate, respectively, called
 371       \VAR{function}s into the calling routine.
 372     }
 373
 374     \IT{(\kwd*{OPTIMIZE} \orGOO{%
 375         \kwd*{COMPILATION-SPEED}\XOR(\kwd*{COMPILATION-SPEED}\VAR{ n}\DF{\LIT{3}})\\
 376         \kwd*{DEBUG}\XOR(\kwd*{DEBUG}\VAR{ n}\DF{\LIT{3}})\\
 377         \kwd*{SAFETY}\XOR(\kwd*{SAFETY}\VAR{ n}\DF{\LIT{3}})\\
 378         \kwd*{SPACE}\XOR(\kwd*{SPACE}\VAR{ n}\DF{\LIT{3}})\\
 379         \kwd*{SPEED}\XOR(\kwd*{SPEED}\VAR{ n}\DF{\LIT{3}})}{\}})}
 380     {
 381       Tell compiler how to optimize. $n=0$ means unimportant, $n=1$ is
 382       neutral, $n=3$ means important.
 383     }
 384
 385     \IT{(\kwd*{SPECIAL} \OPn{\VAR{var}})}
 386     {
 387       Declare \VAR{var}s to be dynamic.
 388     }
 389
 390   \end{LIST}
 391 \end{LIST}
 392
 393
 394
 395
 396 % LocalWords:  mac ro func tion
 397
 398 %%% Local Variables:
 399 %%% mode: latex
 400 %%% TeX-master: "clqr"
 401 %%% End: