% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved. % !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk. \texht{\setcounter{chapter}{0}}{} % Appendix A \newcommand{\lanb}{{\tt [}} \newcommand{\ranb}{{\tt ]}} \newcommand{\vertline}{\texht{$|$}{{\tt |}}} % \newcommand{\ugSysCmdTitle}{\Language{} System Commands} \newcommand{\ugSysCmdNumber}{B.} % % ===================================================================== \begin{page}{ugSysCmdPage}{B. \Language{} System Commands} % ===================================================================== \beginscroll \texht{\bgroup\baselineskip 10pt\ixpt{}\def\Isize{\SIsize}}{} This chapter describes system commands, the command-line facilities used to control the \Language{} environment. The first section is an introduction and discusses the common syntax of the commands available. \table{ { \downlink{\menuitemstyle{A.1. Introduction}}{ugSysCmdOverviewPage} } { \downlink{\menuitemstyle{A.2. )abbreviation}}{ugSysCmdabbreviationPage} } { \downlink{\menuitemstyle{A.3. )boot}}{ugSysCmdbootPage} } { \downlink{\menuitemstyle{A.4. )cd}}{ugSysCmdcdPage} } { \downlink{\menuitemstyle{A.5. )close}}{ugSysCmdclosePage} } { \downlink{\menuitemstyle{A.6. )clear}}{ugSysCmdclearPage} } { \downlink{\menuitemstyle{A.7. )compile}}{ugSysCmdcompilePage} } { \downlink{\menuitemstyle{A.8. )display}}{ugSysCmddisplayPage} } { \downlink{\menuitemstyle{A.9. )edit}}{ugSysCmdeditPage} } { \downlink{\menuitemstyle{A.10. )fin}}{ugSysCmdfinPage} } { \downlink{\menuitemstyle{A.11. )frame}}{ugSysCmdframePage} } { \downlink{\menuitemstyle{A.12. )help}}{ugSysCmdhelpPage} } { \downlink{\menuitemstyle{A.13. )history}}{ugSysCmdhistoryPage} } { \downlink{\menuitemstyle{A.14. )library}}{ugSysCmdlibraryPage} } { \downlink{\menuitemstyle{A.15. )lisp}}{ugSysCmdlispPage} } { \downlink{\menuitemstyle{A.16. )load}}{ugSysCmdloadPage} } { \downlink{\menuitemstyle{A.17. )ltrace}}{ugSysCmdltracePage} } { \downlink{\menuitemstyle{A.18. )pquit}}{ugSysCmdpquitPage} } { \downlink{\menuitemstyle{A.19. )quit}}{ugSysCmdquitPage} } { \downlink{\menuitemstyle{A.20. )read}}{ugSysCmdreadPage} } { \downlink{\menuitemstyle{A.21. )set}}{ugSysCmdsetPage} } { \downlink{\menuitemstyle{A.22. )show}}{ugSysCmdshowPage} } { \downlink{\menuitemstyle{A.23. )spool}}{ugSysCmdspoolPage} } { \downlink{\menuitemstyle{A.24. )synonym}}{ugSysCmdsynonymPage} } { \downlink{\menuitemstyle{A.25. )system}}{ugSysCmdsystemPage} } { \downlink{\menuitemstyle{A.26. )trace}}{ugSysCmdtracePage} } { \downlink{\menuitemstyle{A.27. )undo}}{ugSysCmdundoPage} } { \downlink{\menuitemstyle{A.28. )what}}{ugSysCmdwhatPage} } } \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdOverviewTitle}{Introduction} \newcommand{\ugSysCmdOverviewNumber}{B.1.} % % ===================================================================== \begin{page}{ugSysCmdOverviewPage}{B.1. Introduction} % ===================================================================== \beginscroll System commands are used to perform \Language{} environment management. Among the commands are those that display what has been defined or computed, set up multiple logical \Language{} environments (frames), clear definitions, read files of expressions and commands, show what functions are available, and terminate \Language{}. Some commands are restricted: the commands %-% \HDsyscmdindex{set userlevel interpreter}{ugSysCmdOverviewPage}{B.1.}{Introduction} %-% \HDsyscmdindex{set userlevel compiler}{ugSysCmdOverviewPage}{B.1.}{Introduction} %-% \HDsyscmdindex{set userlevel development}{ugSysCmdOverviewPage}{B.1.}{Introduction} \begin{verbatim} )set userlevel interpreter )set userlevel compiler )set userlevel development \end{verbatim} set the user-access level to the three possible choices. All commands are available at {\tt development} level and the fewest are available at {\tt interpreter} level. The default user-level is {\tt interpreter}. %-% \HDindex{user-level}{ugSysCmdOverviewPage}{B.1.}{Introduction} In addition to the \spadcmd{)set} command (discussed in \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in Section \ugSysCmdsetNumber\ignore{ugSysCmdset}) you can use the \HyperName{} settings facility to change the {\it user-level.} \texht{}{Click on \lispmemolink{Settings}{(|htSystemVariables|)} here to immediately go to the settings facility.} Each command listing begins with one or more syntax pattern descriptions plus examples of related commands. The syntax descriptions are intended to be easy to read and do not necessarily represent the most compact way of specifying all possible arguments and options; the descriptions may occasionally be redundant. All system commands begin with a right parenthesis which should be in the first available column of the input line (that is, immediately after the input prompt, if any). System commands may be issued directly to \Language{} or be included in {\bf .input} files. %-% \HDindex{file!input}{ugSysCmdOverviewPage}{B.1.}{Introduction} A system command {\it argument} is a word that directly follows the command name and is not followed or preceded by a right parenthesis. A system command {\it option} follows the system command and is directly preceded by a right parenthesis. Options may have arguments: they directly follow the option. This example may make it easier to remember what is an option and what is an argument: \centerline{{{\tt )syscmd {\it arg1 arg2} )opt1 {\it opt1arg1 opt1arg2} )opt2 {\it opt2arg1} ...}}} In the system command descriptions, optional arguments and options are enclosed in brackets (``\lanb'' and ``\ranb''). If an argument or option name is in italics, it is meant to be a variable and must have some actual value substituted for it when the system command call is made. For example, the syntax pattern description \noindent {\tt )read} {\it fileName} {\tt \lanb{})quietly\ranb{}} \noindent would imply that you must provide an actual file name for {\it fileName} but need not use the {\tt )quietly} option. Thus \begin{verbatim} )read matrix.input \end{verbatim} is a valid instance of the above pattern. System command names and options may be abbreviated and may be in upper or lower case. The case of actual arguments may be significant, depending on the particular situation (such as in file names). System command names and options may be abbreviated to the minimum number of starting letters so that the name or option is unique. Thus \begin{verbatim} )s Integer \end{verbatim} is not a valid abbreviation for the {\tt )set} command, because both {\tt )set} and {\tt )show} begin with the letter ``s''. Typically, two or three letters are sufficient for disambiguating names. In our descriptions of the commands, we have used no abbreviations for either command names or options. In some syntax descriptions we use a vertical line ``\vertline'' to indicate that you must specify one of the listed choices. For example, in \begin{verbatim} )set output fortran on | off \end{verbatim} only {\tt on} and {\tt off} are acceptable words for following {\tt boot}. We also sometimes use ``...'' to indicate that additional arguments or options of the listed form are allowed. Finally, in the syntax descriptions we may also list the syntax of related commands. \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdabbreviationTitle}{)abbreviation} \newcommand{\ugSysCmdabbreviationNumber}{B.2.} % % ===================================================================== \begin{page}{ugSysCmdabbreviationPage}{B.2. )abbreviation} % ===================================================================== \beginscroll %-% \HDsyscmdindex{abbreviation}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} \par\noindent{\bf User Level Required:} compiler \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )abbreviation query \lanb{}{\it nameOrAbbrev}\ranb{}} \item {\tt )abbreviation category {\it abbrev fullname} \lanb{})quiet\ranb{}} \item {\tt )abbreviation domain {\it abbrev fullname} \lanb{})quiet\ranb{}} \item {\tt )abbreviation package {\it abbrev fullname} \lanb{})quiet\ranb{}} \item {\tt )abbreviation remove {\it nameOrAbbrev}} \end{items} \par\noindent{\bf Command Description:} This command is used to query, set and remove abbreviations for category, domain and package constructors. Every constructor must have a unique abbreviation. This abbreviation is part of the name of the subdirectory under which the components of the compiled constructor are stored. %% BEGIN OBSOLETE %% END OBSOLETE Furthermore, by issuing this command you let the system know what file to load automatically if you use a new constructor. Abbreviations must start with a letter and then be followed by up to seven letters or digits. Any letters appearing in the abbreviation must be in uppercase. When used with the {\tt query} argument, %-% \HDsyscmdindex{abbreviation query}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} this command may be used to list the name associated with a particular abbreviation or the abbreviation for a constructor. If no abbreviation or name is given, the names and corresponding abbreviations for {\it all} constructors are listed. The following shows the abbreviation for the constructor \spadtype{List}: \begin{verbatim} )abbreviation query List \end{verbatim} The following shows the constructor name corresponding to the abbreviation \spadtype{NNI}: \begin{verbatim} )abbreviation query NNI \end{verbatim} The following lists all constructor names and their abbreviations. \begin{verbatim} )abbreviation query \end{verbatim} To add an abbreviation for a constructor, use this command with {\tt category}, {\tt domain} or {\tt package}. %-% \HDsyscmdindex{abbreviation package}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} %-% \HDsyscmdindex{abbreviation domain}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} %-% \HDsyscmdindex{abbreviation category}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} The following add abbreviations to the system for a category, domain and package, respectively: \begin{verbatim} )abbreviation domain SET Set )abbreviation category COMPCAT ComplexCategory )abbreviation package LIST2MAP ListToMap \end{verbatim} If the {\tt )quiet} option is used, no output is displayed from this command. You would normally only define an abbreviation in a library source file. If this command is issued for a constructor that has already been loaded, the constructor will be reloaded next time it is referenced. In particular, you can use this command to force the automatic reloading of constructors. To remove an abbreviation, the {\tt remove} argument is used. %-% \HDsyscmdindex{abbreviation remove}{ugSysCmdabbreviationPage}{B.2.}{)abbreviation} This is usually only used to correct a previous command that set an abbreviation for a constructor name. If, in fact, the abbreviation does exist, you are prompted for confirmation of the removal request. Either of the following commands will remove the abbreviation \spadtype{VECTOR2} and the constructor name \spadtype{VectorFunctions2} from the system: \begin{verbatim} )abbreviation remove VECTOR2 )abbreviation remove VectorFunctions2 \end{verbatim} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdbootTitle}{)boot} \newcommand{\ugSysCmdbootNumber}{B.3.} % % ===================================================================== \begin{page}{ugSysCmdbootPage}{B.3. )boot} % ===================================================================== \beginscroll %-% \HDsyscmdindex{boot}{ugSysCmdbootPage}{B.3.}{)boot} \par\noindent{\bf User Level Required:} development \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )boot} {\it bootExpression} \end{items} \par\noindent{\bf Command Description:} This command is used by \Language{} system developers to execute expressions written in the BOOT language. For example, \begin{verbatim} )boot times3(x) == 3*x \end{verbatim} creates and compiles the \Lisp{} function ``times3'' obtained by translating the BOOT code. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber \downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdcdTitle}{)cd} \newcommand{\ugSysCmdcdNumber}{B.4.} % % ===================================================================== \begin{page}{ugSysCmdcdPage}{B.4. )cd} % ===================================================================== \beginscroll %-% \HDsyscmdindex{cd}{ugSysCmdcdPage}{B.4.}{)cd} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )cd} {\it directory} \end{items} \par\noindent{\bf Command Description:} This command sets the \Language{} working current directory. The current directory is used for looking for input files (for {\tt )read}), \Language{} library source files (for {\tt )compile}), saved history environment files (for {\tt )history )restore}), compiled \Language{} library files (for \spadcmd{)library}), and files to edit (for {\tt )edit}). It is also used for writing spool files (via {\tt )spool}), writing history input files (via {\tt )history )write}) and history environment files (via {\tt )history )save}),and compiled \Language{} library files (via {\tt )compile}). %-% \HDsyscmdindex{read}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{compile}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{history )restore}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{edit}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{spool}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{history )write}{ugSysCmdcdPage}{B.4.}{)cd} %-% \HDsyscmdindex{history )save}{ugSysCmdcdPage}{B.4.}{)cd} If issued with no argument, this command sets the \Language{} current directory to your home directory. If an argument is used, it must be a valid directory name. Except for the ``{\tt )}'' at the beginning of the command, this has the same syntax as the operating system {\tt cd} command. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber \downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdlibraryTitle''}{ugSysCmdlibraryPage} in section \ugSysCmdlibraryNumber \downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber \downlink{``\ugSysCmdspoolTitle''}{ugSysCmdspoolPage} in section \ugSysCmdspoolNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdcloseTitle}{)close} \newcommand{\ugSysCmdcloseNumber}{B.5.} % % ===================================================================== \begin{page}{ugSysCmdclosePage}{B.5. )close} % ===================================================================== \beginscroll %-% \HDsyscmdindex{close}{ugSysCmdclosePage}{B.5.}{)close} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )close} \item{\tt )close )quietly} \end{items} \par\noindent{\bf Command Description:} This command is used to close down interpreter client processes. Such processes are started by \HyperName{} to run \Language{} examples when you click on their text. When you have finished examining or modifying the example and you do not want the extra window around anymore, issue \begin{verbatim} )close \end{verbatim} to the \Language{} prompt in the window. If you try to close down the last remaining interpreter client process, \Language{} will offer to close down the entire \Language{} session and return you to the operating system by displaying something like \begin{verbatim} This is the last AXIOM session. Do you want to kill AXIOM? \end{verbatim} Type "y" (followed by the Return key) if this is what you had in mind. Type "n" (followed by the Return key) to cancel the command. You can use the {\tt )quietly} option to force \Language{} to close down the interpreter client process without closing down the entire \Language{} session. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber \downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdclearTitle}{)clear} \newcommand{\ugSysCmdclearNumber}{B.6.} % % ===================================================================== \begin{page}{ugSysCmdclearPage}{B.6. )clear} % ===================================================================== \beginscroll %-% \HDsyscmdindex{clear}{ugSysCmdclearPage}{B.6.}{)clear} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )clear all} \item{\tt )clear completely} \item{\tt )clear properties all} \item{\tt )clear properties} {\it obj1 \lanb{}obj2 ...\ranb{}} \item{\tt )clear value all} \item{\tt )clear value} {\it obj1 \lanb{}obj2 ...\ranb{}} \item{\tt )clear mode all} \item{\tt )clear mode} {\it obj1 \lanb{}obj2 ...\ranb{}} \end{items} \par\noindent{\bf Command Description:} This command is used to remove function and variable declarations, definitions and values from the workspace. To empty the entire workspace and reset the step counter to 1, issue \begin{verbatim} )clear all \end{verbatim} To remove everything in the workspace but not reset the step counter, issue \begin{verbatim} )clear properties all \end{verbatim} To remove everything about the object {\tt x}, issue \begin{verbatim} )clear properties x \end{verbatim} To remove everything about the objects {\tt x, y} and {\tt f}, issue \begin{verbatim} )clear properties x y f \end{verbatim} The word {\tt properties} may be abbreviated to the single letter ``{\tt p}''. \begin{verbatim} )clear p all )clear p x )clear p x y f \end{verbatim} All definitions of functions and values of variables may be removed by either \begin{verbatim} )clear value all )clear v all \end{verbatim} This retains whatever declarations the objects had. To remove definitions and values for the specific objects {\tt x, y} and {\tt f}, issue \begin{verbatim} )clear value x y f )clear v x y f \end{verbatim} To remove the declarations of everything while leaving the definitions and values, issue \begin{verbatim} )clear mode all )clear m all \end{verbatim} To remove declarations for the specific objects {\tt x, y} and {\tt f}, issue \begin{verbatim} )clear mode x y f )clear m x y f \end{verbatim} The {\tt )display names} and {\tt )display properties} commands may be used to see what is currently in the workspace. The command \begin{verbatim} )clear completely \end{verbatim} does everything that {\tt )clear all} does, and also clears the internal system function and constructor caches. \par\noindent{\bf Also See:} \downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdundoTitle''}{ugSysCmdundoPage} in section \ugSysCmdundoNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdcompileTitle}{)compile} \newcommand{\ugSysCmdcompileNumber}{B.7.} % % ===================================================================== \begin{page}{ugSysCmdcompilePage}{B.7. )compile} % ===================================================================== \beginscroll %-% \HDsyscmdindex{compile}{ugSysCmdcompilePage}{B.7.}{)compile} \par\noindent{\bf User Level Required:} compiler \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )compile} \item {\tt )compile {\it fileName}} \item {\tt )compile {\it fileName}.as} \item {\tt )compile {\it directory/fileName}.as} \item {\tt )compile {\it fileName}.ao} \item {\tt )compile {\it directory/fileName}.ao} \item {\tt )compile {\it fileName}.al} \item {\tt )compile {\it directory/fileName}.al} \item {\tt )compile {\it fileName}.lsp} \item {\tt )compile {\it directory/fileName}.lsp} \item {\tt )compile {\it fileName}.spad} \item {\tt )compile {\it directory/fileName}.spad} \item {\tt )compile {\it fileName} )new} \item {\tt )compile {\it fileName} )old} \item {\tt )compile {\it fileName} )translate} \item {\tt )compile {\it fileName} )quiet} \item {\tt )compile {\it fileName} )noquiet} \item {\tt )compile {\it fileName} )moreargs} \item {\tt )compile {\it fileName} )onlyargs} \item {\tt )compile {\it fileName} )break} \item {\tt )compile {\it fileName} )nobreak} \item {\tt )compile {\it fileName} )library} \item {\tt )compile {\it fileName} )nolibrary} \item {\tt )compile {\it fileName} )vartrace} \item {\tt )compile {\it fileName} )constructor} {\it nameOrAbbrev} \end{items} \par\noindent{\bf Command Description:} You use this command to invoke the new \Language{} library compiler or the old \Language{} system compiler. The {\tt )compile} system command is actually a combination of \Language{} processing and a call to the \axiomxl{} compiler. It is performing double-duty, acting as a front-end to both the \axiomxl{} compiler and the old \Language{} system compiler. (The old \Language{} system compiler was written in Lisp and was an integral part of the \Language{} environment. The \axiomxl{} compiler is written in C and executed by the operating system when called from within \Language{}.) The command compiles files with file extensions {\it .as, .ao} and {\it .al} with the \axiomxl{} compiler and files with file extension {\it .spad} with the old \Language{} system compiler. It also can compile files with file extension {\it .lsp}. These are assumed to be Lisp files genererated by the \axiomxl{} compiler. If you omit the file extension, the command looks to see if you have specified the {\tt )new} or {\tt )old} option. If you have given one of these options, the corresponding compiler is used. Otherwise, the command first looks in the standard system directories for files with extension {\it .as, .ao} and {\it .al} and then files with extension {\it .spad}. The first file found has the appropriate compiler invoked on it. If the command cannot find a matching file, an error message is displayed and the command terminates. The {\tt )translate} option is used to invoke a special version of the old system compiler that will translate a {\it .spad} file to a {\it .as} file. That is, the {\it .spad} file will be parsed and analyzed and a file using the new syntax will be created. By default, the {\it .as} file is created in the same directory as the {\it .spad} file. If that directory is not writable, the current directory is used. If the current directory is not writable, an error message is given and the command terminates. Note that {\tt )translate} implies the {\tt )old} option so the file extension can safely be omitted. If {\tt )translate} is given, all other options are ignored. Please be aware that the translation is not necessarily one hundred percent complete or correct. You should attempt to compile the output with the \axiomxl{} compiler and make any necessary corrections. We now describe the options for the new \axiomxl{} compiler. The first thing {\tt )compile} does is look for a source code filename among its arguments. Thus \begin{verbatim} )compile mycode.as )compile /u/jones/as/mycode.as )compile mycode \end{verbatim} all invoke {\tt )compiler} on the file {\tt /u/jones/as/mycode.as} if the current \Language{} working directory is {\tt /u/jones/as.} (Recall that you can set the working directory via the {\tt )cd} command. If you don't set it explicitly, it is the directory from which you started \Language{}.) This is frequently all you need to compile your file. This simple command: \indent{4} \beginitems \item[1. ] Invokes the \axiomxl{} compiler and produces Lisp output. \item[2. ] Calls the Lisp compiler if the \axiomxl{} compilation was successful. \item[3. ] Uses the {\tt )library} command to tell \Language{} about the contents of your compiled file and arrange to have those contents loaded on demand. \enditems \indent{0} Should you not want the {\tt )library} command automatically invoked, call {\tt )compile} with the {\tt )nolibrary} option. For example, \begin{verbatim} )compile mycode.as )nolibrary \end{verbatim} The general description of \axiomxl{} command line arguments is in the \axiomxl{} documentation. The default options used by the {\tt )compile} command can be viewed and set using the {\tt )set compiler args} \Language{} system command. The current defaults are \begin{verbatim} -O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom \end{verbatim} These options mean: \indent{4} \beginitems \item[-] {\tt -O}: perform all optimizations, \item[-] {\tt -Fasy}: generate a {\tt .asy} file, \item[-] {\tt -Fao}: generate a {\tt .ao} file, \item[-] {\tt -Flsp}: generate a {\tt .lsp} (Lisp) file, %-% \HDindex{Lisp!code generation}{ugSysCmdcompilePage}{B.7.}{)compile} \item[-] {\tt -laxiom}: use the {\tt axiom} library {\tt libaxiom.al}, \item[-] {\tt -Mno-AXL\_W\_WillObsolete}: do not display messages about older generated files becoming obsolete, and \item[-] {\tt -DAxiom}: define the global assertion {\tt Axiom} so that the \axiomxl{} libraries for generating stand-alone code are not accidentally used with \Language{}. \enditems \indent{0} To supplement these default arguments, use the {\tt )moreargs} option on {\tt )compile.} For example, \begin{verbatim} )compile mycode.as )moreargs "-v" \end{verbatim} uses the default arguments and appends the {\tt -v} (verbose) argument flag. The additional argument specification {\bf must be enclosed in double quotes.} To completely replace these default arguments for a particular use of {\tt )compile}, use the {\tt )onlyargs} option. For example, \begin{verbatim} )compile mycode.as )onlyargs "-v -O" \end{verbatim} only uses the {\tt -v} (verbose) and {\tt -O} (optimize) arguments. The argument specification {\bf must be enclosed in double quotes.} In this example, Lisp code is not produced and so the compilation output will not be available to \Language{}. To completely replace the default arguments for all calls to {\tt )compile} within your \Language{} session, use {\tt )set compiler args.} For example, to use the above arguments for all compilations, issue \begin{verbatim} )set compiler args "-v -O" \end{verbatim} Make sure you include the necessary {\tt -l} and {\tt -Y} arguments along with those needed for Lisp file creation. As above, {\bf the argument specification must be enclosed in double quotes.} By default, the {\tt )library} system command {\it exposes} all domains and categories it processes. This means that the \Language{} intepreter will consider those domains and categories when it is trying to resolve a reference to a function. Sometimes domains and categories should not be exposed. For example, a domain may just be used privately by another domain and may not be meant for top-level use. The {\tt )library} command should still be used, though, so that the code will be loaded on demand. In this case, you should use the {\tt )nolibrary} option on {\tt )compile} and the {\tt )noexpose} option in the {\tt )library} command. For example, \begin{verbatim} )compile mycode.as )nolibrary )library mycode )noexpose \end{verbatim} Once you have established your own collection of compiled code, you may find it handy to use the {\tt )dir} option on the {\tt )library} command. This causes {\tt )library} to process all compiled code in the specified directory. For example, \begin{verbatim} )library )dir /u/jones/as/quantum \end{verbatim} You must give an explicit directory after {\tt )dir}, even if you want all compiled code in the current working directory processed, e.g. \begin{verbatim} )library )dir . \end{verbatim} The {\tt )compile} command works with several file extensions. We saw above what happens when it is invoked on a file with extension {\tt .as.} A {\tt .ao} file is a portable binary compiled version of a {\tt .as} file, and {\tt )compile} simply passes the {\tt .ao} file onto \axiomxl{}. The generated Lisp file is compiled and {\tt )library} is automatically called, just as if you had specified a {\tt .as} file. A {\tt .al} file is an archive file containing {\tt .ao} files. The archive is created (on Unix systems) with the {\tt ar} program. When {\tt )compile} is given a {\tt .al} file, it creates a directory whose name is based on that of the archive. For example, if you issue \begin{verbatim} )compile mylib.al \end{verbatim} the directory {\tt mylib.axldir} is created. All members of the archive are unarchived into the directory and {\tt )compile} is called on each {\tt .ao} file found. It is your responsibility to remove the directory and its contents, if you choose to do so. A {\tt .lsp} file is a Lisp source file, presumably, in our context, generated by \axiomxl{} when called with the {\tt -Flsp} option. When {\tt )compile} is used with a {\tt .lsp} file, the Lisp file is compiled and {\tt )library} is called. You must also have present a {\tt .asy} generated from the same source file. The following are descriptions of options for the old system compiler. You can compile category, domain, and package constructors contained in files with file extension {\it .spad}. You can compile individual constructors or every constructor in a file. The full filename is remembered between invocations of this command and {\tt )edit} commands. The sequence of commands \begin{verbatim} )compile matrix.spad )edit )compile \end{verbatim} will call the compiler, edit, and then call the compiler again on the file {\bf matrix.spad.} If you do not specify a {\it directory,} the working current directory (see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd}) is searched for the file. If the file is not found, the standard system directories are searched. If you do not give any options, all constructors within a file are compiled. Each constructor should have an {\tt )abbreviation} command in the file in which it is defined. We suggest that you place the {\tt )abbreviation} commands at the top of the file in the order in which the constructors are defined. The list of commands serves as a table of contents for the file. %-% \HDsyscmdindex{abbreviation}{ugSysCmdcompilePage}{B.7.}{)compile} The {\tt )library} option causes directories containing the compiled code for each constructor to be created in the working current directory. The name of such a directory consists of the constructor abbreviation and the {\bf .NRLIB} file extension. For example, the directory containing the compiled code for the \axiomType{MATRIX} constructor is called {\bf MATRIX.NRLIB.} The {\tt )nolibrary} option says that such files should not be created. The default is {\tt )library.} Note that the semantics of {\tt )library} and {\tt )nolibrary} for the new \axiomxl{} compiler and for the old system compiler are completely different. The {\tt )vartrace} option causes the compiler to generate extra code for the constructor to support conditional tracing of variable assignments. (see \downlink{``\ugSysCmdtraceTitle''}{ugSysCmdtracePage} in Section \ugSysCmdtraceNumber\ignore{ugSysCmdtrace}). Without this option, this code is suppressed and one cannot use the {\tt )vars} option for the trace command. The {\tt )constructor} option is used to specify a particular constructor to compile. All other constructors in the file are ignored. The constructor name or abbreviation follows {\tt )constructor.} Thus either \begin{verbatim} )compile matrix.spad )constructor RectangularMatrix \end{verbatim} or \begin{verbatim} )compile matrix.spad )constructor RMATRIX \end{verbatim} compiles the \axiomType{RectangularMatrix} constructor defined in {\bf matrix.spad.} The {\tt )break} and {\tt )nobreak} options determine what the old system compiler does when it encounters an error. {\tt )break} is the default and it indicates that processing should stop at the first error. The value of the {\tt )set break} variable then controls what happens. %% BEGIN OBSOLTE %% END OBSOLTE \par\noindent{\bf Also See:} \downlink{``\ugSysCmdabbreviationTitle''}{ugSysCmdabbreviationPage} in section \ugSysCmdabbreviationNumber \downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber \downlink{``\ugSysCmdlibraryTitle''}{ugSysCmdlibraryPage} in section \ugSysCmdlibraryNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmddisplayTitle}{)display} \newcommand{\ugSysCmddisplayNumber}{B.8.} % % ===================================================================== \begin{page}{ugSysCmddisplayPage}{B.8. )display} % ===================================================================== \beginscroll %-% \HDsyscmdindex{display}{ugSysCmddisplayPage}{B.8.}{)display} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )display all} \item {\tt )display properties} \item {\tt )display properties all} \item {\tt )display properties} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}} \item {\tt )display value all} \item {\tt )display value} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}} \item {\tt )display mode all} \item {\tt )display mode} {\it \lanb{}obj1 \lanb{}obj2 ...\ranb{}\ranb{}} \item {\tt )display names} \item {\tt )display operations} {\it opName} \end{items} \par\noindent{\bf Command Description:} This command is used to display the contents of the workspace and signatures of functions with a given name.\footnote{A \spadgloss{signature} gives the argument and return types of a function.} The command \begin{verbatim} )display names \end{verbatim} lists the names of all user-defined objects in the workspace. This is useful if you do not wish to see everything about the objects and need only be reminded of their names. The commands \begin{verbatim} )display all )display properties )display properties all \end{verbatim} all do the same thing: show the values and types and declared modes of all variables in the workspace. If you have defined functions, their signatures and definitions will also be displayed. To show all information about a particular variable or user functions, for example, something named {\tt d}, issue \begin{verbatim} )display properties d \end{verbatim} To just show the value (and the type) of {\tt d}, issue \begin{verbatim} )display value d \end{verbatim} To just show the declared mode of {\tt d}, issue \begin{verbatim} )display mode d \end{verbatim} All modemaps for a given operation may be displayed by using {\tt )display operations}. A \spadgloss{modemap} is a collection of information about a particular reference to an operation. This includes the types of the arguments and the return value, the location of the implementation and any conditions on the types. The modemap may contain patterns. The following displays the modemaps for the operation \spadfunFrom{complex}{ComplexCategory}: \begin{verbatim} )d op complex \end{verbatim} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdclearTitle''}{ugSysCmdclearPage} in section \ugSysCmdclearNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdshowTitle''}{ugSysCmdshowPage} in section \ugSysCmdshowNumber \downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdeditTitle}{)edit} \newcommand{\ugSysCmdeditNumber}{B.9.} % % ===================================================================== \begin{page}{ugSysCmdeditPage}{B.9. )edit} % ===================================================================== \beginscroll %-% \HDsyscmdindex{edit}{ugSysCmdeditPage}{B.9.}{)edit} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )edit} \lanb{}{\it filename}\ranb{} \end{items} \par\noindent{\bf Command Description:} This command is used to edit files. It works in conjunction with the {\tt )read} and {\tt )compile} commands to remember the name of the file on which you are working. By specifying the name fully, you can edit any file you wish. Thus \begin{verbatim} )edit /u/julius/matrix.input \end{verbatim} will place you in an editor looking at the file {\tt /u/julius/matrix.input}. %-% \HDindex{editing files}{ugSysCmdeditPage}{B.9.}{)edit} By default, the editor is {\tt vi}, %-% \HDindex{vi}{ugSysCmdeditPage}{B.9.}{)edit} but if you have an EDITOR shell environment variable defined, that editor will be used. When \Language{} is running under the X Window System, it will try to open a separate {\tt xterm} running your editor if it thinks one is necessary. %-% \HDindex{Korn shell}{ugSysCmdeditPage}{B.9.}{)edit} For example, under the Korn shell, if you issue \begin{verbatim} export EDITOR=emacs \end{verbatim} then the emacs %-% \HDindex{emacs}{ugSysCmdeditPage}{B.9.}{)edit} editor will be used by \spadcmd{)edit}. If you do not specify a file name, the last file you edited, read or compiled will be used. If there is no ``last file'' you will be placed in the editor editing an empty unnamed file. It is possible to use the {\tt )system} command to edit a file directly. For example, \begin{verbatim} )system emacs /etc/rc.tcpip \end{verbatim} calls {\tt emacs} to edit the file. %-% \HDindex{emacs}{ugSysCmdeditPage}{B.9.}{)edit} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber \downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdfinTitle}{)fin} \newcommand{\ugSysCmdfinNumber}{B.10.} % % ===================================================================== \begin{page}{ugSysCmdfinPage}{B.10. )fin} % ===================================================================== \beginscroll %-% \HDsyscmdindex{fin}{ugSysCmdfinPage}{B.10.}{)fin} \par\noindent{\bf User Level Required:} development \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )fin} \end{items} \par\noindent{\bf Command Description:} This command is used by \Language{} developers to leave the \Language{} system and return to the underlying \Lisp{} system. To return to \Language{}, issue the ``{\tt (\vertline{}spad\vertline{})}'' function call to \Lisp{}. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber \downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdframeTitle}{)frame} \newcommand{\ugSysCmdframeNumber}{B.11.} % % ===================================================================== \begin{page}{ugSysCmdframePage}{B.11. )frame} % ===================================================================== \beginscroll %-% \HDsyscmdindex{frame}{ugSysCmdframePage}{B.11.}{)frame} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )frame new {\it frameName}} \item{\tt )frame drop {\it \lanb{}frameName\ranb{}}} \item{\tt )frame next} \item{\tt )frame last} \item{\tt )frame names} \item{\tt )frame import {\it frameName} {\it \lanb{}objectName1 \lanb{}objectName2 ...\ranb{}\ranb{}}} \item{\tt )set message frame on \vertline{} off} \item{\tt )set message prompt frame} \end{items} \par\noindent{\bf Command Description:} A {\it frame} can be thought of as a logical session within the physical session that you get when you start the system. You can have as many frames as you want, within the limits of your computer's storage, paging space, and so on. Each frame has its own {\it step number}, {\it environment} and {\it history.} You can have a variable named {\tt a} in one frame and it will have nothing to do with anything that might be called {\tt a} in any other frame. Some frames are created by the \HyperName{} program and these can have pretty strange names, since they are generated automatically. %-% \HDsyscmdindex{frame names}{ugSysCmdframePage}{B.11.}{)frame} To find out the names of all frames, issue \begin{verbatim} )frame names \end{verbatim} It will indicate the name of the current frame. You create a new frame %-% \HDsyscmdindex{frame new}{ugSysCmdframePage}{B.11.}{)frame} ``{\bf quark}'' by issuing \begin{verbatim} )frame new quark \end{verbatim} The history facility can be turned on by issuing either {\tt )set history on} or {\tt )history )on}. If the history facility is on and you are saving history information in a file rather than in the \Language{} environment then a history file with filename {\bf quark.axh} will be created as you enter commands. If you wish to go back to what you were doing in the %-% \HDsyscmdindex{frame next}{ugSysCmdframePage}{B.11.}{)frame} ``{\bf initial}'' frame, use %-% \HDsyscmdindex{frame last}{ugSysCmdframePage}{B.11.}{)frame} \begin{verbatim} )frame next \end{verbatim} or \begin{verbatim} )frame last \end{verbatim} to cycle through the ring of available frames to get back to ``{\bf initial}''. If you want to throw away a frame (say ``{\bf quark}''), issue \begin{verbatim} )frame drop quark \end{verbatim} If you omit the name, the current frame is dropped. %-% \HDsyscmdindex{frame drop}{ugSysCmdframePage}{B.11.}{)frame} If you do use frames with the history facility on and writing to a file, you may want to delete some of the older history files. %-% \HDindex{file!history}{ugSysCmdframePage}{B.11.}{)frame} These are directories, so you may want to issue a command like {\tt rm -r quark.axh} to the operating system. You can bring things from another frame by using %-% \HDsyscmdindex{frame import}{ugSysCmdframePage}{B.11.}{)frame} {\tt )frame import}. For example, to bring the {\tt f} and {\tt g} from the frame ``{\bf quark}'' to the current frame, issue \begin{verbatim} )frame import quark f g \end{verbatim} If you want everything from the frame ``{\bf quark}'', issue \begin{verbatim} )frame import quark \end{verbatim} You will be asked to verify that you really want everything. There are two {\tt )set} flags %-% \HDsyscmdindex{set message frame}{ugSysCmdframePage}{B.11.}{)frame} to make it easier to tell where you are. \begin{verbatim} )set message frame on | off \end{verbatim} will print more messages about frames when it is set on. By default, it is off. \begin{verbatim} )set message prompt frame \end{verbatim} will give a prompt %-% \HDsyscmdindex{set message prompt frame}{ugSysCmdframePage}{B.11.}{)frame} that looks like \begin{verbatim} initial (1) -> \end{verbatim} %-% \HDindex{prompt!with frame name}{ugSysCmdframePage}{B.11.}{)frame} when you start up. In this case, the frame name and step make up the prompt. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdhelpTitle}{)help} \newcommand{\ugSysCmdhelpNumber}{B.12.} % % ===================================================================== \begin{page}{ugSysCmdhelpPage}{B.12. )help} % ===================================================================== \beginscroll %-% \HDsyscmdindex{help}{ugSysCmdhelpPage}{B.12.}{)help} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )help} \item{\tt )help} {\it commandName} \end{items} \par\noindent{\bf Command Description:} This command displays help information about system commands. If you issue \begin{verbatim} )help \end{verbatim} then this very text will be shown. You can also give the name or abbreviation of a system command to display information about it. For example, \begin{verbatim} )help clear \end{verbatim} will display the description of the {\tt )clear} system command. All this material is available in the \Language{} User Guide and in \HyperName{}. In \HyperName{}, choose the {\bf Commands} item from the {\bf Reference} menu. \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdhistoryTitle}{)history} \newcommand{\ugSysCmdhistoryNumber}{B.13.} % % ===================================================================== \begin{page}{ugSysCmdhistoryPage}{B.13. )history} % ===================================================================== \beginscroll %-% \HDsyscmdindex{history}{ugSysCmdhistoryPage}{B.13.}{)history} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )history )on} \item{\tt )history )off} \item{\tt )history )write} {\it historyInputFileName} \item{\tt )history )show \lanb{}{\it n}\ranb{} \lanb{}both\ranb{}} \item{\tt )history )save} {\it savedHistoryName} \item{\tt )history )restore} \lanb{}{\it savedHistoryName}\ranb{} \item{\tt )history )reset} \item{\tt )history )change} {\it n} \item{\tt )history )memory} \item{\tt )history )file} \item{\tt \%} \item{\tt \%\%({\it n})} \item{\tt )set history on \vertline{} off} \end{items} \par\noindent{\bf Command Description:} The {\it history} facility within \Language{} allows you to restore your environment to that of another session and recall previous computational results. Additional commands allow you to review previous input lines and to create an {\bf .input} file of the lines typed to %-% \HDindex{file!input}{ugSysCmdhistoryPage}{B.13.}{)history} \Language{}. \Language{} saves your input and output if the history facility is turned on (which is the default). This information is saved if either of \begin{verbatim} )set history on )history )on \end{verbatim} has been issued. Issuing either \begin{verbatim} )set history off )history )off \end{verbatim} will discontinue the recording of information. %-% \HDsyscmdindex{history )on}{ugSysCmdhistoryPage}{B.13.}{)history} %-% \HDsyscmdindex{set history on}{ugSysCmdhistoryPage}{B.13.}{)history} %-% \HDsyscmdindex{set history off}{ugSysCmdhistoryPage}{B.13.}{)history} %-% \HDsyscmdindex{history )off}{ugSysCmdhistoryPage}{B.13.}{)history} Whether the facility is disabled or not, the value of \spadSyntax{\%} in \Language{} always refers to the result of the last computation. If you have not yet entered anything, \spadSyntax{\%} evaluates to an object of type \spadtype{Variable('\%)}. The function \spadSyntax{\%\%} may be used to refer to other previous results if the history facility is enabled. In that case, {\tt \%\%(n)} is the output from step {\tt n} if {\tt n > 0}. If {\tt n < 0}, the step is computed relative to the current step. Thus {\tt \%\%(-1)} is also the previous step, {\tt \%\%(-2)}, is the step before that, and so on. If an invalid step number is given, \Language{} will signal an error. The {\it environment} information can either be saved in a file or entirely in memory (the default). Each frame (\downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in Section \ugSysCmdframeNumber\ignore{ugSysCmdframe}) has its own history database. When it is kept in a file, some of it may also be kept in memory for efficiency. When the information is saved in a file, the name of the file is of the form {\bf FRAME.axh} where ``{\bf FRAME}'' is the name of the current frame. The history file is placed in the current working directory (see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd}). Note that these history database files are not text files (in fact, they are directories themselves), and so are not in human-readable format. The options to the {\tt )history} command are as follows: \indent{0} \beginitems \item[{\tt )change} {\it n}] will set the number of steps that are saved in memory to {\it n}. This option only has effect when the history data is maintained in a file. If you have issued {\tt )history )memory} (or not changed the default) there is no need to use {\tt )history )change}. %-% \HDsyscmdindex{history )change}{ugSysCmdhistoryPage}{B.13.}{)history} \item[{\tt )on}] will start the recording of information. If the workspace is not empty, you will be asked to confirm this request. If you do so, the workspace will be cleared and history data will begin being saved. You can also turn the facility on by issuing {\tt )set history on}. \item[{\tt )off}] will stop the recording of information. The {\tt )history )show} command will not work after issuing this command. Note that this command may be issued to save time, as there is some performance penalty paid for saving the environment data. You can also turn the facility off by issuing {\tt )set history off}. \item[{\tt )file}] indicates that history data should be saved in an external file on disk. \item[{\tt )memory}] indicates that all history data should be kept in memory rather than saved in a file. Note that if you are computing with very large objects it may not be practical to kept this data in memory. \item[{\tt )reset}] will flush the internal list of the most recent workspace calculations so that the data structures may be garbage collected by the underlying \Lisp{} system. Like {\tt )history )change}, this option only has real effect when history data is being saved in a file. \item[{\tt )restore} \lanb{}{\it savedHistoryName}\ranb{}] completely clears the environment and restores it to a saved session, if possible. The {\tt )save} option below allows you to save a session to a file with a given name. If you had issued {\tt )history )save jacobi} the command {\tt )history )restore jacobi} would clear the current workspace and load the contents of the named saved session. If no saved session name is specified, the system looks for a file called {\bf last.axh}. \item[{\tt )save} {\it savedHistoryName}] is used to save a snapshot of the environment in a file. This file is placed in the current working directory (see \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in Section \ugSysCmdcdNumber\ignore{ugSysCmdcd}). Use {\tt )history )restore} to restore the environment to the state preserved in the file. This option also creates an input file containing all the lines of input since you created the workspace frame (for example, by starting your \Language{} session) or last did a \spadcmd{)clear all} or \spadcmd{)clear completely}. \item[{\tt )show} \lanb{}{\it n}\ranb{} \lanb{}{\tt both}\ranb{}] can show previous input lines and output results. {\tt )show} will display up to twenty of the last input lines (fewer if you haven't typed in twenty lines). {\tt )show} {\it n} will display up to {\it n} of the last input lines. {\tt )show both} will display up to five of the last input lines and output results. {\tt )show} {\it n} {\tt both} will display up to {\it n} of the last input lines and output results. \item[{\tt )write} {\it historyInputFile}] creates an {\bf .input} file with the input lines typed since the start of the session/frame or the last {\tt )clear all} or {\tt )clear completely}. If {\it historyInputFileName} does not contain a period (``.'') in the filename, {\bf .input} is appended to it. For example, {\tt )history )write chaos} and {\tt )history )write chaos.input} both write the input lines to a file called {\bf chaos.input} in your current working directory. If you issued one or more {\tt )undo} commands, {\tt )history )write} eliminates all input lines backtracked over as a result of {\tt )undo}. You can edit this file and then use {\tt )read} to have \Language{} process the contents. \enditems \indent{0} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in section \ugSysCmdframeNumber \downlink{``\ugSysCmdreadTitle''}{ugSysCmdreadPage} in section \ugSysCmdreadNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdundoTitle''}{ugSysCmdundoPage} in section \ugSysCmdundoNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdlibraryTitle}{)library} \newcommand{\ugSysCmdlibraryNumber}{B.14.} % % ===================================================================== \begin{page}{ugSysCmdlibraryPage}{B.14. )library} % ===================================================================== \beginscroll %-% \HDsyscmdindex{library}{ugSysCmdlibraryPage}{B.14.}{)library} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )library {\it libName1 \lanb{}libName2 ...\ranb{}}} \item{\tt )library )dir {\it dirName}} \item{\tt )library )only {\it objName1 \lanb{}objlib2 ...\ranb{}}} \item{\tt )library )noexpose} \end{items} \par\noindent{\bf Command Description:} This command replaces the {\tt )load} system command that was available in \Language{} releases before version 2.0. The \spadcmd{)library} command makes available to \Language{} the compiled objects in the libraries listed. For example, if you {\tt )compile dopler.as} in your home directory, issue {\tt )library dopler} to have \Language{} look at the library, determine the category and domain constructors present, update the internal database with various properties of the constructors, and arrange for the constructors to be automatically loaded when needed. If the {\tt )noexpose} option has not been given, the constructors will be exposed (that is, available) in the current frame. If you compiled a file with the old system compiler, you will have an {\it NRLIB} present, for example, {\it DOPLER.NRLIB,} where {\tt DOPLER} is a constructor abbreviation. The command {\tt )library DOPLER} will then do the analysis and database updates as above. To tell the system about all libraries in a directory, use {\tt )library )dir dirName} where {\tt dirName} is an explicit directory. You may specify ``.'' as the directory, which means the current directory from which you started the system or the one you set via the \spadcmd{)cd} command. The directory name is required. You may only want to tell the system about particular constructors within a library. In this case, use the {\tt )only} option. The command {\tt )library dopler )only Test1} will only cause the {\sf Test1} constructor to be analyzed, autoloaded, etc.. Finally, each constructor in a library are usually automatically exposed when the \spadcmd{)library} command is used. Use the {\tt )noexpose} option if you not want them exposed. At a later time you can use {\tt )set expose add constructor} to expose any hidden constructors. {\bf Note for \Language{} beta testers:} At various times this command was called {\tt )local} and {\tt )with} before the name {\tt )library} became the official name. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in section \ugSysCmdcdNumber \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber \downlink{``\ugSysCmdframeTitle''}{ugSysCmdframePage} in section \ugSysCmdframeNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdlispTitle}{)lisp} \newcommand{\ugSysCmdlispNumber}{B.15.} % % ===================================================================== \begin{page}{ugSysCmdlispPage}{B.15. )lisp} % ===================================================================== \beginscroll %-% \HDsyscmdindex{lisp}{ugSysCmdlispPage}{B.15.}{)lisp} \par\noindent{\bf User Level Required:} development \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )lisp} {\it\lanb{}lispExpression\ranb{}} \end{items} \par\noindent{\bf Command Description:} This command is used by \Language{} system developers to have single expressions evaluated by the \Lisp{} system on which \Language{} is built. The {\it lispExpression} is read by the \Lisp{} reader and evaluated. If this expression is not complete (unbalanced parentheses, say), the reader will wait until a complete expression is entered. Since this command is only useful for evaluating single expressions, the {\tt )fin} command may be used to drop out of \Language{} into \Lisp{}. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber \downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber \downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdloadTitle}{)load} \newcommand{\ugSysCmdloadNumber}{B.16.} % % ===================================================================== \begin{page}{ugSysCmdloadPage}{B.16. )load} % ===================================================================== \beginscroll %-% \HDsyscmdindex{load}{ugSysCmdloadPage}{B.16.}{)load} \par\noindent{\bf User Level Required:} interpreter %% BEGIN OBSOLETE %% END OBSOLETE \par\noindent{\bf Command Description:} This command is obsolete. Use \spadcmd{)library} instead. %% BEGIN OBSOLETE % % % % %% END OBSOLETE \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdltraceTitle}{)ltrace} \newcommand{\ugSysCmdltraceNumber}{B.17.} % % ===================================================================== \begin{page}{ugSysCmdltracePage}{B.17. )ltrace} % ===================================================================== \beginscroll %-% \HDsyscmdindex{ltrace}{ugSysCmdltracePage}{B.17.}{)ltrace} \par\noindent{\bf User Level Required:} development \par\noindent{\bf Command Syntax:} This command has the same arguments as options as the \spadcmd{)trace} command. \par\noindent{\bf Command Description:} This command is used by \Language{} system developers to trace \Lisp{} or BOOT functions. It is not supported for general use. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber \downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber \downlink{``\ugSysCmdtraceTitle''}{ugSysCmdtracePage} in section \ugSysCmdtraceNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdpquitTitle}{)pquit} \newcommand{\ugSysCmdpquitNumber}{B.18.} % % ===================================================================== \begin{page}{ugSysCmdpquitPage}{B.18. )pquit} % ===================================================================== \beginscroll %-% \HDsyscmdindex{pquit}{ugSysCmdpquitPage}{B.18.}{)pquit} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )pquit} \end{items} \par\noindent{\bf Command Description:} This command is used to terminate \Language{} and return to the operating system. Other than by redoing all your computations or by using the {\tt )history )restore} command to try to restore your working environment, you cannot return to \Language{} in the same state. {\tt )pquit} differs from the {\tt )quit} in that it always asks for confirmation that you want to terminate \Language{} (the ``p'' is for ``protected''). %-% \HDsyscmdindex{quit}{ugSysCmdpquitPage}{B.18.}{)pquit} When you enter the {\tt )pquit} command, \Language{} responds % \centerline{{Please enter {\bf y} or {\bf yes} if you really want to leave the interactive }} \centerline{{environment and return to the operating system:}} % If you respond with {\tt y} or {\tt yes}, you will see the message % \centerline{{You are now leaving the \Language{} interactive environment. }} \centerline{{Issue the command {\bf axiom} to the operating system to start a new session.}} % and \Language{} will terminate and return you to the operating system (or the environment from which you invoked the system). If you responded with something other than {\tt y} or {\tt yes}, then the message % \centerline{{You have chosen to remain in the \Language{} interactive environment.}} % will be displayed and, indeed, \Language{} would still be running. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdcloseTitle''}{ugSysCmdclosePage} in section \ugSysCmdcloseNumber \downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber \downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdquitTitle}{)quit} \newcommand{\ugSysCmdquitNumber}{B.19.} % % ===================================================================== \begin{page}{ugSysCmdquitPage}{B.19. )quit} % ===================================================================== \beginscroll %-% \HDsyscmdindex{quit}{ugSysCmdquitPage}{B.19.}{)quit} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )quit} \item{\tt )set quit protected \vertline{} unprotected} \end{items} \par\noindent{\bf Command Description:} This command is used to terminate \Language{} and return to the operating system. Other than by redoing all your computations or by using the {\tt )history )restore} command to try to restore your working environment, you cannot return to \Language{} in the same state. {\tt )quit} differs from the {\tt )pquit} in that it asks for %-% \HDsyscmdindex{pquit}{ugSysCmdquitPage}{B.19.}{)quit} confirmation only if the command \begin{verbatim} )set quit protected \end{verbatim} has been issued. %-% \HDsyscmdindex{set quit protected}{ugSysCmdquitPage}{B.19.}{)quit} Otherwise, {\tt )quit} will make \Language{} terminate and return you to the operating system (or the environment from which you invoked the system). The default setting is {\tt )set quit protected} so that {\tt )quit} and {\tt )pquit} behave in the same way. If you do issue \begin{verbatim} )set quit unprotected \end{verbatim} we %-% \HDsyscmdindex{set quit unprotected}{ugSysCmdquitPage}{B.19.}{)quit} suggest that you do not (somehow) assign {\tt )quit} to be executed when you press, say, a function key. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \downlink{``\ugSysCmdcloseTitle''}{ugSysCmdclosePage} in section \ugSysCmdcloseNumber \downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber \downlink{``\ugSysCmdsystemTitle''}{ugSysCmdsystemPage} in section \ugSysCmdsystemNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdreadTitle}{)read} \newcommand{\ugSysCmdreadNumber}{B.20.} % % ===================================================================== \begin{page}{ugSysCmdreadPage}{B.20. )read} % ===================================================================== \beginscroll %-% \HDsyscmdindex{read}{ugSysCmdreadPage}{B.20.}{)read} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )read} {\it \lanb{}fileName\ranb{}} \item {\tt )read} {\it \lanb{}fileName\ranb{}} \lanb{}{\tt )quiet}\ranb{} \lanb{}{\tt )ifthere}\ranb{} \end{items} \par\noindent{\bf Command Description:} This command is used to read {\bf .input} files into \Language{}. %-% \HDindex{file!input}{ugSysCmdreadPage}{B.20.}{)read} The command \begin{verbatim} )read matrix.input \end{verbatim} will read the contents of the file {\bf matrix.input} into \Language{}. The ``.input'' file extension is optional. See \downlink{``\ugInOutInTitle''}{ugInOutInPage} in Section \ugInOutInNumber\ignore{ugInOutIn} for more information about {\bf .input} files. This command remembers the previous file you edited, read or compiled. If you do not specify a file name, the previous file will be read. The {\tt )ifthere} option checks to see whether the {\bf .input} file exists. If it does not, the {\tt )read} command does nothing. If you do not use this option and the file does not exist, you are asked to give the name of an existing {\bf .input} file. The {\tt )quiet} option suppresses output while the file is being read. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in section \ugSysCmdcompileNumber \downlink{``\ugSysCmdeditTitle''}{ugSysCmdeditPage} in section \ugSysCmdeditNumber \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdsetTitle}{)set} \newcommand{\ugSysCmdsetNumber}{B.21.} % % ===================================================================== \begin{page}{ugSysCmdsetPage}{B.21. )set} % ===================================================================== \beginscroll %-% \HDsyscmdindex{set}{ugSysCmdsetPage}{B.21.}{)set} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item {\tt )set} \item {\tt )set} {\it label1 \lanb{}... labelN\ranb{}} \item {\tt )set} {\it label1 \lanb{}... labelN\ranb{} newValue} \end{items} \par\noindent{\bf Command Description:} The {\tt )set} command is used to view or set system variables that control what messages are displayed, the type of output desired, the status of the history facility, the way \Language{} user functions are cached, and so on. Since this collection is very large, we will not discuss them here. Rather, we will show how the facility is used. We urge you to explore the {\tt )set} options to familiarize yourself with how you can modify your \Language{} working environment. There is a \HyperName{} version of this same facility available from the main \HyperName{} menu. \texht{}{Click \lispmemolink{here}{(|htSystemVariables|)} to go to it.} The {\tt )set} command is command-driven with a menu display. It is tree-structured. To see all top-level nodes, issue {\tt )set} by itself. \begin{verbatim} )set \end{verbatim} Variables with values have them displayed near the right margin. Subtrees of selections have ``{\tt ...}'' displayed in the value field. For example, there are many kinds of messages, so issue {\tt )set message} to see the choices. \begin{verbatim} )set message \end{verbatim} The current setting for the variable that displays %-% \HDindex{computation timings!displaying}{ugSysCmdsetPage}{B.21.}{)set} whether computation times %-% \HDindex{timings!displaying}{ugSysCmdsetPage}{B.21.}{)set} are displayed is visible in the menu displayed by the last command. To see more information, issue \begin{verbatim} )set message time \end{verbatim} This shows that time printing is on now. To turn it off, issue \begin{verbatim} )set message time off \end{verbatim} %-% \HDsyscmdindex{set message time}{ugSysCmdsetPage}{B.21.}{)set} As noted above, not all settings have so many qualifiers. For example, to change the {\tt )quit} command to being unprotected (that is, you will not be prompted for verification), you need only issue \begin{verbatim} )set quit unprotected \end{verbatim} %-% \HDsyscmdindex{set quit unprotected}{ugSysCmdsetPage}{B.21.}{)set} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdshowTitle}{)show} \newcommand{\ugSysCmdshowNumber}{B.22.} % % ===================================================================== \begin{page}{ugSysCmdshowPage}{B.22. )show} % ===================================================================== \beginscroll %-% \HDsyscmdindex{show}{ugSysCmdshowPage}{B.22.}{)show} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )show {\it nameOrAbbrev}} \item{\tt )show {\it nameOrAbbrev} )operations} \item{\tt )show {\it nameOrAbbrev} )attributes} \end{items} \par\noindent{\bf Command Description:} This command displays information about \Language{} domain, package and category {\it constructors}. If no options are given, the {\tt )operations} option is assumed. For example, \begin{verbatim} )show POLY )show POLY )operations )show Polynomial )show Polynomial )operations \end{verbatim} each display basic information about the \spadtype{Polynomial} domain constructor and then provide a listing of operations. Since \spadtype{Polynomial} requires a \spadtype{Ring} (for example, \spadtype{Integer}) as argument, the above commands all refer to a unspecified ring {\tt R}. In the list of operations, \spadSyntax{\$} means \spadtype{Polynomial(R)}. The basic information displayed includes the {\it signature} of the constructor (the name and arguments), the constructor {\it abbreviation}, the {\it exposure status} of the constructor, and the name of the {\it library source file} for the constructor. If operation information about a specific domain is wanted, the full or abbreviated domain name may be used. For example, \begin{verbatim} )show POLY INT )show POLY INT )operations )show Polynomial Integer )show Polynomial Integer )operations \end{verbatim} are among the combinations that will display the operations exported by the domain \spadtype{Polynomial(Integer)} (as opposed to the general {\it domain constructor} \spadtype{Polynomial}). Attributes may be listed by using the {\tt )attributes} option. \par\noindent{\bf Also See:} \downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdspoolTitle}{)spool} \newcommand{\ugSysCmdspoolNumber}{B.23.} % % ===================================================================== \begin{page}{ugSysCmdspoolPage}{B.23. )spool} % ===================================================================== \beginscroll %-% \HDsyscmdindex{spool}{ugSysCmdspoolPage}{B.23.}{)spool} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )spool} \lanb{}{\it fileName}\ranb{} \item{\tt )spool} \end{items} \par\noindent{\bf Command Description:} This command is used to save {\it (spool)} all \Language{} input and output %-% \HDindex{file!spool}{ugSysCmdspoolPage}{B.23.}{)spool} into a file, called a {\it spool file.} You can only have one spool file active at a time. To start spool, issue this command with a filename. For example, \begin{verbatim} )spool integrate.out \end{verbatim} To stop spooling, issue {\tt )spool} with no filename. If the filename is qualified with a directory, then the output will be placed in that directory. If no directory information is given, the spool file will be placed in the %-% \HDindex{directory!for spool files}{ugSysCmdspoolPage}{B.23.}{)spool} {\it current directory.} The current directory is the directory from which you started \Language{} or is the directory you specified using the {\tt )cd} command. %-% \HDsyscmdindex{cd}{ugSysCmdspoolPage}{B.23.}{)spool} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdcdTitle''}{ugSysCmdcdPage} in section \ugSysCmdcdNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdsynonymTitle}{)synonym} \newcommand{\ugSysCmdsynonymNumber}{B.24.} % % ===================================================================== \begin{page}{ugSysCmdsynonymPage}{B.24. )synonym} % ===================================================================== \beginscroll %-% \HDsyscmdindex{synonym}{ugSysCmdsynonymPage}{B.24.}{)synonym} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )synonym} \item{\tt )synonym} {\it synonym fullCommand} \item{\tt )what synonyms} \end{items} \par\noindent{\bf Command Description:} This command is used to create short synonyms for system command expressions. For example, the following synonyms might simplify commands you often use. \begin{verbatim} )synonym save history )save )synonym restore history )restore )synonym mail system mail )synonym ls system ls )synonym fortran set output fortran \end{verbatim} Once defined, synonyms can be used in place of the longer command expressions. Thus \begin{verbatim} )fortran on \end{verbatim} is the same as the longer \begin{verbatim} )set fortran output on \end{verbatim} To list all defined synonyms, issue either of \begin{verbatim} )synonyms )what synonyms \end{verbatim} To list, say, all synonyms that contain the substring ``{\tt ap}'', issue \begin{verbatim} )what synonyms ap \end{verbatim} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdwhatTitle''}{ugSysCmdwhatPage} in section \ugSysCmdwhatNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdsystemTitle}{)system} \newcommand{\ugSysCmdsystemNumber}{B.25.} % % ===================================================================== \begin{page}{ugSysCmdsystemPage}{B.25. )system} % ===================================================================== \beginscroll %-% \HDsyscmdindex{system}{ugSysCmdsystemPage}{B.25.}{)system} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )system} {\it cmdExpression} \end{items} \par\noindent{\bf Command Description:} This command may be used to issue commands to the operating system while remaining in \Language{}. The {\it cmdExpression} is passed to the operating system for execution. To get an operating system shell, issue, for example, \spadcmd{)system sh}. When you enter the key combination, \texht{\fbox{\bf Ctrl}--\fbox{\bf D}}{{\bf Ctrl-D}} (pressing and holding the \texht{\fbox{\bf Ctrl}}{{\bf Ctrl}} key and then pressing the \texht{\fbox{\bf D}}{{\bf D}} key) the shell will terminate and you will return to \Language{}. We do not recommend this way of creating a shell because \Lisp{} may field some interrupts instead of the shell. If possible, use a shell running in another window. If you execute programs that misbehave you may not be able to return to \Language{}. If this happens, you may have no other choice than to restart \Language{} and restore the environment via {\tt )history )restore}, if possible. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber \downlink{``\ugSysCmdfinTitle''}{ugSysCmdfinPage} in section \ugSysCmdfinNumber \downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber \downlink{``\ugSysCmdpquitTitle''}{ugSysCmdpquitPage} in section \ugSysCmdpquitNumber \downlink{``\ugSysCmdquitTitle''}{ugSysCmdquitPage} in section \ugSysCmdquitNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdtraceTitle}{)trace} \newcommand{\ugSysCmdtraceNumber}{B.26.} % % ===================================================================== \begin{page}{ugSysCmdtracePage}{B.26. )trace} % ===================================================================== \beginscroll %-% \HDsyscmdindex{trace}{ugSysCmdtracePage}{B.26.}{)trace} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )trace} \item{\tt )trace )off} \item{\tt )trace} {\it function \lanb{}options\ranb{}} \item{\tt )trace} {\it constructor \lanb{}options\ranb{}} \item{\tt )trace} {\it domainOrPackage \lanb{}options\ranb{}} \end{items} % where options can be one or more of % \begin{items} \item{\tt )after} {\it S-expression} \item{\tt )before} {\it S-expression} \item{\tt )break after} \item{\tt )break before} \item{\tt )cond} {\it S-expression} \item{\tt )count} \item{\tt )count} {\it n} \item{\tt )depth} {\it n} \item{\tt )local} {\it op1 \lanb{}... opN\ranb{}} \item{\tt )nonquietly} \item{\tt )nt} \item{\tt )off} \item{\tt )only} {\it listOfDataToDisplay} \item{\tt )ops} \item{\tt )ops} {\it op1 \lanb{}... opN \ranb{}} \item{\tt )restore} \item{\tt )stats} \item{\tt )stats reset} \item{\tt )timer} \item{\tt )varbreak} \item{\tt )varbreak} {\it var1 \lanb{}... varN \ranb{}} \item{\tt )vars} \item{\tt )vars} {\it var1 \lanb{}... varN \ranb{}} \item{\tt )within} {\it executingFunction} \end{items} \par\noindent{\bf Command Description:} This command is used to trace the execution of functions that make up the \Language{} system, functions defined by users, and functions from the system library. Almost all options are available for each type of function but exceptions will be noted below. To list all functions, constructors, domains and packages that are traced, simply issue \begin{verbatim} )trace \end{verbatim} To untrace everything that is traced, issue \begin{verbatim} )trace )off \end{verbatim} When a function is traced, the default system action is to display the arguments to the function and the return value when the function is exited. Note that if a function is left via an action such as a {\tt THROW}, no return value will be displayed. Also, optimization of tail recursion may decrease the number of times a function is actually invoked and so may cause less trace information to be displayed. Other information can be displayed or collected when a function is traced and this is controlled by the various options. Most options will be of interest only to \Language{} system developers. If a domain or package is traced, the default action is to trace all functions exported. Individual interpreter, lisp or boot functions can be traced by listing their names after {\tt )trace}. Any options that are present must follow the functions to be traced. \begin{verbatim} )trace f \end{verbatim} traces the function {\tt f}. To untrace {\tt f}, issue \begin{verbatim} )trace f )off \end{verbatim} Note that if a function name contains a special character, it will be necessary to escape the character with an underscore % \begin{verbatim} )trace _/D_,1 \end{verbatim} % To trace all domains or packages that are or will be created from a particular constructor, give the constructor name or abbreviation after {\tt )trace}. % \begin{verbatim} )trace MATRIX )trace List Integer \end{verbatim} % The first command traces all domains currently instantiated with \spadtype{Matrix}. If additional domains are instantiated with this constructor (for example, if you have used \spadtype{Matrix(Integer)} and \spadtype{Matrix(Float)}), they will be automatically traced. The second command traces \spadtype{List(Integer)}. It is possible to trace individual functions in a domain or package. See the {\tt )ops} option below. The following are the general options for the {\tt )trace} command. %!! system command parser doesn't treat general s-expressions correctly, %!! I recommand not documenting )after )before and )cond \indent{0} \beginitems %\item[{\tt )after} {\it S-expression}] %causes the given \Lisp{} {\it S-expression} to be %executed after exiting the traced function. %\item[{\tt )before} {\it S-expression}] %causes the given \Lisp{} {\it S-expression} to be %executed before entering the traced function. \item[{\tt )break after}] causes a \Lisp{} break loop to be entered after exiting the traced function. \item[{\tt )break before}] causes a \Lisp{} break loop to be entered before entering the traced function. \item[{\tt )break}] is the same as \spadcmd{)break before}. %\item[{\tt )cond} {\it S-expression}] %causes trace information to be shown only if the given %\Lisp{} {\it S-expression} evaluates to non-NIL. For %example, the following command causes the system function %{\tt resolveTT} to be traced but to have the information %displayed only if the value of the variable %{\tt \$reportBottomUpFlag} is non-NIL. %\begin{verbatim} %)trace resolveTT )cond \_\$reportBottomUpFlag} %\end{verbatim} \item[{\tt )count}] causes the system to keep a count of the number of times the traced function is entered. The total can be displayed with {\tt )trace )stats} and cleared with {\tt )trace )stats reset}. \item[{\tt )count} {\it n}] causes information about the traced function to be displayed for the first {\it n} executions. After the \eth{\it n} execution, the function is untraced. \item[{\tt )depth} {\it n}] causes trace information to be shown for only {\it n} levels of recursion of the traced function. The command \begin{verbatim} )trace fib )depth 10 \end{verbatim} will cause the display of only 10 levels of trace information for the recursive execution of a user function \userfun{fib}. \item[{\tt )math}] causes the function arguments and return value to be displayed in the \Language{} monospace two-dimensional math format. \item[{\tt )nonquietly}] causes the display of additional messages when a function is traced. \item[{\tt )nt}] This suppresses all normal trace information. This option is useful if the {\tt )count} or {\tt )timer} options are used and you are interested in the statistics but not the function calling information. \item[{\tt )off}] causes untracing of all or specific functions. Without an argument, all functions, constructors, domains and packages are untraced. Otherwise, the given functions and other objects are untraced. To immediately retrace the untraced functions, issue {\tt )trace )restore}. \item[{\tt )only} {\it listOfDataToDisplay}] causes only specific trace information to be shown. The items are listed by using the following abbreviations: \indent{0} \beginitems \item[a] display all arguments \item[v] display return value \item[1] display first argument \item[2] display second argument \item[15] display the 15th argument, and so on \enditems \indent{0} \enditems \indent{0} \indent{0} \beginitems \item[{\tt )restore}] causes the last untraced functions to be retraced. If additional options are present, they are added to those previously in effect. \item[{\tt )stats}] causes the display of statistics collected by the use of the {\tt )count} and {\tt )timer} options. \item[{\tt )stats reset}] resets to 0 the statistics collected by the use of the {\tt )count} and {\tt )timer} options. \item[{\tt )timer}] causes the system to keep a count of execution times for the traced function. The total can be displayed with {\tt )trace )stats} and cleared with {\tt )trace )stats reset}. %!! only for lisp, boot, may not work in any case, recommend removing %\item[{\tt )varbreak}] %causes a \Lisp{} break loop to be entered after %the assignment to any variable in the traced function. \item[{\tt )varbreak} {\it var1 \lanb{}... varN\ranb{}}] causes a \Lisp{} break loop to be entered after the assignment to any of the listed variables in the traced function. \item[{\tt )vars}] causes the display of the value of any variable after it is assigned in the traced function. Note that library code must have been compiled (see \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in Section \ugSysCmdcompileNumber\ignore{ugSysCmdcompile}) using the {\tt )vartrace} option in order to support this option. \item[{\tt )vars} {\it var1 \lanb{}... varN\ranb{}}] causes the display of the value of any of the specified variables after they are assigned in the traced function. Note that library code must have been compiled (see \downlink{``\ugSysCmdcompileTitle''}{ugSysCmdcompilePage} in Section \ugSysCmdcompileNumber\ignore{ugSysCmdcompile}) using the {\tt )vartrace} option in order to support this option. \item[{\tt )within} {\it executingFunction}] causes the display of trace information only if the traced function is called when the given {\it executingFunction} is running. \enditems \indent{0} The following are the options for tracing constructors, domains and packages. \indent{0} \beginitems \item[{\tt )local} {\it \lanb{}op1 \lanb{}... opN\ranb{}\ranb{}}] causes local functions of the constructor to be traced. Note that to untrace an individual local function, you must use the fully qualified internal name, using the escape character \spadSyntax{\_} before the semicolon. \begin{verbatim} )trace FRAC )local )trace FRAC_;cancelGcd )off \end{verbatim} \item[{\tt )ops} {\it op1 \lanb{}... opN\ranb{}}] By default, all operations from a domain or package are traced when the domain or package is traced. This option allows you to specify that only particular operations should be traced. The command % \begin{verbatim} )trace Integer )ops min max _+ _- \end{verbatim} % traces four operations from the domain \spadtype{Integer}. Since {\tt +} and {\tt -} are special characters, it is necessary to escape them with an underscore. \enditems \indent{0} \par\noindent{\bf Also See:} \downlink{``\ugSysCmdbootTitle''}{ugSysCmdbootPage} in section \ugSysCmdbootNumber \downlink{``\ugSysCmdlispTitle''}{ugSysCmdlispPage} in section \ugSysCmdlispNumber \downlink{``\ugSysCmdltraceTitle''}{ugSysCmdltracePage} in section \ugSysCmdltraceNumber \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdundoTitle}{)undo} \newcommand{\ugSysCmdundoNumber}{B.27.} % % ===================================================================== \begin{page}{ugSysCmdundoPage}{B.27. )undo} % ===================================================================== \beginscroll %-% \HDsyscmdindex{undo}{ugSysCmdundoPage}{B.27.}{)undo} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )undo} \item{\tt )undo} {\it integer} \item{\tt )undo} {\it integer \lanb{}option\ranb{}} \item{\tt )undo} {\tt )redo} \end{items} % where {\it option} is one of % \begin{items} \item{\tt )after} \item{\tt )before} \end{items} \par\noindent{\bf Command Description:} This command is used to restore the state of the user environment to an earlier point in the interactive session. The argument of an {\tt )undo} is an integer which must designate some step number in the interactive session. \begin{verbatim} )undo n )undo n )after \end{verbatim} These commands return the state of the interactive environment to that immediately after step {\tt n}. If {\tt n} is a positive number, then {\tt n} refers to step nummber {\tt n}. If {\tt n} is a negative number, it refers to the \eth{\tt n} previous command (that is, undoes the effects of the last \smath{-n} commands). A {\tt )clear all} resets the {\tt )undo} facility. Otherwise, an {\tt )undo} undoes the effect of {\tt )clear} with options {\tt properties}, {\tt value}, and {\tt mode}, and that of a previous {\tt undo}. If any such system commands are given between steps \smath{n} and \smath{n + 1} (\smath{n > 0}), their effect is undone for {\tt )undo m} for any \texht{\smath{0 < m \leq n}.}{0 < m <= n}. The command {\tt )undo} is equivalent to {\tt )undo -1} (it undoes the effect of the previous user expression). The command {\tt )undo 0} undoes any of the above system commands issued since the last user expression. \begin{verbatim} )undo n )before \end{verbatim} This command returns the state of the interactive environment to that immediately before step {\tt n}. Any {\tt )undo} or {\tt )clear} system commands given before step {\tt n} will not be undone. \begin{verbatim} )undo )redo \end{verbatim} This command reads the file {\tt redo.input}. created by the last {\tt )undo} command. This file consists of all user input lines, excluding those backtracked over due to a previous {\tt )undo}. \par\noindent{\bf Also See:} \downlink{``\ugSysCmdhistoryTitle''}{ugSysCmdhistoryPage} in section \ugSysCmdhistoryNumber The command {\tt )history )write} will eliminate the ``undone'' command lines of your program. \endscroll \autobuttons \end{page} % % \newcommand{\ugSysCmdwhatTitle}{)what} \newcommand{\ugSysCmdwhatNumber}{B.28.} % % ===================================================================== \begin{page}{ugSysCmdwhatPage}{B.28. )what} % ===================================================================== \beginscroll %-% \HDsyscmdindex{what}{ugSysCmdwhatPage}{B.28.}{)what} \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{items} \item{\tt )what categories} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what commands } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what domains } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what operations} {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what packages } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what synonym } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )what things } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \item{\tt )apropos } {\it pattern1} \lanb{}{\it pattern2 ...\ranb{}} \end{items} \par\noindent{\bf Command Description:} This command is used to display lists of things in the system. The patterns are all strings and, if present, restrict the contents of the lists. Only those items that contain one or more of the strings as substrings are displayed. For example, \begin{verbatim} )what synonym \end{verbatim} displays all command synonyms, \begin{verbatim} )what synonym ver \end{verbatim} displays all command synonyms containing the substring ``{\tt ver}'', \begin{verbatim} )what synonym ver pr \end{verbatim} displays all command synonyms containing the substring ``{\tt ver}'' or the substring ``{\tt pr}''. Output similar to the following will be displayed \begin{verbatim} ---------------- System Command Synonyms ----------------- user-defined synonyms satisfying patterns: ver pr )apr ........................... )what things )apropos ....................... )what things )prompt ........................ )set message prompt )version ....................... )lisp *yearweek* \end{verbatim} Several other things can be listed with the {\tt )what} command: \indent{0} \beginitems \item[{\tt categories}] displays a list of category constructors. %-% \HDsyscmdindex{what categories}{ugSysCmdwhatPage}{B.28.}{)what} \item[{\tt commands}] displays a list of system commands available at your user-level. %-% \HDsyscmdindex{what commands}{ugSysCmdwhatPage}{B.28.}{)what} Your user-level %-% \HDindex{user-level}{ugSysCmdwhatPage}{B.28.}{)what} is set via the {\tt )set userlevel} command. %-% \HDsyscmdindex{set userlevel}{ugSysCmdwhatPage}{B.28.}{)what} To get a description of a particular command, such as ``{\tt )what}'', issue {\tt )help what}. \item[{\tt domains}] displays a list of domain constructors. %-% \HDsyscmdindex{what domains}{ugSysCmdwhatPage}{B.28.}{)what} \item[{\tt operations}] displays a list of operations in the system library. %-% \HDsyscmdindex{what operations}{ugSysCmdwhatPage}{B.28.}{)what} It is recommended that you qualify this command with one or more patterns, as there are thousands of operations available. For example, say you are looking for functions that involve computation of eigenvalues. To find their names, try {\tt )what operations eig}. A rather large list of operations is loaded into the workspace when this command is first issued. This list will be deleted when you clear the workspace via {\tt )clear all} or {\tt )clear completely}. It will be re-created if it is needed again. \item[{\tt packages}] displays a list of package constructors. %-% \HDsyscmdindex{what packages}{ugSysCmdwhatPage}{B.28.}{)what} \item[{\tt synonym}] lists system command synonyms. %-% \HDsyscmdindex{what synonym}{ugSysCmdwhatPage}{B.28.}{)what} \item[{\tt things}] displays all of the above types for items containing %-% \HDsyscmdindex{what things}{ugSysCmdwhatPage}{B.28.}{)what} the pattern strings as substrings. The command synonym {\tt )apropos} is equivalent to %-% \HDsyscmdindex{apropos}{ugSysCmdwhatPage}{B.28.}{)what} {\tt )what things}. \enditems \indent{0} \par\noindent{\bf Also See:} \downlink{``\ugSysCmddisplayTitle''}{ugSysCmddisplayPage} in section \ugSysCmddisplayNumber \downlink{``\ugSysCmdsetTitle''}{ugSysCmdsetPage} in section \ugSysCmdsetNumber \downlink{``\ugSysCmdshowTitle''}{ugSysCmdshowPage} in section \ugSysCmdshowNumber \texht{\egroup}{} \endscroll \autobuttons \end{page} %