continued work

[clqr.git] / clqr-compiler.tex

% Copyright (C) 2008 Bert Burgemeister
%
% Permission is granted to copy, distribute and/or modify this
% document under the terms of the GNU Free Documentation License,
% Version 1.2 or any later version published by the Free Software
% Foundation; with no Invariant Sections, no Front-Cover Texts and
% no Back-Cover Texts. For details see file COPYING.
%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Compiler} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Predicates} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\FU*{SPECIAL-OPERATOR-P} \VAR{foo})}
  {
  \retval{\T} if \VAR{foo} is a special operator.
  }

  \IT{(\FU*{COMPILED-FUNCTION-P} \VAR{foo})}
  {
  \retval{\T} if \VAR{foo} is of type \kwd{compiled-function}.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Compilation} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}

  \IT{(\FU*{COMPILE} 
    \xorGOO{\NIL\\
      \VAR{name}}{\}}
    \Op{\VAR{definition}})}
  {
  Return \retval{compiled function} or its \VAR{name}, \retvalii{\T} in case
  of warnings, and \retvaliii{\T} in case of failure.
  }

  \IT{(\FU*{COMPILE-FILE} \VAR{file} 
    \orGOO{\kwd{:output-file}\VAR{ out-path}\\
      \kwd{:verbose} \VAR{ bool}\DF{\kwd{*compile-verbose*}}\\
      \kwd{:print}\VAR{ bool}\DF{\kwd{*compile-print*}}\\
      \kwd{:external-format} \VAR{
        file-format}\DF{\kwd{:default}}}{\}})}
  {
  Write compiled contents of \VAR{path} to \VAR{out-path}.
  Return \retval{true output path} or \retval{\NIL}, \retvalii{\T}
  in case of warnings or errors, \retvaliii{\T} in case of warnings
  or errors excluding style warnings.
  }

  \IT{\arrGOO{\V*{*compile-file-pathname*}\DF{\NIL}\\
      \V*{*compile-file-truename*}\DF{\NIL}}{.}}
  {
  Input file used by \FU{compile-file}.
  }

  \IT{\arrGOO{\V*{*compile-print*}\\
      \V*{*compile-verbose*}}{.}}
  {
  Defaults used in \FU{compile-file}.
  }

  \IT{(\FU*{COMPILE-FILE-PATHNAME} \Op{\kwd{:pathname} \VAR{path}})}
  {
  \retval{Pathname} \FU{COMPILE-FILE} writes to.
  }

  \IT{(\FU*{LOAD} \VAR{path} 
    \orGOO{\kwd{:verbose} \VAR{ bool}\DF{\kwd{*load-verbose*}}\\
      \kwd{:print} \VAR{ bool}\DF{\kwd{*load-print*}}\\
      \kwd{:if-does-not-exist} \VAR{ bool}\DF{\T}\\
      \kwd{:external-format} \VAR{
        file-format}\DF{\kwd{:default}}}{\}})}
  {
  Load source or compiled file. Return \retval{\T} if successful.
  }

  \IT{\arrGOO{\V*{*load-pathname*}\DF{\NIL}\\
      \V*{*load-truename*}\DF{\NIL}}{.}}
  {
  Input file used by \FU{load}.
  }

  \IT{\arrGOO{\V*{*load-print*}\\
      \V*{*load-verbose*}}{.}}
  {
  Defaults used in \FU{load}.
  }

  \IT{(\SF*{EVAL-WHEN} (%
    \orGOO{\kwd{:compile-toplevel}\\
      \kwd{:load-toplevel}\\
      \kwd{:execute}}{\}}) \OPn{\VAR{form}})} 
  {
  Evaluate \VAR{form}s returning \retval{values of last \VAR{form}} if
  \SF{EVAL-WHEN} is in the top-level of a file being compiled, in the
  top-level of a compiled file being loaded, or anywhere, respectively 
  }

  \IT{(\kwd*{WITH-COMPILATION-UNIT} (\Op{\kwd{:override}
      \VAR{bool}\DF{\NIL}}) \OPn{\VAR{form}})}
  {
  Return \retval{values of \VAR{form}s}. Warnings deferred by the
  compiler until end of compilation are deferred until the end of
  evaluation of \VAR{form}s. 
  }

  \IT{(\SF*{LOAD-TIME-VALUE} \VAR{form}
    \Op{\VAR{read-only}\DF{\NIL}})}
  {
  Evaluate \VAR{form} at compile time and treat \retval{its value} as
  literal at run time. 
  }

  \IT{(\SF*{QUOTE} \VAR{foo})}
  {
  Return \retval{unevaluated \VAR{foo}}.
  }

  \IT{(\GFU*{MAKE-LOAD-FORM} \VAR{foo} \Op{\VAR{environment}})}
  {
  Make \retval{one or two forms} enabling \kwd{load} to construct
  something equvalent to \VAR{foo}.
  }

  \IT{(\FU*{MAKE-LOAD-FORM-SAVING-SLOTS} \VAR{foo}
    \orGOO{\kwd{:slot-names} \VAR{ slots}\\
      \kwd{:environment}  \VAR{ environment}}{\}})}
  {
  Make \retval{two forms} yielding something equvalent to \VAR{foo}
  but preserving only \VAR{slots}.
  }

  \IT{\arrGOO{(\FU*{MACRO-FUNCTION} \VAR{ symbol }
      \Op{\VAR{environment}})\\
      (\kwd*{COMPILER-MACRO-FUNCTION} \VAR{ name }
      \Op{\VAR{environment}})}{.}}
  {
  Return specified \retval{macro function}, or \retval{compiler macro
    function}, respectively, if any. Return \retval{\NIL}
  otherwise. \kwd{setf}able. 
  }
  
  \IT{(\FU*{EVAL} \VAR{form})}
  {
  Return \retval{values of \VAR{form}}.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{REPL and Debugging} 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{LIST}{1cm}
  
  \IT{\arrGOO{\kwd*{+}\XOR\kwd*{++}\XOR\V*{+++}\\[1pt]
      \kwd*{*}\XOR\kwd*{**}\XOR\V*{***}\\[1pt]
      \kwd*{/}\XOR\kwd*{//}\XOR\V*{///}}{.}}
  {
  Last, penultimate, or antepenultimate form evaluated in the REPL, or
  their respective primary values, or lists of their respective
  values. 
  }

  \IT{\kwd*{--}}
  {
  Form currently being evaluated by the REPL.
  }

  \IT{(\FU*{APROPOS} \VAR{string} \OPn{\VAR{package}})}
  {
  Print interned symbols containig \VAR{string}.
  }

  \IT{(\FU*{APROPOS-LIST} \VAR{string} \OPn{\VAR{package}})}
  {
  \retval{List of interned symbols} containig \VAR{string}.
  }

  \IT{(\FU*{DRIBBLE} \Op{\VAR{path}})}
  {
  Save a record of interactive session to file at \VAR{path}.
  }

  \IT{(\FU*{ED} \Op{\VAR{file-or-function}\DF{\NIL}})}
  {
  Invoke editor if possible.
  }

  \IT{(\xorGOO{\SF*{MACROEXPAND-1}\\
      \SF*{MACROEXPAND}}{\}}\VAR{form} \Op{\VAR{environment}})}
  {
  Return \retval{macro expansion}, once or entirely, respectively, of
  \VAR{form} and \retvalii{\T} if \VAR{form} is a macro form. 
  Return \retval{\VAR{form}} and \retvalii{\NIL} otherwise.
  }

  \IT{\V*{*macroexpand-hook*}}
  {
  Function called by \kwd{macroexpand-1} to generate macro expansions.
  }

  \IT{(\SF*{TRACE} \OPn{\VAR{function}})}
  {
  Cause \VAR{function}s to be traced. With no arguments,
  return \retval{list of traced functions}.
  }

  \IT{(\SF*{UNTRACE} \OPn{\VAR{function}})}
  {
  Stop \VAR{function}s, or each currently traced function from being
  traced. 
  }

  \IT{\V*{*trace-output*}}
  {
  Stream \kwd{trace} and \kwd{time} print their output on.
  }

  \IT{(\SF*{STEP} \VAR{form})}
  {
  Step through evaluation of \VAR{form}. Return \retval{values of
    \VAR{form}}. 
  }

  \IT{(\SF*{TIME} \OPn{\VAR{form}})}
  {
  Evaluate \VAR{form}s and print timing information to
  \V{*trace-output*}. Return \retval{values of \VAR{form}s}. 
  }
  \IT{(\FU*{INSPECT} \VAR{foo})}
  {
    Interactively give information about \VAR{foo}.
  }

  \IT{(\FU*{DESCRIBE} \VAR{foo}
    \Op{\VAR{stream}\DF{\kwd{*standard-output*}}})}
  {
  Send information about \VAR{foo} to \VAR{stream}.
  }

  \IT{(\GFU*{DESCRIBE-OBJECT} \VAR{foo} \Op{\VAR{stream}})}
  {
  Send information about \VAR{foo} to \VAR{stream}. Not to be
  called by user.
  }

  \IT{(\FU*{DISASSEMBLE} \VAR{function})}
  {
  Send disassembled representation of \VAR{function} to
  \kwd{*standard-output*}. Return \retval{\NIL}.
  }

\end{LIST}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Declarations}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{LIST}{1cm}

  \IT{\arrGOO{(\FU*{PROCLAIM} \VAR{ decl})\\
      (\SF*{DECLAIM} \OPn{\VAR{ decl}})}{.}}
  {
  Globally make declaration(s) \VAR{decl}. \VAR{decl} can be:
  \kwd{declaration},      
  \kwd{type},
  \kwd{ftype},           
  \kwd{inline},   
  \kwd{notinline},
  \kwd{optimize}, or
  \kwd{special}.
  See below.
  }

  \IT{(\SF*{DECLARE} \OPn{\VAR{decl}})}
  {
  Inside certain forms, locally make declarations \VAR{decl}. \VAR{decl} can be:
  \kwd{dynamic-extent},
  \kwd{type},
  \kwd{ftype},           
  \kwd{ignorable},       
  \kwd{ignore},     
  \kwd{inline},     
  \kwd{notinline},  
  \kwd{optimize}, or
  \kwd{special}.
  See below.      
  }

  \begin{LIST}{.5cm}
    
    \IT{(\kwd*{DECLARATION} \OPn{foo})}
    {
    Make \VAR{foo}s names of declarations.
   }
 
    \IT{(\kwd*{DYNAMIC-EXTENT} \OPn{\VAR{var}} \OPn{(\kwd{function}
        \VAR{fu})})}
    {
    Declare objects referred to by \VAR{var} or \VAR{fu} to have
    dynamic extent. 
  }


    \IT{\arrGOO{(\kwd*{TYPE} \VAR{ type} \OPn{\VAR{ variable}})\\
        (\kwd*{FTYPE} \VAR{ type} \OPn{\VAR{ function}})}{.}}
    {
    Declare \VAR{variable} or \VAR{function} to be of \VAR{type}.
  }

    \IT{(\xorGOO{\kwd*{IGNORE}\\
        \kwd*{IGNORABLE}}{\}}\xorGOO{%
        \VAR{var}\\
        (\kwd{function} \VAR{ function})}{\}^{\!\!*}})}
    {
    Suppress warnings about used/unused bindings.
  }

    \IT{\arrGOO{(\kwd*{INLINE} \OPn{\VAR{ function}})\\
        (\kwd*{NOTINLINE} \OPn{\VAR{ function}})}{.}}
    {
    Tell compiler to integrate/not to integrate, respectively, called
    \VAR{function}s into the calling routine.
  }

    \IT{(\kwd*{OPTIMIZE}\orGOO{%
        \kwd*{COMPILATION-SPEED}\XOR(\kwd*{COMPILATION-SPEED}\VAR{ n})\\
        \kwd*{DEBUG}\XOR(\kwd*{DEBUG}\VAR{ n})\\
        \kwd*{SAFETY}\XOR(\kwd*{SAFETY}\VAR{ n})\\
        \kwd*{SPACE}\XOR(\kwd*{SPACE}\VAR{ n})\\
        \kwd*{SPEED}\XOR(\kwd*{SPEED}\VAR{ n})}{\}})}
    {
    Tell compiler how to optimize. $n=0$ means unimportant, $n=1$ is
    neutral, $n=3$ means important.
  }

    \IT{(\kwd*{SPECIAL} \OPn{\VAR{var}})}
    {
    Declare \VAR{var}s being dynamic.
  }

  \end{LIST}
\end{LIST}