reduce-historical/r38/lisp/csl/r38.doc/util.tex

\chapter{{\REDUCE} and Rlisp Utilities}

{\REDUCE} and its associated support language system Rlisp\index{Rlisp}
include a number of utilities which have proved useful for program
development over the years.  The following are supported in most of the
implementations of {\REDUCE} currently available.

\section{The Standard Lisp Compiler}\index{Compiler}

Many versions of {\REDUCE} include a Standard Lisp compiler that is
automatically loaded on demand.  You should check your system specific
user guide to make sure you have such a compiler.  To make the compiler
active, the switch {\tt COMP}\ttindex{COMP} should be turned on.  Any
further definitions input after this will be compiled automatically.  If
the compiler used is a derivative version of the original Griss-Hearn
compiler,
(M. L. Griss and A.
C. Hearn, ``A Portable LISP Compiler", SOFTWARE --- Practice and Experience
11 (1981) 541-605),
there are other switches that might also be
used in this regard.  However, these additional switches are not supported
in all compilers.  They are as follows:
%\ttindex{PLAP}\ttindex{PGWD}\ttindex{PWRDS}

{\renewcommand{\arraystretch}{2}
\begin{tabular}{lp{\reduceboxwidth}}
{\tt PLAP} & If ON, causes the printing of the
portable macros produced by the compiler; \\
%
{\tt PGWD} & If ON, causes the printing of the
actual assembly language instructions generated from the macros; \\
%
{\tt PWRDS} & If ON, causes a statistic
message of the form \newline
{\tt    <function> COMPILED, <words> WORDS, <words> LEFT} \newline
to be printed.  The first number is the number of words of binary
program space the compiled function took, and the second number
the number of words left unused in binary program space. \\
\end{tabular}}

\section{Fast Loading Code Generation Program}\index{Fast loading of code}
\label{sec-load}
In most versions of {\REDUCE}, it is possible to take any set of Lisp, Rlisp
or {\REDUCE} commands and build a fast loading version of them. In Rlisp or
{\REDUCE}, one does the following:
\begin{verbatim}
         faslout <filename>;
         <commands or IN statements>
         faslend;
\end{verbatim}
To load such a file, one uses the command {\tt LOAD},\ttindex{LOAD}
e.g. {\tt load foo;}
or {\tt load foo,bah;}

This process produces a fast-loading version of the original file.  In some
implementations, this means another file is created with the same name but
a different extension. For example, in PSL-based systems, the extension is
{\tt b} (for binary). In CSL-based systems, however, this process adds the
fast-loading code to a single file in which all such code is stored. 
Particular functions are provided by CSL for managing this file, and 
described in the CSL user documentation.

In doing this build, as with the production of a Standard Lisp form of
such statements, it is important to remember that some of the commands
must be instantiated during the building process.  For example, macros
must be expanded, and some property list operations must happen.
The {\REDUCE} sources should be consulted for further details on this.
% To facilitate this, the {\tt EVAL} and {\tt IGNORE} flags may be
% used.  Note also that there can be no {\tt LOAD} command within the input
% statements.

To avoid excessive printout, input statements should be followed by a \$
instead of the semicolon.  With {\tt LOAD} however, the input doesn't
print out regardless of which terminator is used with the command.

If you subsequently change the source files used in producing a fast
loading file, don't forget to repeat the above process in order to update
the fast loading file correspondingly.  Remember also that the text which
is read in during the creation of the fast load file, in the compiling
process described above, is {\em not\/} stored in your {\REDUCE}
environment, but only translated and output.  If you want to use the file
just created, you must then use {\tt LOAD} to load the output of the
fast-loading file generation program.

When the file to be loaded contains a complete package for a given
application, {\tt LOAD\_PACKAGE}\ttindex{LOAD\_PACKAGE} rather than
{\tt LOAD} should be used.  The syntax is the same.  However,
{\tt LOAD\_PACKAGE} does some additional bookkeeping such as recording that
this package has now been loaded, that is required for the correct
operation of the system.

\section{The Standard Lisp Cross Reference Program}\index{Cross reference}

