Fix bugs reported by Fengjing Xiao
[clqr.git] / clqr-compiler.tex
blob3b7792679c50848eabdd4eee669ed0735d576c2f
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 %
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 \section{Compiler}
12 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 \subsection{Predicates}
16 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18 \begin{LIST}{1cm}
20 \IT{(\FU*{SPECIAL-OPERATOR-P} \VAR{foo})}
22 \retval{\T} if \VAR{foo} is a special operator.
25 \IT{(\FU*{COMPILED-FUNCTION-P} \VAR{foo})}
27 \retval{\T} if \VAR{foo} is of type \kwd{compiled-function}.
30 \end{LIST}
33 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34 \subsection{Compilation}
35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
37 \begin{LIST}{1cm}
39 \IT{(\FU*{COMPILE}
40 \xorGOO{\NIL\VAR{ definition}\\
41 \xorGOO{\VAR{name}\\
42 (\kwd{setf } \VAR{name})}{\}}\text{ }\Op{\VAR{definition}}}{\}})}
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.
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}}}{\}})}
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.
64 \IT{(\FU*{COMPILE-FILE-PATHNAME} \VAR{file} \Op{\kwd{:output-file}
65 \VAR{path}} \Op{\VAR{other-keyargs}})}
67 \retval{Pathname} \FU{COMPILE-FILE} writes to if invoked with the
68 same arguments.
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}}}{\}})}
78 Load source file or compiled file into Lisp environment. Return
79 \retval{\T} if successful.
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}.
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}.
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}})}
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.)
110 \IT{(\SO*{LOCALLY} \OPn{(\kwd{declare} \OPn{\NEV{\VAR{decl}}})}
111 \PROGN{\VAR{form}})}
113 Evaluate \VAR{form}s in a lexical environment with declarations
114 \VAR{decl} in effect. Return \retval{values of \VAR{form}s}.
117 \IT{(\MC*{WITH-COMPILATION-UNIT} (\Op{\kwd{:override}
118 \VAR{bool}\DF{\NIL}}) \PROGN{\VAR{form}})}
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.
125 \IT{(\SO*{LOAD-TIME-VALUE} \VAR{form}
126 \Op{\NEV{\VAR{read-only}}\DF{\NIL}})}
128 Evaluate \VAR{form} at compile time and treat \retval{its value} as
129 literal at run time.
132 \IT{(\SO*{QUOTE} \NEV{\VAR{foo}})}
134 Return \retval{unevaluated \VAR{foo}}.
137 \IT{(\GFU*{MAKE-LOAD-FORM} \VAR{foo} \Op{\VAR{environment}})}
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.
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}}{\}})}
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}.
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}})}{.}}
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.
167 \IT{(\FU*{EVAL} \VAR{arg})}
169 Return \retval{values of value of \VAR{arg}} evaluated in global environment.
172 \end{LIST}
175 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
176 \subsection{REPL and Debugging}
177 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
179 \begin{LIST}{1cm}
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.
190 \IT{\V*{--}}
192 \retval{Form} currently being evaluated by the REPL.
195 \IT{(\FU*{APROPOS} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
197 Print interned symbols containing \VAR{string}.
200 \IT{(\FU*{APROPOS-LIST} \VAR{string} \Op{\VAR{package}\DF{\NIL}})}
202 \retval{List of interned symbols} containing \VAR{string}.
205 \IT{(\FU*{DRIBBLE} \Op{\VAR{path}})}
207 Save a record of interactive session to file at \VAR{path}. Without
208 \VAR{path}, close that file.
211 \IT{(\FU*{ED} \Op{\VAR{file-or-function}\DF{\NIL}})}
213 Invoke editor if possible.
216 \IT{(\xorGOO{\FU*{MACROEXPAND-1}\\
217 \FU*{MACROEXPAND}}{\}} \VAR{form} \Op{\VAR{environment}\DF{\NIL}})}
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.
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.
231 \IT{(\MC*{TRACE} \xorGOO{\VAR{function}\\
232 (\kwd{setf } \VAR{function})}{\}^{\!\!*}})}
234 Cause \VAR{function}s to be traced. With no arguments,
235 return \retval{list of traced functions}.
238 \IT{(\MC*{UNTRACE} \xorGOO{\VAR{function}\\
239 (\kwd{setf } \VAR{function})}{\}^{\!\!*}})}
241 Stop \VAR{function}s, or each currently traced function, from being
242 traced.
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.
250 \IT{(\MC*{STEP} \VAR{form})}
252 Step through evaluation of \VAR{form}. Return \retval{values of
253 \VAR{form}}.
256 \IT{(\FU*{BREAK} \Op{\VAR{control} \OPn{\VAR{arg}}})}
258 Jump directly into debugger; return \retval{\NIL}.
259 See page \pageref{section:Format}, \FU{format}, for \VAR{control}
260 and \VAR{arg}s.
263 \IT{(\MC*{TIME} \VAR{form})}
265 Evaluate \VAR{form}s and print timing information to
266 \V{\A trace-output\A}. Return \retval{values of \VAR{form}}.
268 \IT{(\FU*{INSPECT} \VAR{foo})}
270 Interactively give information about \VAR{foo}.
273 \IT{(\FU*{DESCRIBE} \VAR{foo}
274 \Op{\DES{\VAR{stream}}\DF{\V{\A standard-output\A}}})}
276 Send information about \VAR{foo} to \VAR{stream}.
279 \IT{(\GFU*{DESCRIBE-OBJECT} \VAR{foo} \Op{\DES{\VAR{stream}}})}
281 Send information about \VAR{foo} to \VAR{stream}. Called by
282 \FU{describe}.
285 \IT{(\FU*{DISASSEMBLE} \VAR{function})}
287 Send disassembled representation of \VAR{function} to
288 \V{\A standard-output\A}. Return \retval{\NIL}.
291 \IT{(\FU*{ROOM} \Op{\Goo{\NIL\XOR\kwd{:default}\XOR\T}\DF{\kwd{:default}}})}
293 Print information about internal storage management to \kwd{\A
294 standard-output\A}.
299 \end{LIST}
302 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
303 \subsection{Declarations}
304 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
305 \begin{LIST}{1cm}
307 \IT{\arrGOO{(\FU*{PROCLAIM} \VAR{ decl})\\
308 (\MC*{DECLAIM } \OPn{\NEV{\VAR{decl}}})}{.}}
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.
321 \IT{(\kwd*{DECLARE} \OPn{\NEV{\VAR{decl}}})}
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.
337 \begin{LIST}{.5cm}
339 \IT{(\kwd*{DECLARATION} \OPn{foo})}
341 Make \VAR{foo}s names of declarations.
344 \IT{(\kwd*{DYNAMIC-EXTENT} \OPn{\VAR{variable}} \OPn{(\kwd{function}
345 \VAR{function})})}
347 Declare lifetime of \VAR{variable}s and/or \VAR{function}s to end
348 when control leaves enclosing block.
352 \IT{\arrGOO{(\Op{\kwd*{TYPE}} \VAR{ type} \OPn{\VAR{ variable}})\\
353 (\kwd*{FTYPE} \VAR{ type} \OPn{\VAR{ function}})}{.}}
355 Declare \VAR{variable}s or \VAR{function}s to be of \VAR{type}.
358 \IT{(\xorGOO{\kwd*{IGNORABLE}\\
359 \kwd*{IGNORE}}{\}}
360 \xorGOO{%
361 \VAR{var}\\
362 (\kwd{function} \VAR{ function})}{\}^{\!\!*}})}
364 Suppress warnings about used/unused bindings.
367 \IT{\arrGOO{(\kwd*{INLINE} \OPn{\VAR{ function}})\\
368 (\kwd*{NOTINLINE} \OPn{\VAR{ function}})}{.}}
370 Tell compiler to integrate/not to integrate, respectively, called
371 \VAR{function}s into the calling routine.
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}})}{\}})}
381 Tell compiler how to optimize. $n=0$ means unimportant, $n=1$ is
382 neutral, $n=3$ means important.
385 \IT{(\kwd*{SPECIAL} \OPn{\VAR{var}})}
387 Declare \VAR{var}s to be dynamic.
390 \end{LIST}
391 \end{LIST}
396 % LocalWords: mac ro func tion
398 %%% Local Variables:
399 %%% mode: latex
400 %%% TeX-master: "clqr"
401 %%% End: