diff --git a/books/bookvol0.pamphlet b/books/bookvol0.pamphlet index 2e0d1a6..ff543ff 100644 --- a/books/bookvol0.pamphlet +++ b/books/bookvol0.pamphlet @@ -64076,56 +64076,11 @@ this has the same syntax as the operating system {\tt cd} command. {\tt )read} \index{ugSysCmdread}, and {\tt )spool} \index{ugSysCmdspool}. -\section{)close} -\index{ugSysCmdclose} - -\index{close} - - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )close} -\item{\tt )close )quietly} -\end{list} -\par\noindent{\bf Command Description:} - -This command is used to close down interpreter client processes. -Such processes are started by HyperDoc to run Axiom 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 Axiom prompt in the window. - -If you try to close down the last remaining interpreter client -process, Axiom will offer to close down the entire Axiom -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 ``{\tt y}'' (followed by the Return key) if this is what you had in mind. -Type ``{\tt n}'' (followed by the Return key) to cancel the command. - -You can use the {\tt )quietly} option to force Axiom to -close down the interpreter client process without closing down -the entire Axiom session. - -\par\noindent{\bf Also See:} -{\tt )quit} \index{ugSysCmdquit} and -{\tt )pquit} \index{ugSysCmdpquit}. - - - \section{)clear} \index{ugSysCmdclear} \index{clear} - \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} @@ -64208,6 +64163,47 @@ system function and constructor caches. {\tt )history} \index{ugSysCmdhistory}, and {\tt )undo} \index{ugSysCmdundo}. +\section{)close} +\index{ugSysCmdclose} + +\index{close} + + +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )close} +\item{\tt )close )quietly} +\end{list} +\par\noindent{\bf Command Description:} + +This command is used to close down interpreter client processes. +Such processes are started by HyperDoc to run Axiom 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 Axiom prompt in the window. + +If you try to close down the last remaining interpreter client +process, Axiom will offer to close down the entire Axiom +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 ``{\tt y}'' (followed by the Return key) if this is what you had in mind. +Type ``{\tt n}'' (followed by the Return key) to cancel the command. + +You can use the {\tt )quietly} option to force Axiom to +close down the interpreter client process without closing down +the entire Axiom session. + +\par\noindent{\bf Also See:} +{\tt )quit} \index{ugSysCmdquit} and +{\tt )pquit} \index{ugSysCmdpquit}. \section{)compile} \label{ugSysCmdcompile} @@ -64215,7 +64211,6 @@ system function and constructor caches. \index{compile} - \par\noindent{\bf User Level Required:} compiler \par\noindent{\bf Command Syntax:} @@ -64333,8 +64328,68 @@ variable then controls what happens. {\tt )edit} \index{ugSysCmdedit}, and {\tt )library} \index{ugSysCmdlibrary}. +\section{)copyright} +\index{copyright} + +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )copyright} +\end{list} +\par\noindent{\bf Command Description:} + +This command will show the text of the various licenses used +within the Axiom system. + +\section{)credits} +\index{credits} -%Original Page 577 +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )credits} +\end{list} +\par\noindent{\bf Command Description:} + +This command will show the list of names of people who have +contributed to Axiom. + +\section{)describe} +\index{credits} + +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )describe categoryName} +\item{\tt )describe domainName} +\item{\tt )describe packageName} +\end{list} +\par\noindent{\bf Command Description:} + +Given a categoryName, domainName, or a packageName it writes +some descriptive information to the console stream. For example, +\begin{verbatim} +)describe Set +A set over a domain D models the usual mathematical notion of a +finite set of elements from D. Sets are unordered collections of +distinct elements (that is, order and duplication does not matter). +The notation set [a,b,c] can be used to create a set and the usual +operations such as union and intersection are available to form new +sets. In our implementation, Language maintains the entries in sorted +order. Specifically, the parts function returns the entries as a list +in ascending order and the extract operation returns the maximum +entry. Given two sets s and t where #s = m and #t = n, the complexity +of + s = t is O(min(n,m)) + s < t is O(max(n,m)) + union(s,t), intersect(s,t), minus(s,t), + member(x,t) is O(n log n) + + insert(x,t) and remove(x,t) is O(n) +\end{verbatim} \section{)display} \index{ugSysCmddisplay} @@ -64972,289 +65027,99 @@ command may be used to drop out of Axiom into Common Lisp. {\tt )boot} \index{ugSysCmdboot}, and {\tt )fin} \index{ugSysCmdfin}. -\section{)regress} -\index{regress} +\section{)ltrace} +\label{ugSysCmdtrace} +\label{ugSysCmdltrace} +\index{ugSysCmdltrace} + +\index{ltrace} + \par\noindent{\bf User Level Required:} development + \par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )regress} {\it filename} -\item {\tt )regress} {\it filename.output} -\item {\tt )regress} {\it /path/filename} -\item {\tt )regress} {\it /pathfilename.output} -\end{list} -\par\noindent{\bf Command Description:} +This command has the same arguments as options as the +{\tt )trace} command. -\begin{verbatim} -The regress command will run the regress function that was compiled -as part of the lisp image build process. This function expects an -input filename, possibly containing a path prefix. +\par\noindent{\bf Command Description:} -If the filename contains a period then we consider it a fully formed -filename, otherwise we append ``.output'', which is the default file -extension. +This command is used by Axiom system developers to trace +Common Lisp functions. It is not supported for general use. - )regress matrix - )regress matrix.output - )regress /path/to/file/matrix - )regress /path/to/file/matrix.output - -will test the contents of the file matrix.output. +\par\noindent{\bf Also See:} +{\tt )boot} \index{ugSysCmdboot}, +{\tt )lisp} \index{ugSysCmdlisp}, and +{\tt )trace} \index{ugSysCmdtrace}. -The idea behind regression testing is to check that the results -we currently get match the results we used to get. In order to -do that we create input files with a special comment format that -contains the prior results. These are easy to create as all you -need to do is run the Axiom function, capture the results, and -turn them input specially formed comments using the -- comment. +\section{)pquit} +\index{ugSysCmdpquit} -A regression file caches the result of an Axiom function so we -can automate the testing process. It is a file of many tests, -each with their own output. +\index{pquit} -The regression file format uses the Axiom -- comment syntax to keep -a copy of the expected output from an Axiom command. This expected -output is compared character by character against the actual output. -The regression file is broken into numbered blocks, delimited by -a --S for the beginning and a --E for the end. The total number of -blocks is also given so missing or failed tests also raise an error. +\par\noindent{\bf User Level Required:} interpreter -There are 4 special kinds of -- comments in regression files: +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )pquit} +\end{list} - --S n of M this is test n of M tests in this file - --E n this marks the end of test n - --R any output this marks the actual expected output line - --I any output this line is compared but ignored +\par\noindent{\bf Command Description:} -A regression test file looks like: +This command is used to terminate Axiom 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 Axiom in the same state. - )set break resume - )spool foo.output - )set message type off - )clear all +{\tt )pquit} differs from the {\tt )quit} in that it always asks for +confirmation that you want to terminate Axiom (the ``p'' is for +``protected''). +\index{quit} +When you enter the {\tt )pquit} command, Axiom responds +% +\begin{center} +Please enter {\bf y} or {\bf yes} if you really want to +leave the interactive \\ +environment and return to the operating system: +\end{center} +% +If you respond with {\tt y} or {\tt yes}, you will see the message +% +\begin{center} +You are now leaving the Axiom interactive environment. \\ +Issue the command {\bf axiom} to the operating system to start a new session. +\end{center} +% +and Axiom 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 +% +\begin{center} +You have chosen to remain in the Axiom interactive environment. +\end{center} +% +will be displayed and, indeed, Axiom would still be running. - --S 1 of 3 - 2+3 - --R this is the exact Axiom output - --R (1) 5 - --E 1 +\par\noindent{\bf Also See:} +{\tt )fin} \index{ugSysCmdfin}, +{\tt )history} \index{ugSysCmdhistory}, +{\tt )close} \index{ugSysCmdclose}, +{\tt )quit} \index{ugSysCmdquit}, and +{\tt )system} \index{ugSysCmdsystem}. - --S 2 of 3 - 2+3 - --R this should fail to match - --R (2) 7 - --E 2 - --S 3 of 3 - 2+3 - --R this fails to match but we - --I (3) 7 use --I to ignore this line - --E 3 +%Original Page 585 -We can now run this file with +\section{)quit} +\index{ugSysCmdquit} - )read foo.input +\index{quit} -Note that when this file is run it will create a spool file called -"foo.output" because of the lines: - - )spool foo.output - )spool -The "foo.output" file contains the console image of the result. -It will look like: - - Starts dribbling to foo.output (2012/2/28, 12:25:7). - )set message type off - )clear all - - --S 1 of 3 - 2+3 - - (1) 5 - --R - --R (1) 5 - --E 1 - - --S 2 of 3 - 2+3 - - (2) 5 - --R - --R (2) 7 - --E 2 - - --S 3 of 3 - 2+3 - - (3) 5 - --R - --I (3) 7 - --E 3 - - )spool - -This "foo.output" file can now be checked using the )regress command. - -When we run the )regress foo.output we see; - - testing foo - passed foo 1 of 3 - MISMATCH - expected:" (2) 7" - got:" (2) 5" - FAILED foo 2 of 2 - passed foo 3 of 3 - regression result FAILED 1 of 3 stanzas file foo - -Tests either pass or fail. A passing test generates the message: - - passed foo 1 of 3 - -A failing test will give a reversed printout of the expected vs -actual output as well as a FAILED message, as in: - - MISMATCH - expected:" (2) 7" - got:" (2) 5" - FAILED foo 2 of 3 - -The last line of output is a summary: - - regression result FAILED 1 of 3 stanzas file foo - -\end{verbatim} - -\par\noindent{\bf Also See:} -{\tt )tangle} - -\section{)tangle} -\index{ugSysCmdboot} -\index{tangle} -\par\noindent{\bf User Level Required:} development -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )tangle} {\it filename} -\item {\tt )tangle} {\it filename.output} -\item {\tt )tangle} {\it /path/filename} -\item {\tt )tangle} {\it /pathfilename.output} -\end{list} - -\par\noindent{\bf Command Description:} - -\begin{verbatim} -This command is used to tangle pamphlet files. - -)tangle matrix.input.pamphlet - -will tangle the contents of the file matrix.input.pamphlet into -matrix.input. The ``.input.pamphlet'' is optional. - -\end{verbatim} - -\par\noindent{\bf Also See:} -{\tt )regress} - -%Original Page 584 - -\section{)trace} -\label{ugSysCmdtrace} -\label{ugSysCmdltrace} -\index{ugSysCmdltrace} - -\index{ltrace} - - -\par\noindent{\bf User Level Required:} development - -\par\noindent{\bf Command Syntax:} - -This command has the same arguments as options as the -{\tt )trace} command. - -\par\noindent{\bf Command Description:} - -This command is used by Axiom system developers to trace -Common Lisp or -BOOT functions. -It is not supported for general use. - -\par\noindent{\bf Also See:} -{\tt )boot} \index{ugSysCmdboot}, -{\tt )lisp} \index{ugSysCmdlisp}, and -{\tt )trace} \index{ugSysCmdtrace}. - - -\section{)pquit} -\index{ugSysCmdpquit} - -\index{pquit} - - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )pquit} -\end{list} - -\par\noindent{\bf Command Description:} - -This command is used to terminate Axiom 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 Axiom in the same state. - -{\tt )pquit} differs from the {\tt )quit} in that it always asks for -confirmation that you want to terminate Axiom (the ``p'' is for -``protected''). -\index{quit} -When you enter the {\tt )pquit} command, Axiom responds -% -\begin{center} -Please enter {\bf y} or {\bf yes} if you really want to -leave the interactive \\ -environment and return to the operating system: -\end{center} -% -If you respond with {\tt y} or {\tt yes}, you will see the message -% -\begin{center} -You are now leaving the Axiom interactive environment. \\ -Issue the command {\bf axiom} to the operating system to start a new session. -\end{center} -% -and Axiom 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 -% -\begin{center} -You have chosen to remain in the Axiom interactive environment. -\end{center} -% -will be displayed and, indeed, Axiom would still be running. - -\par\noindent{\bf Also See:} -{\tt )fin} \index{ugSysCmdfin}, -{\tt )history} \index{ugSysCmdhistory}, -{\tt )close} \index{ugSysCmdclose}, -{\tt )quit} \index{ugSysCmdquit}, and -{\tt )system} \index{ugSysCmdsystem}. - - -%Original Page 585 - -\section{)quit} -\index{ugSysCmdquit} - -\index{quit} - - -\par\noindent{\bf User Level Required:} interpreter +\par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} \begin{list}{} @@ -65307,7 +65172,6 @@ executed when you press, say, a function key. \index{read} - \par\noindent{\bf User Level Required:} interpreter \par\noindent{\bf Command Syntax:} @@ -65348,6 +65212,190 @@ The {\tt )quiet} option suppresses output while the file is being read. %Original Page 586 +\section{)regress} +\index{regress} +\par\noindent{\bf User Level Required:} development +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item {\tt )regress} {\it filename} +\item {\tt )regress} {\it filename.output} +\item {\tt )regress} {\it /path/filename} +\item {\tt )regress} {\it /pathfilename.output} +\end{list} + +\par\noindent{\bf Command Description:} + +\begin{verbatim} +The regress command will run the regress function that was compiled +as part of the lisp image build process. This function expects an +input filename, possibly containing a path prefix. + +If the filename contains a period then we consider it a fully formed +filename, otherwise we append ``.output'', which is the default file +extension. + + )regress matrix + )regress matrix.output + )regress /path/to/file/matrix + )regress /path/to/file/matrix.output + +will test the contents of the file matrix.output. + +The idea behind regression testing is to check that the results +we currently get match the results we used to get. In order to +do that we create input files with a special comment format that +contains the prior results. These are easy to create as all you +need to do is run the Axiom function, capture the results, and +turn them input specially formed comments using the -- comment. + +A regression file caches the result of an Axiom function so we +can automate the testing process. It is a file of many tests, +each with their own output. + +The regression file format uses the Axiom -- comment syntax to keep +a copy of the expected output from an Axiom command. This expected +output is compared character by character against the actual output. + +The regression file is broken into numbered blocks, delimited by +a --S for the beginning and a --E for the end. The total number of +blocks is also given so missing or failed tests also raise an error. + +There are 4 special kinds of -- comments in regression files: + + --S n of M this is test n of M tests in this file + --E n this marks the end of test n + --R any output this marks the actual expected output line + --I any output this line is compared but ignored + +A regression test file looks like: + + )set break resume + )spool foo.output + )set message type off + )clear all + + --S 1 of 3 + 2+3 + --R this is the exact Axiom output + --R (1) 5 + --E 1 + + --S 2 of 3 + 2+3 + --R this should fail to match + --R (2) 7 + --E 2 + + --S 3 of 3 + 2+3 + --R this fails to match but we + --I (3) 7 use --I to ignore this line + --E 3 + +We can now run this file with + + )read foo.input + +Note that when this file is run it will create a spool file called +"foo.output" because of the lines: + + )spool foo.output + )spool + +The "foo.output" file contains the console image of the result. +It will look like: + + Starts dribbling to foo.output (2012/2/28, 12:25:7). + )set message type off + )clear all + + --S 1 of 3 + 2+3 + + (1) 5 + --R + --R (1) 5 + --E 1 + + --S 2 of 3 + 2+3 + + (2) 5 + --R + --R (2) 7 + --E 2 + + --S 3 of 3 + 2+3 + + (3) 5 + --R + --I (3) 7 + --E 3 + + )spool + +This "foo.output" file can now be checked using the )regress command. + +When we run the )regress foo.output we see; + + testing foo + passed foo 1 of 3 + MISMATCH + expected:" (2) 7" + got:" (2) 5" + FAILED foo 2 of 2 + passed foo 3 of 3 + regression result FAILED 1 of 3 stanzas file foo + +Tests either pass or fail. A passing test generates the message: + + passed foo 1 of 3 + +A failing test will give a reversed printout of the expected vs +actual output as well as a FAILED message, as in: + + MISMATCH + expected:" (2) 7" + got:" (2) 5" + FAILED foo 2 of 3 + +The last line of output is a summary: + + regression result FAILED 1 of 3 stanzas file foo + +\end{verbatim} + +\par\noindent{\bf Also See:} +{\tt )tangle} + +\section{)savesystem} +\index{savesystem} + +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )savesystem {\sl filename}} +\end{list} +\par\noindent{\bf Command Description:} + +This command will save the current Axiom session including +currently set variables into an executable file under the given +filename. For instance, + +\begin{verbatim} + axiom + (1) -> t1:=4 + (1) -> )savesystem foo +\end{verbatim} +and Axiom exits. Then do +\begin{verbatim} + ./foo + (1) -> t1 + 4 +\end{verbatim} + \section{)set} \label{ugSysCmdset} \index{ugSysCmdset} @@ -65522,6 +65570,56 @@ Axiom or is the directory you specified using the {\tt )cd} \index{ugSysCmdcd}. +\section{)summary} +\index{summary} + +\par\noindent{\bf User Level Required:} interpreter + +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item{\tt )summary} +\end{list} +\par\noindent{\bf Command Description:} + +\begin{verbatim} + )credits : list the people who have contributed to Axiom + + )help gives more information + )quit : exit AXIOM + + )abbreviation : query, set and remove abbreviations for constructors + )browse : start an Axiom http server on 127.0.0.1 port 8085 + )cd : set working directory + )clear : remove declarations, definitions or values + )close : throw away an interpreter client and workspace + )compile : invoke constructor compiler + )copyright : show copyright and trademark information + )describe : show database information for a category, domain, or package + )display : display Library operations and objects in your workspace + )edit : edit a file + )fin : drop into lisp, use (restart) to return to the session + )frame : manage interpreter workspaces + )history : manage aspects of interactive session + )include : insert a file into a .input file + )library : introduce new constructors + )lisp : evaluate a LISP expression + )ltrace : trace functions + )pquit : ask if you really want to exit Axiom + )quit : exit Axiom + )read : execute AXIOM commands from a file + )regress : regression test an output spool file + )savesystem : save LISP image to a file + )set : view and set system variables + )show : show constructor information + )spool : log input and output to a file + )synonym : define an abbreviation for system commands + )system : issue shell commands + )tangle : extract chunks from a literate program to an input file + )trace : trace execution of functions + )undo : restore workspace to earlier state + )what : search for various things by name +\end{verbatim} + \section{)synonym} \index{ugSysCmdsynonym} @@ -65624,6 +65722,63 @@ possible. %Original Page 590 +\section{)tangle} +\index{ugSysCmdboot} +\index{tangle} +\par\noindent{\bf User Level Required:} development +\par\noindent{\bf Command Syntax:} +\begin{list}{} +\item {\tt )tangle} {\it filename} +\item {\tt )tangle} {\it filename.output} +\item {\tt )tangle} {\it /path/filename} +\item {\tt )tangle} {\it /pathfilename.output} +\end{list} + +\par\noindent{\bf Command Description:} + +\begin{verbatim} +This command is used to tangle pamphlet files. + +)tangle matrix.input.pamphlet + +will tangle the contents of the file matrix.input.pamphlet into +matrix.input. The ``.input.pamphlet'' is optional. + +\end{verbatim} + +\par\noindent{\bf Also See:} +{\tt )regress} + +%Original Page 584 + +\section{)trace} +\label{ugSysCmdtrace} +\label{ugSysCmdltrace} +\index{ugSysCmdltrace} + +\index{ltrace} + + +\par\noindent{\bf User Level Required:} development + +\par\noindent{\bf Command Syntax:} + +This command has the same arguments as options as the +{\tt )trace} command. + +\par\noindent{\bf Command Description:} + +This command is used by Axiom system developers to trace +Common Lisp or +BOOT functions. +It is not supported for general use. + +\par\noindent{\bf Also See:} +{\tt )boot} \index{ugSysCmdboot}, +{\tt )lisp} \index{ugSysCmdlisp}, and +{\tt )trace} \index{ugSysCmdtrace}. + + \section{)trace} \index{ugSysCmdtrace}