@@ -1,299 +1,299 @@ -\section{General Commands} - -\begin{Command}{BYE} -The \name{bye} command ends the REDUCE session, returning control to the -program (e.g., the operating system) that called REDUCE. When you are at -the top level, the \name{bye} command exits REDUCE. \name{quit} is a -synonym for \name{bye}. - -\end{Command} - -\begin{Command}{CONT} -The command \name{cont} returns control to an interactive file after a -\nameref{pause} command that has been answered with \name{n}. - -\begin{Examples} -\explanation{Suppose you are in the middle of an interactive file.} \\ - & factorize(x**2 + 17*x + 60); \\ - & \{X + 5,X + 12\} \\ - pause; & Cont? (Y or N) \\ -n \\ -saveas results; \\ -factor1 := first results; & FACTOR1 := X + 5 \\ -factor2 := second results; & FACTOR2 := X + 12 \\ -cont; & \explanationo{\em the file resumes} -\end{Examples} - -\begin{Comments} -A \nameref{pause} allows you to enter your own REDUCE commands, change -switch values, inquire about results, or other such activities. When you -wish to resume operation of the interactive file, use \name{cont}. - -\end{Comments} -\end{Command} - - -\begin{Command}{DISPLAY} -\index{history}\index{interactive} -When given a numeric argument \meta{n}, \name{display} prints the \meta{n} -most recent input statements, identified by prompt numbers. If an empty -pair of parentheses is given, or if \meta{n} is greater than the current -number of statements, all the input statements since the beginning of -the session are printed. -%%%INCONSISTENT??? {\em or} - -\begin{Syntax} -\name{display}\(\meta{n}\) {\em or} \name{display}\(\) -\end{Syntax} - -\meta{n} should be a positive integer. However, if it is a real number, the -truncated integer value is used, and if a non-numeric argument is used, all -the input statements are printed. - -\begin{Comments} -The statements are displayed in upper case, with lines split at semicolons or -dollar signs, as they are in editing. If long files have been input during -the session, the \name{display} command is slow to format these for -printing. -\end{Comments} -\end{Command} - - -\begin{Command}{LOAD\_PACKAGE} -\index{package} -The \name{load\_package} command is used to load REDUCE packages, such as -\name{gentran} that are not automatically loaded by the system. -\begin{Syntax} -\name{load\_package "}\meta{package\_name}\name{"} -\end{Syntax} - -%%% We should probably list the names of the packages here. -A package is only loaded once; subsequent calls of \name{load\_package} -for the same package name are ignored. -\end{Command} - - -\begin{Command}{PAUSE} -\index{interactive} -The \name{pause} command, given in an interactive file, stops operation and -asks if you want to continue or not. - -\begin{Examples} -\explanation{An interactive file is running, and at some point you see the -question} \\ - Cont? (Y or N) \\ -\explanation{If you type} \\ -y\key{Return}\\ -\explanation{the file continues to run until the next pause or the end.} \\ -\explanation{If you type } \\ -n\key{Return} \\ -\explanation{you will get a numbered REDUCE prompt, and be allowed to -enter and execute any REDUCE statements. If you later wish to continue with -the file, type} \\ -cont; \\ -\explanation{and the file resumes.} -\end{Examples} - -To use \name{pause} in your own interactive files, type - -\name{pause;} - - -in the file wherever you want it. - - -\begin{Comments} -\name{pause} does not allow you to continue without typing either \name{y} -or \name{n}. Its use is to slow down scrolling of interactive files, or to -let you change parameters or switch settings for the calculations. - -If you have stopped an interactive file at a \name{pause,} and do not wish to -resume the file, type \name{end;}. This does not end the REDUCE session, but -stops input from the file. A second \name{end;} ends the REDUCE session. -However, if you have pauses from more than one file stacked up, an \name{end;} -brings you back to the top level, not the file directly above. - -A \name{pause} typed from the terminal has no effect. -\end{Comments} -\end{Command} - - -\begin{Command}{QUIT} -The \name{quit} command ends the REDUCE session, returning control to the -program (e.g., the operating system) that called REDUCE. When you are at -the top level, the \name{quit} command exits REDUCE. \nameref{bye} is a -synonym for \name{quit}. - -\end{Command} - - -\begin{Operator}{RECLAIM} -\index{memory} -\begin{Comments} -REDUCE's memory is in a storage structure called a heap. As REDUCE -statements execute, chunks of memory are used up. When these chunks are no -longer needed, they remain idle. When the memory is almost full, -the system executes a garbage collection, reclaiming space that is no -longer needed, and putting all the free space at one end. Depending on -the size of the image REDUCE is using, -garbage collection needs to be done more or less often. A -larger image means fewer but longer garbage collections. -Regardless of memory size, -if you ask REDUCE to do something ridiculous, like \name{factorial(2000)}, it may -garbage collect many times. -\end{Comments} -\end{Operator} - - -\begin{Command}{REDERR} -\index{error handling} -The \name{rederr} command allows you to print an error message from inside -a \nameref{procedure} or a \nameref{block} statement. -The calculation is gracefully terminated. -\begin{Syntax} -\name{rederr} \meta{message} -\end{Syntax} - -\meta{message} is an error message, usually inside double quotation marks -(a \nameref{string}). - -\begin{Examples} -\begin{multilineinput} -procedure fac(n); - if not (fixp(n) and n>=0) - then rederr "Choose nonneg. integer only" - else for i := 0:n-1 product i+1; -\end{multilineinput} & -fac \\ -fac a; & - ***** Choose nonneg. integer only \\ -fac 5; & 120 -\end{Examples} -\begin{Comments} -The above procedure finds the factorial of its argument. -If n is not a positive integer or 0, an error message is returned. - -If your procedure is executed in a file, the usual error message is -printed, followed by \name{Cont? (Y or N)}, just as any other error does from -a file. Although the procedure is gracefully terminated, any switch settings or -variable assignments you made before the error occurred are not undone. If you -need to clean up such items before exiting, use a group statement, with the -\name{rederr} command as its last statement. -\end{Comments} -\end{Command} - - -\begin{Command}{RETRY} -\index{interactive} -The \name{retry} command allows you to retry the latest statement that resulted -in an error message. - -\begin{Examples} -matrix a; \\ -det a; & ***** Matrix A not set \\ -a := mat((1,2),(3,4)); & \begin{multilineoutput}{6cm} -A(1,1) := 1 -A(1,2) := 2 -A(2,1) := 3 -A(2,2) := 4 -\end{multilineoutput}\\ -retry; & -2 -\end{Examples} -\begin{Comments} -\name{retry} remembers only the most recent statement that resulted in an -error message. It allows you to stop and fix something obvious, then -continue on your way without retyping the original command. -\end{Comments} -\end{Command} - - -\begin{Command}{SAVEAS} -The \name{saveas} command saves the current workspace under the name of its -argument. -\begin{Syntax} -\name{saveas} \meta{identifier} -\end{Syntax} - -\meta{identifier} can be any valid REDUCE identifier. - -\begin{Examples} - -\explanation{(The numbered prompts are shown below, unlike in most examples)}\\ -1: solve(x^2-3);& -\{x=sqrt(3),x= - sqrt(3)\}\\ -2: saveas rts(0)\$\\ -3: rts(0);& -\{x=sqrt(3),x= - sqrt(3)\}\\ -\end{Examples} -\begin{Comments} -\name{saveas} works only for the current workspace, the last algebraic -expression produced by REDUCE. This allows you to save a result that you -did not assign to an identifier when you originally typed the input. -For access to previous output use \nameref{ws}. -\end{Comments} -\end{Command} - - -\begin{Command}{SHOWTIME} -\index{time} -The \name{showtime} command prints the elapsed system time since the last -call of this command or since the beginning of the session, if it has not -been called before. - - -\begin{Examples} -showtime; & Time: 1020 ms \\ -factorize(x^4 - 8x^4 + 8x^2 - 136x - 153); - & \{X - 9,X^{2} + 17,X + 1\} \\ -showtime; & Time: 920 ms -\end{Examples} -\begin{Comments} -The time printed is either the elapsed cpu time or the elapsed wall clock -time, depending on your system. \name{showtime} allows you to see the -system time resources REDUCE uses in its calculations. Your time readings -will of course vary from this example according to the system you use. -\end{Comments} -\end{Command} - - -\begin{Command}{WRITE} -\index{output} -The \name{write} command explicitly writes its arguments to the output device -(terminal or file). -\begin{Syntax} -\name{write} \meta{item}\{,\meta{item}\}\optional -\end{Syntax} - - -\meta{item} can be an expression, an assignment or a \nameref{string} -enclosed in double quotation marks (\name{"}). - -\begin{Examples} -write a, sin x, "this is a string"; & ASIN(X)this is a string \\ -write a," ",sin x," this is a string"; & A SIN(X) this is a string \\ -if not numberp(a) then write "the symbol ",a; - & the symbol A \\ -array m(10); \\ -for i := 1:5 do write m(i) := 2*i; & -\begin{multilineoutput}{6cm} -M(1) := 2 -M(2) := 4 -M(3) := 6 -M(4) := 8 -M(5) := 10 -\end{multilineoutput}\\ -m(4); & 8 -\end{Examples} - -\begin{Comments} -The items specified by a single \name{write} statement print on a single line -unless they are too long. A printed line is always ended with a carriage -return, so the next item printed starts a new line. - -When an assignment statement is printed, the assignment is also made. This -allows you to get feedback on filling slots in an array with a \nameref{for} - statement, as shown in the last example above. -\end{Comments} -\end{Command} - - +\section{General Commands} + +\begin{Command}{BYE} +The \name{bye} command ends the REDUCE session, returning control to the +program (e.g., the operating system) that called REDUCE. When you are at +the top level, the \name{bye} command exits REDUCE. \name{quit} is a +synonym for \name{bye}. + +\end{Command} + +\begin{Command}{CONT} +The command \name{cont} returns control to an interactive file after a +\nameref{pause} command that has been answered with \name{n}. + +\begin{Examples} +\explanation{Suppose you are in the middle of an interactive file.} \\ + & factorize(x**2 + 17*x + 60); \\ + & \{X + 5,X + 12\} \\ + pause; & Cont? (Y or N) \\ +n \\ +saveas results; \\ +factor1 := first results; & FACTOR1 := X + 5 \\ +factor2 := second results; & FACTOR2 := X + 12 \\ +cont; & \explanationo{\em the file resumes} +\end{Examples} + +\begin{Comments} +A \nameref{pause} allows you to enter your own REDUCE commands, change +switch values, inquire about results, or other such activities. When you +wish to resume operation of the interactive file, use \name{cont}. + +\end{Comments} +\end{Command} + + +\begin{Command}{DISPLAY} +\index{history}\index{interactive} +When given a numeric argument \meta{n}, \name{display} prints the \meta{n} +most recent input statements, identified by prompt numbers. If an empty +pair of parentheses is given, or if \meta{n} is greater than the current +number of statements, all the input statements since the beginning of +the session are printed. +%%%INCONSISTENT??? {\em or} + +\begin{Syntax} +\name{display}\(\meta{n}\) {\em or} \name{display}\(\) +\end{Syntax} + +\meta{n} should be a positive integer. However, if it is a real number, the +truncated integer value is used, and if a non-numeric argument is used, all +the input statements are printed. + +\begin{Comments} +The statements are displayed in upper case, with lines split at semicolons or +dollar signs, as they are in editing. If long files have been input during +the session, the \name{display} command is slow to format these for +printing. +\end{Comments} +\end{Command} + + +\begin{Command}{LOAD\_PACKAGE} +\index{package} +The \name{load\_package} command is used to load REDUCE packages, such as +\name{gentran} that are not automatically loaded by the system. +\begin{Syntax} +\name{load\_package "}\meta{package\_name}\name{"} +\end{Syntax} + +%%% We should probably list the names of the packages here. +A package is only loaded once; subsequent calls of \name{load\_package} +for the same package name are ignored. +\end{Command} + + +\begin{Command}{PAUSE} +\index{interactive} +The \name{pause} command, given in an interactive file, stops operation and +asks if you want to continue or not. + +\begin{Examples} +\explanation{An interactive file is running, and at some point you see the +question} \\ + Cont? (Y or N) \\ +\explanation{If you type} \\ +y\key{Return}\\ +\explanation{the file continues to run until the next pause or the end.} \\ +\explanation{If you type } \\ +n\key{Return} \\ +\explanation{you will get a numbered REDUCE prompt, and be allowed to +enter and execute any REDUCE statements. If you later wish to continue with +the file, type} \\ +cont; \\ +\explanation{and the file resumes.} +\end{Examples} + +To use \name{pause} in your own interactive files, type + +\name{pause;} + + +in the file wherever you want it. + + +\begin{Comments} +\name{pause} does not allow you to continue without typing either \name{y} +or \name{n}. Its use is to slow down scrolling of interactive files, or to +let you change parameters or switch settings for the calculations. + +If you have stopped an interactive file at a \name{pause,} and do not wish to +resume the file, type \name{end;}. This does not end the REDUCE session, but +stops input from the file. A second \name{end;} ends the REDUCE session. +However, if you have pauses from more than one file stacked up, an \name{end;} +brings you back to the top level, not the file directly above. + +A \name{pause} typed from the terminal has no effect. +\end{Comments} +\end{Command} + + +\begin{Command}{QUIT} +The \name{quit} command ends the REDUCE session, returning control to the +program (e.g., the operating system) that called REDUCE. When you are at +the top level, the \name{quit} command exits REDUCE. \nameref{bye} is a +synonym for \name{quit}. + +\end{Command} + + +\begin{Operator}{RECLAIM} +\index{memory} +\begin{Comments} +REDUCE's memory is in a storage structure called a heap. As REDUCE +statements execute, chunks of memory are used up. When these chunks are no +longer needed, they remain idle. When the memory is almost full, +the system executes a garbage collection, reclaiming space that is no +longer needed, and putting all the free space at one end. Depending on +the size of the image REDUCE is using, +garbage collection needs to be done more or less often. A +larger image means fewer but longer garbage collections. +Regardless of memory size, +if you ask REDUCE to do something ridiculous, like \name{factorial(2000)}, it may +garbage collect many times. +\end{Comments} +\end{Operator} + + +\begin{Command}{REDERR} +\index{error handling} +The \name{rederr} command allows you to print an error message from inside +a \nameref{procedure} or a \nameref{block} statement. +The calculation is gracefully terminated. +\begin{Syntax} +\name{rederr} \meta{message} +\end{Syntax} + +\meta{message} is an error message, usually inside double quotation marks +(a \nameref{string}). + +\begin{Examples} +\begin{multilineinput} +procedure fac(n); + if not (fixp(n) and n>=0) + then rederr "Choose nonneg. integer only" + else for i := 0:n-1 product i+1; +\end{multilineinput} & +fac \\ +fac a; & + ***** Choose nonneg. integer only \\ +fac 5; & 120 +\end{Examples} +\begin{Comments} +The above procedure finds the factorial of its argument. +If n is not a positive integer or 0, an error message is returned. + +If your procedure is executed in a file, the usual error message is +printed, followed by \name{Cont? (Y or N)}, just as any other error does from +a file. Although the procedure is gracefully terminated, any switch settings or +variable assignments you made before the error occurred are not undone. If you +need to clean up such items before exiting, use a group statement, with the +\name{rederr} command as its last statement. +\end{Comments} +\end{Command} + + +\begin{Command}{RETRY} +\index{interactive} +The \name{retry} command allows you to retry the latest statement that resulted +in an error message. + +\begin{Examples} +matrix a; \\ +det a; & ***** Matrix A not set \\ +a := mat((1,2),(3,4)); & \begin{multilineoutput}{6cm} +A(1,1) := 1 +A(1,2) := 2 +A(2,1) := 3 +A(2,2) := 4 +\end{multilineoutput}\\ +retry; & -2 +\end{Examples} +\begin{Comments} +\name{retry} remembers only the most recent statement that resulted in an +error message. It allows you to stop and fix something obvious, then +continue on your way without retyping the original command. +\end{Comments} +\end{Command} + + +\begin{Command}{SAVEAS} +The \name{saveas} command saves the current workspace under the name of its +argument. +\begin{Syntax} +\name{saveas} \meta{identifier} +\end{Syntax} + +\meta{identifier} can be any valid REDUCE identifier. + +\begin{Examples} + +\explanation{(The numbered prompts are shown below, unlike in most examples)}\\ +1: solve(x^2-3);& +\{x=sqrt(3),x= - sqrt(3)\}\\ +2: saveas rts(0)\$\\ +3: rts(0);& +\{x=sqrt(3),x= - sqrt(3)\}\\ +\end{Examples} +\begin{Comments} +\name{saveas} works only for the current workspace, the last algebraic +expression produced by REDUCE. This allows you to save a result that you +did not assign to an identifier when you originally typed the input. +For access to previous output use \nameref{ws}. +\end{Comments} +\end{Command} + + +\begin{Command}{SHOWTIME} +\index{time} +The \name{showtime} command prints the elapsed system time since the last +call of this command or since the beginning of the session, if it has not +been called before. + + +\begin{Examples} +showtime; & Time: 1020 ms \\ +factorize(x^4 - 8x^4 + 8x^2 - 136x - 153); + & \{X - 9,X^{2} + 17,X + 1\} \\ +showtime; & Time: 920 ms +\end{Examples} +\begin{Comments} +The time printed is either the elapsed cpu time or the elapsed wall clock +time, depending on your system. \name{showtime} allows you to see the +system time resources REDUCE uses in its calculations. Your time readings +will of course vary from this example according to the system you use. +\end{Comments} +\end{Command} + + +\begin{Command}{WRITE} +\index{output} +The \name{write} command explicitly writes its arguments to the output device +(terminal or file). +\begin{Syntax} +\name{write} \meta{item}\{,\meta{item}\}\optional +\end{Syntax} + + +\meta{item} can be an expression, an assignment or a \nameref{string} +enclosed in double quotation marks (\name{"}). + +\begin{Examples} +write a, sin x, "this is a string"; & ASIN(X)this is a string \\ +write a," ",sin x," this is a string"; & A SIN(X) this is a string \\ +if not numberp(a) then write "the symbol ",a; + & the symbol A \\ +array m(10); \\ +for i := 1:5 do write m(i) := 2*i; & +\begin{multilineoutput}{6cm} +M(1) := 2 +M(2) := 4 +M(3) := 6 +M(4) := 8 +M(5) := 10 +\end{multilineoutput}\\ +m(4); & 8 +\end{Examples} + +\begin{Comments} +The items specified by a single \name{write} statement print on a single line +unless they are too long. A printed line is always ended with a carriage +return, so the next item printed starts a new line. + +When an assignment statement is printed, the assignment is also made. This +allows you to get feedback on filling slots in an array with a \nameref{for} + statement, as shown in the last example above. +\end{Comments} +\end{Command} + +