{\tt CREF}\ttindex{CREF} is a Standard Lisp program for processing a
set of Standard LISP function definitions to produce:
\begin{enumerate}
\item A ``summary'' showing:
\begin{enumerate}
\item A list of files processed;
\item A list of ``entry points'' (functions which are not called or
are only called by themselves);
\item A list of undefined functions (functions called but not
defined in this set of functions);
\item A list of variables that were used non-locally but not
declared {\tt GLOBAL} or {\tt FLUID} before their use;
\item A list of variables that were declared {\tt GLOBAL} but not used
as {\tt FLUID}s, i.e., bound in a function;
\item A list of {\tt FLUID} variables that were not bound in a function
so that one might consider declaring them {\tt GLOBAL}s;
\item A list of all {\tt GLOBAL} variables present;
\item A list of all {\tt FLUID} variables present;
\item A list of all functions present.
\end{enumerate}
\item A ``global variable usage'' table, showing for each non-local
   variable:
\begin{enumerate}
\item Functions in which it is used as a declared {\tt FLUID} or {\tt GLOBAL};
\item Functions in which it is used but not declared;
\item Functions in which it is bound;
\item Functions in which it is changed by {\tt SETQ}.
\end{enumerate}
\item A ``function usage'' table showing for each function:
\begin{enumerate}
\item Where it is defined;
\item Functions which call this function;
\item Functions called by it;
\item Non-local variables used.
\end{enumerate}
\end{enumerate}

The program will also check that functions are called with the correct
number of arguments, and print a diagnostic message otherwise.

The output is alphabetized on the first seven characters of each function
name.

\subsection{Restrictions}

Algebraic procedures in {\REDUCE} are treated as if they were symbolic, so
that algebraic constructs will actually appear as calls to symbolic
functions, such as {\tt AEVAL}.

\subsection{Usage}

To invoke the cross reference program, the switch {\tt CREF}
\ttindex{CREF} is used. {\tt on cref} causes the cref program to load
and the cross-referencing process to begin.  After all the required
definitions are loaded, {\tt off cref} will cause the cross-reference
listing to be produced.  For example, if you wish to cross-reference all
functions in the file {\tt tst.red}, and produce the cross-reference
listing in the file {\tt tst.crf}, the following sequence can be used:
\begin{verbatim}
        out "tst.crf";
        on cref;
        in "tst.red"$
        off cref;
        shut "tst.crf";
\end{verbatim}
To process more than one file, more {\tt IN} statements may be added
before the call of {\tt off cref}, or the {\tt IN} statement changed to
include a list of files.

\subsection{Options}

Functions with the flag {\tt NOLIST} will not be examined or output.
Initially, all Standard Lisp functions are so flagged. (In fact, they are
kept on a list {\tt NOLIST!*}, so if you wish to see references to {\em
all} functions, then {\tt CREF} should be first loaded with the command {\tt
load cref}, and this variable then set to {\tt NIL}).

It should also be remembered that any macros with the property list flag
{\tt EXPAND}, or, if the switch {\tt FORCE} is on, without the property
list flag {\tt NOEXPAND}, will be expanded before the definition is seen
by the cross-reference program, so this flag can also be used to select
those macros you require expanded and those you do not.

\section{Prettyprinting Reduce Expressions}\index{Prettyprinting}

{\REDUCE} includes a module for printing {\REDUCE} syntax in a standard
format.  This module is activated by the switch {\tt PRET},
\ttindex{PRET} which is normally off.

Since the system converts algebraic input into an equivalent symbolic form,
the printing program tries to interpret this as an algebraic expression
before printing it. In most cases, this can be done successfully. However,
there will be occasional instances where results are printed in symbolic
mode form that bears little resemblance to the original input, even though
it is formally equivalent.

If you want to prettyprint a whole file, say {\tt off output,msg;}
\ttindex{MSG} and (hopefully) only clean output will result.  Unlike {\tt
DEFN},\ttindex{DEFN} input is also evaluated with {\tt PRET}
\ttindex{PRET} on.

\section{Prettyprinting Standard Lisp S-Expressions}\index{Prettyprinting}

REDUCE includes a module for printing
S-expressions in a standard format.  The Standard Lisp function for this
purpose is {\tt PRETTYPRINT}\ttindex{PRETTYPRINT} which takes a Lisp
expression and prints the formatted equivalent.

Users can also have their {\REDUCE} input printed in this form by use of
the switch {\tt DEFN}.\ttindex{DEFN} This is in fact a convenient way to
convert {\REDUCE} (or Rlisp) syntax into Lisp. {\tt off msg;} will prevent
warning messages from being printed.

NOTE: When {\tt DEFN} is on, input is not evaluated.