1\chapter{{\REDUCE} and Rlisp Utilities} 2 3{\REDUCE} and its associated support language system Rlisp\index{Rlisp} 4include a number of utilities which have proved useful for program 5development over the years. The following are supported in most of the 6implementations of {\REDUCE} currently available. 7 8\section{The Standard Lisp Compiler}\index{Compiler} 9 10Many versions of {\REDUCE} include a Standard Lisp compiler that is 11automatically loaded on demand. You should check your system specific 12user guide to make sure you have such a compiler. To make the compiler 13active, the switch {\tt COMP}\ttindex{COMP} should be turned on. Any 14further definitions input after this will be compiled automatically. If 15the compiler used is a derivative version of the original Griss-Hearn 16compiler, 17(M. L. Griss and A. 18C. Hearn, ``A Portable LISP Compiler", SOFTWARE --- Practice and Experience 1911 (1981) 541-605), 20there are other switches that might also be 21used in this regard. However, these additional switches are not supported 22in all compilers. They are as follows: 23%\ttindex{PLAP}\ttindex{PGWD}\ttindex{PWRDS} 24 25{\renewcommand{\arraystretch}{2} 26\begin{tabular}{lp{\reduceboxwidth}} 27{\tt PLAP} & If ON, causes the printing of the 28portable macros produced by the compiler; \\ 29% 30{\tt PGWD} & If ON, causes the printing of the 31actual assembly language instructions generated from the macros; \\ 32% 33{\tt PWRDS} & If ON, causes a statistic 34message of the form \newline 35{\tt <function> COMPILED, <words> WORDS, <words> LEFT} \newline 36to be printed. The first number is the number of words of binary 37program space the compiled function took, and the second number 38the number of words left unused in binary program space. \\ 39\end{tabular}} 40 41\section{Fast Loading Code Generation Program}\index{Fast loading of code} 42\label{sec-load} 43In most versions of {\REDUCE}, it is possible to take any set of Lisp, Rlisp 44or {\REDUCE} commands and build a fast loading version of them. In Rlisp or 45{\REDUCE}, one does the following: 46\begin{verbatim} 47 faslout <filename>; 48 <commands or IN statements> 49 faslend; 50\end{verbatim} 51To load such a file, one uses the command {\tt LOAD},\ttindex{LOAD} 52e.g. {\tt load foo;} 53or {\tt load foo,bah;} 54 55This process produces a fast-loading version of the original file. In some 56implementations, this means another file is created with the same name but 57a different extension. For example, in PSL-based systems, the extension is 58{\tt b} (for binary). In CSL-based systems, however, this process adds the 59fast-loading code to a single file in which all such code is stored. 60Particular functions are provided by CSL for managing this file, and 61described in the CSL user documentation. 62 63In doing this build, as with the production of a Standard Lisp form of 64such statements, it is important to remember that some of the commands 65must be instantiated during the building process. For example, macros 66must be expanded, and some property list operations must happen. 67The {\REDUCE} sources should be consulted for further details on this. 68% To facilitate this, the {\tt EVAL} and {\tt IGNORE} flags may be 69% used. Note also that there can be no {\tt LOAD} command within the input 70% statements. 71 72To avoid excessive printout, input statements should be followed by a \$ 73instead of the semicolon. With {\tt LOAD} however, the input doesn't 74print out regardless of which terminator is used with the command. 75 76If you subsequently change the source files used in producing a fast 77loading file, don't forget to repeat the above process in order to update 78the fast loading file correspondingly. Remember also that the text which 79is read in during the creation of the fast load file, in the compiling 80process described above, is {\em not\/} stored in your {\REDUCE} 81environment, but only translated and output. If you want to use the file 82just created, you must then use {\tt LOAD} to load the output of the 83fast-loading file generation program. 84 85When the file to be loaded contains a complete package for a given 86application, {\tt LOAD\_PACKAGE}\ttindex{LOAD\_PACKAGE} rather than 87{\tt LOAD} should be used. The syntax is the same. However, 88{\tt LOAD\_PACKAGE} does some additional bookkeeping such as recording that 89this package has now been loaded, that is required for the correct 90operation of the system. 91 92\section{The Standard Lisp Cross Reference Program}\index{Cross reference} 93 94{\tt CREF}\ttindex{CREF} is a Standard Lisp program for processing a 95set of Standard LISP function definitions to produce: 96\begin{enumerate} 97\item A ``summary'' showing: 98\begin{enumerate} 99\item A list of files processed; 100\item A list of ``entry points'' (functions which are not called or 101are only called by themselves); 102\item A list of undefined functions (functions called but not 103defined in this set of functions); 104\item A list of variables that were used non-locally but not 105declared {\tt GLOBAL} or {\tt FLUID} before their use; 106\item A list of variables that were declared {\tt GLOBAL} but not used 107as {\tt FLUID}s, i.e., bound in a function; 108\item A list of {\tt FLUID} variables that were not bound in a function 109so that one might consider declaring them {\tt GLOBAL}s; 110\item A list of all {\tt GLOBAL} variables present; 111\item A list of all {\tt FLUID} variables present; 112\item A list of all functions present. 113\end{enumerate} 114\item A ``global variable usage'' table, showing for each non-local 115 variable: 116\begin{enumerate} 117\item Functions in which it is used as a declared {\tt FLUID} or {\tt GLOBAL}; 118\item Functions in which it is used but not declared; 119\item Functions in which it is bound; 120\item Functions in which it is changed by {\tt SETQ}. 121\end{enumerate} 122\item A ``function usage'' table showing for each function: 123\begin{enumerate} 124\item Where it is defined; 125\item Functions which call this function; 126\item Functions called by it; 127\item Non-local variables used. 128\end{enumerate} 129\end{enumerate} 130 131The program will also check that functions are called with the correct 132number of arguments, and print a diagnostic message otherwise. 133 134The output is alphabetized on the first seven characters of each function 135name. 136 137\subsection{Restrictions} 138 139Algebraic procedures in {\REDUCE} are treated as if they were symbolic, so 140that algebraic constructs will actually appear as calls to symbolic 141functions, such as {\tt AEVAL}. 142 143\subsection{Usage} 144 145To invoke the cross reference program, the switch {\tt CREF} 146\ttindex{CREF} is used. {\tt on cref} causes the cref program to load 147and the cross-referencing process to begin. After all the required 148definitions are loaded, {\tt off cref} will cause the cross-reference 149listing to be produced. For example, if you wish to cross-reference all 150functions in the file {\tt tst.red}, and produce the cross-reference 151listing in the file {\tt tst.crf}, the following sequence can be used: 152\begin{verbatim} 153 out "tst.crf"; 154 on cref; 155 in "tst.red"$ 156 off cref; 157 shut "tst.crf"; 158\end{verbatim} 159To process more than one file, more {\tt IN} statements may be added 160before the call of {\tt off cref}, or the {\tt IN} statement changed to 161include a list of files. 162 163\subsection{Options} 164 165Functions with the flag {\tt NOLIST} will not be examined or output. 166Initially, all Standard Lisp functions are so flagged. (In fact, they are 167kept on a list {\tt NOLIST!*}, so if you wish to see references to {\em 168all} functions, then {\tt CREF} should be first loaded with the command {\tt 169load cref}, and this variable then set to {\tt NIL}). 170 171It should also be remembered that any macros with the property list flag 172{\tt EXPAND}, or, if the switch {\tt FORCE} is on, without the property 173list flag {\tt NOEXPAND}, will be expanded before the definition is seen 174by the cross-reference program, so this flag can also be used to select 175those macros you require expanded and those you do not. 176 177\section{Prettyprinting Reduce Expressions}\index{Prettyprinting} 178 179{\REDUCE} includes a module for printing {\REDUCE} syntax in a standard 180format. This module is activated by the switch {\tt PRET}, 181\ttindex{PRET} which is normally off. 182 183Since the system converts algebraic input into an equivalent symbolic form, 184the printing program tries to interpret this as an algebraic expression 185before printing it. In most cases, this can be done successfully. However, 186there will be occasional instances where results are printed in symbolic 187mode form that bears little resemblance to the original input, even though 188it is formally equivalent. 189 190If you want to prettyprint a whole file, say {\tt off output,msg;} 191\ttindex{MSG} and (hopefully) only clean output will result. Unlike {\tt 192DEFN},\ttindex{DEFN} input is also evaluated with {\tt PRET} 193\ttindex{PRET} on. 194 195\section{Prettyprinting Standard Lisp S-Expressions}\index{Prettyprinting} 196 197REDUCE includes a module for printing 198S-expressions in a standard format. The Standard Lisp function for this 199purpose is {\tt PRETTYPRINT}\ttindex{PRETTYPRINT} which takes a Lisp 200expression and prints the formatted equivalent. 201 202Users can also have their {\REDUCE} input printed in this form by use of 203the switch {\tt DEFN}.\ttindex{DEFN} This is in fact a convenient way to 204convert {\REDUCE} (or Rlisp) syntax into Lisp. {\tt off msg;} will prevent 205warning messages from being printed. 206 207NOTE: When {\tt DEFN} is on, input is not evaluated. 208 209