diff --git a/books/bookvol5.pamphlet b/books/bookvol5.pamphlet index 8db7069..beb7755 100644 --- a/books/bookvol5.pamphlet +++ b/books/bookvol5.pamphlet @@ -169,54 +169,6 @@ $$ \center{\large{Volume 5: Axiom Interpreter}} \end{titlepage} \pagenumbering{roman} -\begin{verbatim} -Portions Copyright (c) 2005 Timothy Daly - -The Blue Bayou image Copyright (c) 2004 Jocelyn Guidry - -Portions Copyright (c) 2004 Martin Dunstan - -Portions Copyright (c) 1991-2002, -The Numerical ALgorithms Group Ltd. -All rights reserved. - -This book and the Axiom software is licensed as follows: - -Redistribution and use in source and binary forms, with or -without modification, are permitted provided that the following -conditions are -met: - - - Redistributions of source code must retain the above - copyright notice, this list of conditions and the - following disclaimer. - - - Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the - following disclaimer in the documentation and/or other - materials provided with the distribution. - - - Neither the name of The Numerical ALgorithms Group Ltd. - nor the names of its contributors may be used to endorse - or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND -CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, -INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR -CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -SUCH DAMAGE. - -\end{verbatim} \tableofcontents \vfill \eject @@ -737,7 +689,7 @@ This function performs those setup commands. @ -\pagehead{initroot}{Set \$spadroot to be the AXIOM shell variable} +\pagehead{initroot}{Set spadroot to be the AXIOM shell variable} Sets up the system to use the {\bf AXIOM} shell variable if we can and default to the {\bf \$spadroot} variable (which was the value of the {\bf AXIOM} shell variable at build time) if we can't. @@ -986,6 +938,1278 @@ Note that incRgen recursively wraps this function in a delay list. @ +\chapter{The Interpreter Syntax} +\section{syntax assignment} +\label{assignment} +\index{assignment} +\index{syntax!assignment} +\index{assignment!syntax} +<>= + +Immediate, Delayed, and Multiple Assignment + +==================================================================== +Immediate Assignment +==================================================================== + +A variable in Axiom refers to a value. A variable has a name beginning +with an uppercase or lowercase alphabetic character, "%", or "!". +Successive characters (if any) can be any of the above, digits, or "?". +Case is distinguished. The following are all examples of valid, distinct +variable names: + + a tooBig? a1B2c3%!? + A %j numberOfPoints + beta6 %J numberofpoints + +The ":=" operator is the immediate assignment operator. Use it to +associate a value with a variable. The syntax for immediate assignment +for a single variable is: + + variable := expression + +The value returned by an immediate assignment is the value of expression. + + a := 1 + 1 + Type: PositiveInteger + +The right-hand side of the expression is evaluated, yielding 1. The value +is then assigned to a. + + b := a + 1 + Type: PositiveInteger + +The right-hand side of the expression is evaluated, yieldig 1. This value +is then assigned to b. Thus a and b both have the value 1 after the sequence +of assignments. + + a := 2 + 2 + Type: PositiveInteger + +What is the value of b if a is assigned the value 2? + + b + 1 + Type: PositiveInteger + +The value of b is left unchanged. + +This is what we mean when we say this kind of assignment is immediate. +The variable b has no dependency on a after the initial assignment. This +is the usual notion of assignment in programming languages such as C, +Pascal, and Fortran. + +==================================================================== +Delayed Assignment +==================================================================== + +Axiom provides delayed assignment with "==". This implements a delayed +evaluation of the right-hand side and dependency checking. The syntax for +delayed assignment is + + variable == expression + +The value returned by a delayed assignment is the unique value of Void. + + a == 1 + Type: Void + + b == a + Type: Void + +Using a and b as above, these are the corresponding delayed assignments. + + a + Compiling body of rule a to compute value of type PositiveInteger + 1 + Type: PositiveInteger + +The right-hand side of each delayed assignment is left unevaluated until +the variables on the left-hand sides are evaluated. + + b + Compiling body of rule b to compute value of type PositiveInteger + 1 + Type: PositiveInteger + +This gives the same results as before. But if we change a to 2 + + a == 2 + Compiled code for a has been cleared. + Compiled code for b has been cleared. + 1 old definition(s) deleted for function or rule a + Type: Void + +Then a evaluates to 2, as expected + + a + Compiling body of rule a to compute value of type PositiveInteger + 2 + Type: PositiveInteger + +but the value of b reflects the change to a + + b + Compiling body of rule b to compute value of type PositiveInteger + 2 + Type: PositiveInteger + +==================================================================== +Multiple Immediate Assignments +==================================================================== + +It is possible to set several variables at the same time by using a +tuple of variables and a tuple of expressions. A tuple is a collection +of things separated by commas, often surrounded by parentheses. The +syntax for multiple immediate assignment is + + ( var1, var2, ..., varN ) := ( expr1, expr2, ..., exprN ) + +The value returned by an immediate assignment is the value of exprN. + + ( x, y ) := ( 1, 2 ) + 2 + Type: PositiveInteger + +This sets x to 1 and y to 2. Multiple immediate assignments are parallel +in the sense that the expressions on the right are all evaluated before +any assignments on the left are made. However, the order of evaluation +of these expressions is undefined. + + ( x, y ) := ( y, x ) + 1 + Type: PositiveInteger + + x + 2 + Type: PositiveInteger + +The variable x now has the previous value of y. + + y + 1 + Type: PositiveInteger + +The variable y now has the previous value of x. + +There is no syntactic form for multiple delayed assignments. + +@ + +\section{syntax blocks} +\label{blocks} +\index{blocks} +\index{syntax!blocks} +\index{blocks!syntax} +<>= +==================================================================== +Blocks +==================================================================== + +A block is a sequence of expressions evaluated in the order that they +appear, except as modified by control expressions such as leave, return, +iterate, and if-then-else constructions. The value of a block is the +value of the expression last evaluated in the block. + +To leave a block early, use "=>". For example, + + i < 0 => x + +The expression before the "=>" must evaluate to true or false. The +expression following the "=>" is the return value of the block. + +A block can be constructed in two ways: + + 1. the expressions can be separated by semicolons and the resulting + expression surrounded by parentheses, and + 2. the expressions can be written on succeeding lines with each line + indented the same number of spaces (which must be greater than zero). + A block entered in this form is called a pile + +Only the first form is available if you are entering expressions directly +to Axiom. Both forms are available in .input files. The syntax for a simple +block of expressions entered interactively is + + ( expression1 ; expression2 ; ... ; expressionN ) + +The value returned by a block is the value of an "=>" expression, or +expressionN if no "=>" is encountered. + +In .input files, blocks can also be written in piles. The examples +given here are assumed to come from .input files. + + a := + i := gcd(234,672) + i := 2*i**5 - i + 1 + 1 / i + + 1 + ----- + 23323 + Type: Fraction Integer + +In this example, we assign a rational number to a using a block consisting +of three expressions. This block is written as a pile. Each expression in +the pile has the same indentation, in this case two spaces to the right of +the first line. + + a := ( i := gcd(234,672); i := 2*i**5 - i + 1; 1 / i ) + + 1 + ----- + 23323 + Type: Fraction Integer + +Here is the same block written on one line. This is how you are required +to enter it at the input prompt. + + ( a := 1; b := 2; c := 3; [a,b,c] ) + [1,2,3] + Type: List PositiveInteger + +AAxiom gives you two ways of writing a block and the preferred way in +an .input file is to use a pile. Roughly speaking, a pile is a block +whose consituent expressions are indented the same amount. You begin a +pile by starting a new line for the first expression, indenting it to +the right of the previous line. You then enter the second expression on +a new line, vertically aligning it with the first line. And so on. If +you need to enter an inner pile, further indent its lines to the right +of the outer pile. Axiom knows where a pile ends. It ends when a subsequent +line is indented to the left of the pile or the end of the file. + +Also See: +o )help if +o )help repeat +o )help while +o )help for +o )help suchthat +o )help parallel +o )help lists + +@ +\footnote{ +\fnref{if} +\fnref{repeat} +\fnref{while} +\fnref{for} +\fnref{suchthat} +\fnref{parallel} +\fnref{lists}} + +\section{system clef} +\label{clef} +\index{clef} +\index{syntax!clef} +\index{clef!syntax} +<>= + +Entering printable keys generally inserts new text into the buffer (unless +in overwrite mode, see below). Other special keys can be used to modify +the text in the buffer. In the description of the keys below, ^n means +Control-n, or holding the CONTROL key down while pressing "n". Errors +will ring the terminal bell. + +^A/^E : Move cursor to beginning/end of the line. +^F/^B : Move cursor forward/backward one character. +^D : Delete the character under the cursor. +^H, DEL : Delete the character to the left of the cursor. +^K : Kill from the cursor to the end of line. +^L : Redraw current line. +^O : Toggle overwrite/insert mode. Initially in insert mode. Text + added in overwrite mode (including yanks) overwrite + existing text, while insert mode does not overwrite. +^P/^N : Move to previous/next item on history list. +^R/^S : Perform incremental reverse/forward search for string on + the history list. Typing normal characters adds to the current + search string and searches for a match. Typing ^R/^S marks + the start of a new search, and moves on to the next match. + Typing ^H or DEL deletes the last character from the search + string, and searches from the starting location of the last search. + Therefore, repeated DEL's appear to unwind to the match nearest + the point at which the last ^R or ^S was typed. If DEL is + repeated until the search string is empty the search location + begins from the start of the history list. Typing ESC or + any other editing character accepts the current match and + loads it into the buffer, terminating the search. +^T : Toggle the characters under and to the left of the cursor. +^Y : Yank previously killed text back at current location. Note that + this will overwrite or insert, depending on the current mode. +^U : Show help (this text). +TAB : Perform command completion based on word to the left of the cursor. + Words are deemed to contain only the alphanumeric and the % ! ? _ + characters. +NL, CR : returns current buffer to the program. + +DOS and ANSI terminal arrow key sequences are recognized, and act like: + + up : same as ^P + down : same as ^N + left : same as ^B + right : same as ^F + +@ + +\section{syntax collection} +\label{collection} +\index{collection} +\index{syntax!collection} +\index{collection!syntax} +<>= +==================================================================== +Collection -- Creating Lists and Streams with Iterators +==================================================================== + +All of the loop expressions which do not use the repeat leave or +iterate words can be used to create lists and streams. For example: + +This creates a simple list of the integers from 1 to 10: + + list := [i for i in 1..10] + [1,2,3,4,5,6,7,8,9,10] + Type: List PositiveInteger + +Create a stream of the integers greater than or equal to 1: + + stream := [i for i in 1..] + [1,2,3,4,5,6,7,...] + Type: Stream PositiveInteger + +This is a list of the prime numbers between 1 and 10, inclusive: + + [i for i in 1..10 | prime? i] + [2,3,5,7] + Type: List PositiveInteger + +This is a stream of the prime integers greater than or equal to 1: + + [i for i in 1.. | prime? i] + [2,3,5,7,11,13,17,...] + Type: Stream PositiveInteger + +This is a list of the integers between 1 and 10, inclusive, whose +squares are less than 700: + + [i for i in 1..10 while i*i < 700] + [1,2,3,4,5,6,7,8,9,10] + Type: List PositiveInteger + +This is a stream of the integers greater than or equal to 1 whose +squares are less than 700: + + [i for i in 1.. while i*i < 700] + [1,2,3,4,5,6,7,...] + Type: Stream PositiveInteger + +The general syntax of a collection is + + [ collectExpression iterator1 iterator2 ... iteratorN ] + +where each iterator is either a for or a while clause. The loop +terminates immedidately when the end test of any iterator succeeds +or when a return expression is evaluated in collectExpression. The +value returned by the collection is either a list or a stream of +elements, one for each iteration of the collectExpression. + +Be careful when you use while to create a stream. By default Axiom +tries to compute and display the first ten elements of a stream. If +the while condition is not satisfied quickly, Axiom can spend a long +(potentially infinite) time trying to compute the elements. Use + + )set streams calculate + +to change the defaults to something else. This also affects the number +of terms computed and displayed for power series. For the purposes of +these examples we have use this system command to display fewer than +ten terms. + +@ + +\section{syntax for} +\label{for} +\index{for} +\index{syntax!for} +\index{for!syntax} +<>= +==================================================================== +for loops +==================================================================== + +Axiom provide the for and in keywords in repeat loops, allowing you +to integrate across all elements of a list, or to have a variable take +on integral values from a lower bound to an upper bound. We shall refer +to these modifying clauses of repeat loops as for clauses. These clauses +can be present in addition to while clauses (See )help while). As with +all other types of repeat loops, leave (see )help leave) can be used to +prematurely terminate evaluation of the loop. + +The syntax for a simple loop using for is + + for iterator repeat loopbody + +The iterator has several forms. Each form has an end test which is +evaluted before loopbody is evaluated. A for loop terminates immediately +when the end test succeeds (evaluates to true) or when a leave or return +expression is evaluated in loopbody. The value returned by the loop is +the unique value of Void. + +==================================================================== +for i in n..m repeat +==================================================================== + +If for is followed by a variable name, the in keyword and then an integer +segment of the form n..m, the end test for this loop is the predicate +i > m. The body of the loop is evaluated m-n+1 times if this number is +greater than 0. If this number is less than or equal to 0, the loop body +is not evaluated at all. + +The variable i has the value n, n+1, ..., m for successive iterations +of the loop body. The loop variable is a local variable within the loop +body. Its value is not available outside the loop body and its value and +type within the loop body completely mask any outer definition of a +variable with the same name. + + for i in 10..12 repeat output(i**3) + 1000 + 1331 + 1728 + Type: Void + +The loop prints the values of 10^3, 11^3, and 12^3. + + a := [1,2,3] + [1,2,3] + Type: List PositiveInteger + + for i in 1..#a repeat output(a.i) + 1 + 2 + 3 + Type: Void + +Iterate across this list using "." to access the elements of a list +and the # operation to count its elements. + +This type of iteration is applicable to anything that uses ".". You +can also use it with functions that use indices to extract elements. + + m := matrix [[1,2],[4,3],[9,0]] + +- -+ + | 1 2 | + | 4 3 | + | 9 0 | + +- -+ + Type: Matrix Integer + +Define m to be a matrix. + + for i in 1..nrows(m) repeat output row(m.i) + [1,2] + [4,3] + [9,0] + Type: Void + +Display the rows of m. + +You can iterate with for-loops. + + for i in 1..5 repeat + if odd?(i) then iterate + output(i) + 2 + 4 + Type: Void + +Display the even integers in a segment. + +==================================================================== +for i in n..m by s repeat +==================================================================== + +By default, the difference between values taken on by a variable in +loops such as + + for i in n..m repeat ... + +is 1. It is possible to supply another, possibly negative, step value +by using the by keyword along with for and in. Like the upper and lower +bounds, the step value following the by keyword must be an integer. Note +that the loop + + for i in 1..2 by 0 repeat output(i) + +will not terminate by itself, as the step value does not change the +index from its initial value of 1. + + for i in 1..5 by 2 repeat output(i) + 1 + 3 + 5 + Type: Void + +This expression displays the odd integers between two bounds. + + for i in 5..1 by -2 repeat output(i) + 5 + 3 + 1 + Type: Void + +Use this to display the numbers in reverse order. + +==================================================================== +for i in n.. repeat +==================================================================== + +If the value after the ".." is omitted, the loop has no end test. A +potentially infinite loop is thus created. The variable is given the +successive values n, n+1, n+2, ... and the loop is terminated only +if a leave or return expression is evaluated in the loop body. However, +you may also add some other modifying clause on the repeat, for example, +a while clause, to stop the loop. + + for i in 15.. while not prime?(i) repeat output(i) + 15 + 16 + Type: Void + +This loop displays the integers greater than or equal to 15 and less +than the first prime number greater than 15. + +==================================================================== +for x in l repeat +==================================================================== + +Another variant of the for loop has the form: + + for x in list repeat loopbody + +This form is used when you want to iterate directly over the elements +of a list. In this form of the for loop, the variable x takes on the +value of each successive element in l. The end test is most simply +stated in English: "are there no more x in l?" + + l := [0, -5, 3] + [0, -5, 3] + Type: List Integer + + for x in l repeat output(x) + 0 + -5 + 3 + Type: Void + +This displays all of the elements of the list l, one per line. + +Since the list constructing expression + + expand [n..m] + +creates the list + + [n, n+1, ..., m] + +you might be tempted to think that the loops + + for i in n..m repeat output(i) + +and + + for x in expand [n..m] repeat output(x) + +are equivalent. The second form first creates the expanded list +(no matter how large it might be) and then does the iteration. The +first form potentially runs in much less space, as the index variable +i is simply incremented once per loop and the list is not actually +created. Using the first form is much more efficient. + +Of course, sometimes you really want to iterate across a specific list. +This displays each of the factors of 2400000: + + for f in factors(factor(2400000)) repeat output(f) + [factor= 2, exponent= 8] + [factor= 3, exponent= 1] + [factor= 5, exponent= 5] + Type: Void + +@ + +\section{syntax if} +\label{if} +\index{if} +\index{syntax!if} +\index{if!syntax} +<>= +==================================================================== +If-then-else +==================================================================== + +Like many other programming languages, Axiom uses the three keywords +if, then, and else to form conditional expressions. The else part of +the conditional is optional. The expression between the if and then +keywords is a predicate: an expression that evaluates to or is +convertible to either true or false, that is, a Boolean. + +The syntax for conditional expressions is + + if predicate then expression1 else expression2 + +where the "else expression2" part is optional. The value returned from +a conditional expression is expression1 if the predicate evaluates to +true and expression2 otherwise. If no else clause is given, the value +is always the unique value of Void. + +An if-then-else expression always returns a value. If the else clause +is missing then the entire expression returns the unique value of Void. +If both clauses are present, the type of the value returned by if is +obtained by resolving the types of the values of the two clauses. + +The predicate must evaluate to, or be convertible to, an object of type +Boolean: true or false. By default, the equal sign "=" creates an equation. + + x + 1 = y + x + 1 = y + Type: Equation Polynomial Integer + +This is an equation, not a boolean condition. In particular, it is +an object of type Equation Polynomial Integer. + +However, for predicates in if expressions, Axiom places a default +target type of Boolean on the predicate and equality testing is performed. +Thus you need not qualify the "=" in any way. In other contexts you may +need to tell Axiom that you want to test for equality rather than create +an equation. In these cases, use "@" and a target type of Boolean. + +The compound symbol meaning "not equal" in Axiom is "~=". This can be +used directly without a package call or a target specification. The +expression "a ~= b" is directly translated to "not(a = b)". + +Many other functions have return values of type Boolean. These include +<, <=, >, >=, ~=, and member?. By convention, operations with names +ending in "?" return Boolean values. + +The usual rules for piles are suspended for conditional expressions. In +.input files, the then and else keywords can begin in the same column +as the corresponding if by may also appear to the right. Each of the +following styles of writing if-then-else expressions is acceptable: + + if i>0 then output("positive") else output("nonpositive") + + if i>0 then output("positive") + else output("nonpositive") + + if i>0 then output("positive") + else output("nonpositive") + + if i>0 + then output("positive") + else output("nonpositive") + + if i>0 + then output("positive") + else output("nonpositive") + +A block can follow the then or else keywords. In the following two +assignments to a, the then and else clauses each are followed by two +line piles. The value returned in each is the value of the second line. + + a := + if i > 0 then + j := sin(i * pi()) + exp(j + 1/j) + else + j := cos(i * 0.5 * pi()) + log(abs(j)**5 + i) + + + a := + if i > 0 + then + j := sin(i * pi()) + exp(j + 1/j) + else + j := cos(i * 0.5 * pi()) + log(abs(j)**5 + i) + +These are both equivalent to the following: + + a := + if i > 0 then (j := sin(i * pi()); exp(j + 1/j)) + else (j := cos(i * 0.5 * pi()); log(abs(j)**5 + i)) + +@ + +\section{syntax iterate} +\label{iterate} +\index{iterate} +\index{syntax!iterate} +\index{iterate!syntax} +<>= +==================================================================== +iterate in loops +==================================================================== + +Axiom provides an iterate expression that skips over the remainder +of a loop body and starts the next loop execution. We first initialize +a counter. + + i := 0 + 0 + Type: NonNegativeInteger + +Display the even integers from 2 to 5: + + repeat + i := i + 1 + if i > 5 then leave + if odd?(i) then iterate + output(i) + 2 + 4 + Type: Void + +@ + +\section{syntax leave} +\label{leave} +\index{leave} +\index{syntax!leave} +\index{leave!syntax} +<>= +==================================================================== +leave in loops +==================================================================== + +The leave keyword is often more useful in terminating a loop. A +leave causes control to transfer to the expression immediately following +the loop. As loops always return the unique value of Void, you cannot +return a value with leave. That is, leave takes no argument. + + f() == + i := 1 + repeat + if factorial(i) > 1000 then leave + i := i + 1 + i + Type: Void + +This example is a modification of the last example in the previous +section. Instead of using return we'll use leave. + + f() + 7 + Type: PositiveInteger + +The loop terminates when factorial(i) gets big enough. The last line +of the function evaluates to the corresponding "good" value of i +and the function terminates, returning that value. + +You can only use leave to terminate the evaluation of one loop. Lets +consider a loop within a loop, that is, a loop with a nested loop. +First, we initialize two counter variables. + + (i,j) := (1,1) + 1 + Type: PositiveInteger + + repeat + repeat + if (i + j) > 10 then leave + j := j + 1 + if (i + j) > 10 then leave + i := i + 1 + Type: Void + +Nested loops must have multiple leave expressions at the appropriate +nesting level. How would you rewrite this so (i + j) > 10 is only +evaluated once? + +==================================================================== +leave vs => in loop bodies +==================================================================== + +Compare the following two loops: + + i := 1 i := 1 + repeat repeat + i := i + 1 i := i + 1 + i > 3 => i if i > 3 then leave + output(i) output(i) + +In the example on the left, the values 2 and 3 for i are displayed but +then the "=>" does not allow control to reach the call to output again. +The loop will not terminate until you run out of space or interrupt the +execution. The variable i will continue to be incremented because the +"=>" only means to leave the block, not the loop. + +In the example on the right, upon reaching 4, the leave will be executed, +and both the block and the loop will terminate. This is one of the reasons +why both "=>" and leave are provided. Using a while clase with the "=>" +lets you simulate the action of leave. + +@ + +\section{syntax parallel} +\label{parallel} +\index{parallel} +\index{syntax!parallel} +\index{parallel!syntax} +<>= +==================================================================== +parallel iteration +==================================================================== + +Sometimes you want to iterate across two lists in parallel, or perhaps +you want to traverse a list while incrementing a variable. + +The general syntax of a repeat loop is + + iterator1, iterator2, ..., iteratorN repeat loopbody + +where each iterator is either a for or a while clause. The loop +terminates immediately when the end test of any iterator succeeds or +when a leave or return expression is evaluated in loopbody. The value +returned by the loop is the unique value of Void. + + l := [1,3,5,7] + [1,3,5,7] + Type: List PositiveInteger + + m := [100,200] + [100,200] + Type: List PositiveInteger + + sum := 0 + 0 + Type: NonNegativeInteger + +Here we write a loop to iterate across two lists, computing the sum +of the pairwise product of the elements: + + for x in l for y in m repeat + sum := sum + x*y + Type: Void + +The last two elements of l are not used in the calculation because +m has two fewer elements than l. + + sum + 700 + Type: NonNegativeInteger + +This is the "dot product". + +Next we write a loop to compute the sum of the products of the loop +elements with their positions in the loop. + + l := [2,3,5,7,11,13,17,19,23,29,31,37] + [2,3,5,7,11,13,17,19,23,29,31,37] + Type: List PositiveInteger + + sum := 0 + 0 + Type: NonNegativeInteger + + for i in 0.. for x in l repeat sum := i * x + Type: Void + +Here looping stops when the list l is exhaused, even though the +for i in 0.. specifies no terminating condition. + + sum + 407 + Type: NonNegativeInteger + +When "|" is used to qualify any of the for clauses in a parallel +iteration, the variables in the predicates can be from an outer +scope or from a for clause in or to the left of the modified clause. + +This is correct: + + for i in 1..10 repeat + for j in 200..300 | ood? (i+j) repeat + output [i,j] + +But this is not correct. The variable j has not been defined outside +the inner loop: + + for i in 1..01 | odd? (i+j) repeat -- wrong, j not defined + for j in 200..300 repeat + output [i,j] + +It is possible to mix several of repeat modifying clauses on a loop: + + for i in 1..10 + for j in 151..160 | odd? j + while i + j < 160 repeat + output [i,j] + [1,151] + [3,153] + Type: Void + +Here are useful rules for composing loop expressions: + + 1. while predicates can only refer to variables that are global (or + in an outer scope) or that are defined in for clauses to the left + of the predicate. + 2. A "such that" predicate (somthing following "|") must directly + follow a for clause and can only refer to variables that are + global (or in an outer scope) or defined in the modified for clause + or any for clause to the left. + +@ + +\section{syntax repeat} +\label{repeat} +\index{repeat} +\index{syntax!repeat} +\index{repeat!syntax} +<>= +==================================================================== +Repeat Loops +==================================================================== + +A loop is an expression that contains another expression, called the loop +body, which is to be evaluated zero or more times. All loops contain the +repeat keyword and return the unique value of Void. Loops can contain +inner loops to any depth. + +The most basic loop is of the form + + repeat loopbody + +Unless loopbody contains a leave or return expression, the loop repeats +foreer. The value returned by the loop is the unique value of Void. + +Axiom tries to determine completely the type of every object in a loop +and then to translate the loop body to Lisp or even to machine code. This +translation is called compilation. + +If Axiom decides that it cannot compile the loop, it issues a message +stating the problem and then the following message: + + We will attemp to step through and interpret the code + +It is still possible that Axiom can evalute the loop but in interpret-code +mode. + +==================================================================== +Return in Loops +==================================================================== + +A return expression is used to exit a function with a particular value. +In particular, if a return is in a loop within the function, the loop +is terminated whenever the return is evaluated. + + f() == + i := 1 + repeat + if factorial(i) > 1000 then return i + i := i + 1 + Type: Void + + f() + Type: Void + +When factorial(i) is big enough, control passes from inside the loop +all the way outside the function, returning the value of i (so we think). +What went wrong? Isn't it obvious that this function should return an +integer? Well, Axiom makes no attempt to analyze the structure of a +loop to determine if it always returns a value because, in general, this +is impossible. So Axiom has this simple rule: the type of the function is +determined by the type of its body, in this case a block. The normal value +of a block is the value of its last expression, in this case, a loop. And +the value of every loop is the unique value of Void. So the return type +of f is Void. + +There are two ways to fix this. The best way is for you to tell Axiom +what the return type of f is. You do this by giving f a declaration + + f:() -> Integer + +prior to calling for its value. This tells Axiom "trust me -- an integer +is returned". Another way is to add a dummy expression as follows. + + f() == + i := 1 + repeat + if factorial(i) > 1000 then return i + i := i + 1 + 0 + Type: Void + +Note that the dummy expression will never be evaluated but it is the +last expression in the function and will determine the return type. + + f() + 7 + Type: PositiveInteger + +==================================================================== +leave in loops +==================================================================== + +The leave keyword is often more useful in terminating a loop. A +leave causes control to transfer to the expression immediately following +the loop. As loops always return the unique value of Void, you cannot +return a value with leave. That is, leave takes no argument. + + f() == + i := 1 + repeat + if factorial(i) > 1000 then leave + i := i + 1 + i + Type: Void + +This example is a modification of the last example in the previous +section. Instead of using return we'll use leave. + + f() + 7 + Type: PositiveInteger + +The loop terminates when factorial(i) gets big enough. The last line +of the function evaluates to the corresponding "good" value of i +and the function terminates, returning that value. + +You can only use leave to terminate the evaluation of one loop. Lets +consider a loop within a loop, that is, a loop with a nested loop. +First, we initialize two counter variables. + + (i,j) := (1,1) + 1 + Type: PositiveInteger + + repeat + repeat + if (i + j) > 10 then leave + j := j + 1 + if (i + j) > 10 then leave + i := i + 1 + Type: Void + +Nested loops must have multiple leave expressions at the appropriate +nesting level. How would you rewrite this so (i + j) > 10 is only +evaluated once? + +==================================================================== +leave vs => in loop bodies +==================================================================== + +Compare the following two loops: + + i := 1 i := 1 + repeat repeat + i := i + 1 i := i + 1 + i > 3 => i if i > 3 then leave + output(i) output(i) + +In the example on the left, the values 2 and 3 for i are displayed but +then the "=>" does not allow control to reach the call to output again. +The loop will not terminate until you run out of space or interrupt the +execution. The variable i will continue to be incremented because the +"=>" only means to leave the block, not the loop. + +In the example on the right, upon reaching 4, the leave will be executed, +and both the block and the loop will terminate. This is one of the reasons +why both "=>" and leave are provided. Using a while clase with the "=>" +lets you simulate the action of leave. + +==================================================================== +iterate in loops +==================================================================== + +Axiom provides an iterate expression that skips over the remainder +of a loop body and starts the next loop execution. We first initialize +a counter. + + i := 0 + 0 + Type: NonNegativeInteger + +Display the even integers from 2 to 5: + + repeat + i := i + 1 + if i > 5 then leave + if odd?(i) then iterate + output(i) + 2 + 4 + Type: Void + +Also See: +o )help blocks +o )help if +o )help while +o )help for +o )help suchthat +o )help parallel +o )help lists + +@ +\footnote{ +\fnref{blocks} +\fnref{if} +\fnref{while} +\fnref{for} +\fnref{suchthat} +\fnref{parallel} +\fnref{lists}} + +\section{syntax suchthat} +\label{suchthat} +\index{suchthat} +\index{syntax!suchthat} +\index{suchthat!syntax} +<>= +==================================================================== +Such that predicates +==================================================================== + +A for loop can be followed by a "|" and then a predicate. The predicate +qualifies the use of the values from the iterator that follows the for. +Think of the vertical bar "|" as the phrase "such that". + + for n in 0..4 | odd? n repeat output n + 1 + 3 + Type: Void + +This loop expression prints out the integers n in the given segment +such that n is odd. + +A for loop can also be written + + for iterator | predicate repeat loopbody + +which is equivalent to: + + for iterator repeat if predicate then loopbody else iterate + +The predicate need not refer only to the variable in the for clause. +Any variable in an outer scope can be part of the predicate. + + for i in 1..50 repeat + for j in 1..50 | factorial(i+j) < 25 repeat + output [i,j] + [1,1] + [1,2] + [1,3] + [2,1] + [2,2] + [3,1] + Type: Void + +@ + +\section{syntax syntax} +\label{syntax} +<>= + +The Axiom Interactive Language has the following features documented here. + +More information is available by typing + + )help feature + +where feature is one of: + + assignment -- Immediate and delayed assignments + blocks -- Blocks of expressions + collection -- creating lists with iterators + for -- for loops + if -- If-then-else statements + iterate -- using iterate in loops + leave -- using leave in loops + parallel -- parallel iterations + repeat -- repeat loops + suchthat -- suchthat predicates + while -- while loops + +@ + +\section{syntax while} +\label{while} +\index{while} +\index{syntax!while} +\index{while!syntax} +<>= +==================================================================== +while loops +==================================================================== + +The repeat in a loop can be modified by adding one or more while +clauses. Each clause contains a predicate immediately following the +while keyword. The predicate is tested before the evaluation of the +body of the loop. The loop body is evaluated whenever the predicate +in a while clause is true. + +The syntax for a simple loop using while is + + while predicate repeat loopbody + +The predicate is evaluated before loopbody is evaluated. A while loop +terminates immediately when predicate evaluates to false or when a +leave or return expression is evaluted. See )help repeat for more +information on leave and return. + +Here is a simple example of using while in a loop. We first initialize +the counter. + + i := 1 + 1 + Type: PositiveInteger + + while i < 1 repeat + output "hello" + i := i + 1 + Type: Void + +The steps involved in computing this example are + (1) set i to 1 + (2) test the condition i < 1 and determine that it is not true + (3) do not evaluate the loop body and therefore do not display "hello" + + (x, y) := (1, 1) + 1 + Type: PositiveInteger + +If you have multiple predicates to be tested use the logical and +operation to separate them. Axiom evaluates these predicates from +left to right. + + while x < 4 and y < 10 repeat + output [x,y] + x := x + 1 + y := y + 2 + [1,1] + [2,3] + [3,5] + Type: Void + + +A leave expression can be included in a loop body to terminate a loop +even if the predicate in any while clauses are not false. + + (x, y) := (1, 1) + 1 + Type: PositiveInteger + + while x < 4 and y < 10 repeat + if x + y > 7 then leave + output [x,y] + x := x + 1 + y := y + 2 + [1,1] + [2,3] + Type: Void + +@ + \chapter{System Command Handling} \defdollar{systemCommands} The system commands are the top-level commands available in Axiom @@ -1363,84 +2587,80 @@ we return the remainder of the string without the leading prefix. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{abbreviations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} compiler - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\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{list} - -\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. - -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, \index{abbreviation query} -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 {\tt List}: -\begin{verbatim} +<>= +==================================================================== +A.2. )abbreviation +==================================================================== + +User Level Required: compiler + +Command Syntax: + + - )abbreviation query [nameOrAbbrev] + - )abbreviation category abbrev fullname [)quiet] + - )abbreviation domain abbrev fullname [)quiet] + - )abbreviation package abbrev fullname [)quiet] + - )abbreviation remove nameOrAbbrev + +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. 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 query argument, 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 all constructors are listed. + +The following shows the abbreviation for the constructor List: + )abbreviation query List -\end{verbatim} -The following shows the constructor name corresponding to the -abbreviation {\tt NNI}: -\begin{verbatim} + +The following shows the constructor name corresponding to the abbreviation +NNI: + )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}. -\index{abbreviation package} -\index{abbreviation domain} -\index{abbreviation category} -The following add abbreviations to the system for a + +To add an abbreviation for a constructor, use this command with category, +domain or package. 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. -\index{abbreviation remove} 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 {\tt VECTOR2} and the constructor name -{\tt VectorFunctions2} from the system: -\begin{verbatim} + +If the )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 remove argument is used. 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 VECTOR2 and the constructor name VectorFunctions2 +from the system: + )abbreviation remove VECTOR2 )abbreviation remove VectorFunctions2 -\end{verbatim} + +Also See: +o )compile + +@ +\footnote{\fnref{compile}} -\section{Variables Used} \section{Functions} \defun{abbreviations}{abbreviations} <>= @@ -1520,31 +2740,40 @@ will remove the abbreviation {\tt VECTOR2} and the constructor name %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{boot} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} development - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )boot} {\it bootExpression} -\end{list} - -\par\noindent{\bf Command Description:} - -This command is used by Axiom system developers to execute -expressions written in the BOOT language. -For example, -\begin{verbatim} +<>= +==================================================================== +A.3. )boot +==================================================================== + +User Level Required: development + +Command Syntax: + + - )boot bootExpression + +Command Description: + +This command is used by AXIOM system developers to execute expressions +written in the BOOT language. For example, + )boot times3(x) == 3*x -\end{verbatim} -creates and compiles the Common Lisp function ``times3'' -obtained by translating the BOOT code. + +creates and compiles the Lisp function ``times3'' obtained by translating the +BOOT code. + +Also See: +o )fin +o )lisp +o )set +o )system + +@ +\footnote{ +\fnref{fin} +\fnref{lisp} +\fnref{set} +\fnref{system}} -\par\noindent{\bf Also See:} -\fnref{fin}, -\fnref{lisp}, -\fnref{set}, and -\fnref{system} -\section{Variables Used} \section{Functions} This command is in the list of \verb|$noParseCommands| @@ -1555,19 +2784,20 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{browse} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= -\par\noindent{\bf User Level Required:} development +User Level Required: development -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )browse} -\end{list} +Command Syntax: + + )browse -\par\noindent{\bf Command Description:} +Command Description: -This command is used by Axiom system users to start the Axiom top -level loop listening for browser connections. +This command is used by Axiom system users to start the Axiom top level +loop listening for browser connections. +@ \section{Overview} The Axiom book on the help browser is a complete rewrite of the hyperdoc mechanism. There are several components that were needed @@ -1771,49 +3001,48 @@ if the token is a command. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{cd} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )cd} {\it directory} -\end{list} - -\par\noindent{\bf Command Description:} - -This command sets the Axiom working current directory. -The current directory is used for looking for -input files (for {\tt )read}), -Axiom library source files (for {\tt )compile}), -saved history environment files (for {\tt )history )restore}), -compiled Axiom library files (for {\tt )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 Axiom library files (via {\tt )compile}). -\index{read} -\index{compile} -\index{history )restore} -\index{edit} -\index{spool} -\index{history )write} -\index{history )save} - -If issued with no argument, this command sets the Axiom -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:} -\fnref{compiler}, -\fnref{edit}, -\fnref{history}, -\fnref{library}, -\fnref{read}, and -\fnref{spool} +<>= +==================================================================== +A.4. )cd +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )cd directory + +Command Description: + +This command sets the AXIOM working current directory. The current directory +is used for looking for input files (for )read), AXIOM library source files +(for )compile), saved history environment files (for )history )restore), +compiled AXIOM library files (for )library), and files to edit (for )edit). +It is also used for writing spool files (via )spool), writing history input +files (via )history )write) and history environment files (via )history +)save),and compiled AXIOM library files (via )compile). + +If issued with no argument, this command sets the AXIOM current directory to +your home directory. If an argument is used, it must be a valid directory +name. Except for the ``)'' at the beginning of the command, this has the same +syntax as the operating system cd command. + +Also See: +o )compile +o )edit +o )history +o )library +o )read +o )spool + +@ +\footnote{ +\fnref{compile} +\fnref{edit} +\fnref{history} +\fnref{library} +\fnref{read} +\fnref{spool}} \section{Variables Used} \section{Functions} @@ -1821,85 +3050,92 @@ this has the same syntax as the operating system {\tt cd} command. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{clear} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\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{list} -\par\noindent{\bf Command Description:} - +<>= +==================================================================== +A.6. )clear +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )clear all + - )clear completely + - )clear properties all + - )clear properties obj1 [obj2 ...] + - )clear value all + - )clear value obj1 [obj2 ...] + - )clear mode all + - )clear mode obj1 [obj2 ...] + +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} +definitions and values from the workspace. To empty the entire workspace and +reset the step counter to 1, issue + )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} + +To remove everything about the object x, issue + )clear properties x -\end{verbatim} -To remove everything about the objects {\tt x, y} and {\tt f}, issue -\begin{verbatim} + +To remove everything about the objects x, y and f, issue + )clear properties x y f -\end{verbatim} - -The word {\tt properties} may be abbreviated to the single letter -``{\tt p}''. -\begin{verbatim} + +The word properties may be abbreviated to the single letter ``p''. + )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} + +This retains whatever declarations the objects had. To remove definitions and +values for the specific objects x, y and f, issue + )clear value x y f )clear v x y f -\end{verbatim} -To remove the declarations of everything while leaving the definitions and + +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} + +To remove declarations for the specific objects x, y and f, issue + )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 )display names and )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:} -\fnref{display}, -\fnref{history}, -\fnref{frame}, and -\fnref{undo} + +does everything that )clear all does, and also clears the internal system +function and constructor caches. + +Also See: +o )display +o )history +o )undo + +@ +\footnote{ +\fnref{display} +\fnref{history} +\fnref{undo}} \section{Variables Used} \defdollar{clearOptions} @@ -2114,43 +3350,50 @@ Clear all the options except the argument. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{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} +<>= +==================================================================== +A.5. )close +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )close + - )close )quietly + +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 + )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} + +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 + 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:} -\fnref{quit} and -\fnref{pquit} + +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 )quietly option to force AXIOM to close down the interpreter +client process without closing down the entire AXIOM session. + +Also See: +o )quit +o )pquit + +@ +\footnote{ +\fnref{quit} +\fnref{pquit}} -\section{Variables Used} \section{Functions} \defun{queryClients}{queryClients} Returns the number of active scratchpad clients @@ -2200,318 +3443,265 @@ Returns the number of active scratchpad clients %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{compiler} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} compiler - -\par\noindent{\bf Command Syntax:} - -\begin{list}{} -\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{list} - -\par\noindent{\bf Command Description:} - -You use this command to invoke the new Axiom library compiler or -the old Axiom system compiler. -The {\tt )compile} system command is actually a combination of -Axiom processing and a call to the Aldor compiler. -It is performing double-duty, acting as a front-end to -both the Aldor compiler and the old Axiom system -compiler. -(The old Axiom system compiler was written in Lisp and was -an integral part of the Axiom environment. -The Aldor compiler is written in C and executed by the operating system -when called from within Axiom.) - -This command compiles files with file extensions {\it .as, .ao} -and {\it .al} with the -Aldor compiler and files with file extension {\it .spad} with the -old Axiom system compiler. -It also can compile files with file extension {\it .lsp}. These -are assumed to be Lisp files genererated by the Aldor -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 Aldor compiler -and make any necessary corrections. - -We now describe the options for the new Aldor compiler. - -The first thing {\tt )compile} does is look for a source code -filename among its arguments. -Thus -\begin{verbatim} +<>= +==================================================================== +A.7. )compile +==================================================================== + +User Level Required: compiler + +Command Syntax: + + - )compile + - )compile fileName + - )compile fileName.as + - )compile directory/fileName.as + - )compile fileName.ao + - )compile directory/fileName.ao + - )compile fileName.al + - )compile directory/fileName.al + - )compile fileName.lsp + - )compile directory/fileName.lsp + - )compile fileName.spad + - )compile directory/fileName.spad + - )compile fileName )new + - )compile fileName )old + - )compile fileName )translate + - )compile fileName )quiet + - )compile fileName )noquiet + - )compile fileName )moreargs + - )compile fileName )onlyargs + - )compile fileName )break + - )compile fileName )nobreak + - )compile fileName )library + - )compile fileName )nolibrary + - )compile fileName )vartrace + - )compile fileName )constructor nameOrAbbrev + +Command Description: + +You use this command to invoke the new AXIOM library compiler or the old +AXIOM system compiler. The )compile system command is actually a combination +of AXIOM processing and a call to the AXIOM-XL compiler. It is performing +double-duty, acting as a front-end to both the AXIOM-XL compiler and the old +AXIOM system compiler. (The old AXIOM system compiler was written in Lisp and +was an integral part of the AXIOM environment. The AXIOM-XL compiler is +written in C and executed by the operating system when called from within +AXIOM.) + +The command compiles files with file extensions .as, .ao and .al with the +AXIOM-XL compiler and files with file extension .spad with the old AXIOM +system compiler. It also can compile files with file extension .lsp. These +are assumed to be Lisp files genererated by the AXIOM-XL compiler. If you +omit the file extension, the command looks to see if you have specified the +)new or )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 .as, .ao and .al and +then files with extension .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 )translate option is used to invoke a special version of the old system +compiler that will translate a .spad file to a .as file. That is, the .spad +file will be parsed and analyzed and a file using the new syntax will be +created. By default, the .as file is created in the same directory as the +.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 )translate implies the )old option so the file +extension can safely be omitted. If )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 AXIOM-XL compiler and make any necessary corrections. + +We now describe the options for the new AXIOM-XL compiler. + +The first thing )compile does is look for a source code filename among its +arguments. Thus + )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 Axiom 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 -Axiom.) - -This is frequently all you need to compile your file. -This simple command: -\begin{enumerate} -\item Invokes the Aldor compiler and produces Lisp output. -\item Calls the Lisp compiler if the Aldor compilation was -successful. -\item Uses the {\tt )library} command to tell Axiom about -the contents of your compiled file and arrange to have those -contents loaded on demand. -\end{enumerate} - -Should you not want the {\tt )library} command automatically -invoked, call {\tt )compile} with the {\tt )nolibrary} option. -For example, -\begin{verbatim} + +all invoke )compiler on the file /u/jones/as/mycode.as if the current AXIOM +working directory is /u/jones/as. (Recall that you can set the working +directory via the )cd command. If you don't set it explicitly, it is the +directory from which you started AXIOM.) + +This is frequently all you need to compile your file. This simple command: + + - Invokes the AXIOM-XL compiler and produces Lisp output. + - Calls the Lisp compiler if the AXIOM-XL compilation was + successful. + - Use the )library command to tell AXIOM about + the contents of your compiled file and arrange to have those contents + loaded on demand. + +Should you not want the )library command automatically invoked, call )compile +with the )nolibrary option. For example, + )compile mycode.as )nolibrary -\end{verbatim} - -The general description of Aldor command line arguments is in -the Aldor documentation. -The default options used by the {\tt )compile} command can be -viewed and set using the {\tt )set compiler args} Axiom -system command. -The current defaults are -\begin{verbatim} + +The general description of AXIOM-XL command line arguments is in the AXIOM-XL +documentation. The default options used by the )compile command can be viewed +and set using the )set compiler args AXIOM system command. The current +defaults are + -O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom -\end{verbatim} + These options mean: -\begin{itemize} -\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, -\index{Lisp!code generation} -\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 -Aldor libraries for generating stand-alone code -are not accidentally used with Axiom. -\end{itemize} - -To supplement these default arguments, use the {\tt )moreargs} option on -{\tt )compile.} + + - -O: perform all optimizations, + - -Fasy: generate a .asy file, + - -Fao: generate a .ao file, + - -Flsp: generate a .lsp (Lisp) + file, + - -laxiom: use the axiom library libaxiom.al, + - -Mno-AXL_W_WillObsolete: do not display messages + about older generated files becoming obsolete, and + - -DAxiom: define the global assertion Axiom so that the + AXIOM-XL libraries for generating stand-alone code are not accidentally + used with AXIOM. + +To supplement these default arguments, use the )moreargs option on )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} + +uses the default arguments and appends the -v (verbose) argument flag. The +additional argument specification must be enclosed in double quotes. + +To completely replace these default arguments for a particular use of +)compile, use the )onlyargs option. For example, + )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 Axiom. - -To completely replace the default arguments for all calls to {\tt -)compile} within your Axiom session, use {\tt )set compiler args.} -For example, to use the above arguments for all compilations, issue -\begin{verbatim} + +only uses the -v (verbose) and -O (optimize) arguments. The argument +specification must be enclosed in double quotes. In this example, Lisp code +is not produced and so the compilation output will not be available to AXIOM. + +To completely replace the default arguments for all calls to )compile within +your AXIOM session, use )set compiler args. For example, to use the above +arguments for all compilations, issue + )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 Axiom 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} + +Make sure you include the necessary -l and -Y arguments along with those +needed for Lisp file creation. As above, the argument specification must be +enclosed in double quotes. + +By default, the )library system command exposes all domains and categories it +processes. This means that the AXIOM 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 )library command should still be used, though, so that the +code will be loaded on demand. In this case, you should use the )nolibrary +option on )compile and the )noexpose option in the )library command. For +example, + )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} + +Once you have established your own collection of compiled code, you may find +it handy to use the )dir option on the )library command. This causes )library +to process all compiled code in the specified directory. For example, + )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} + +You must give an explicit directory after )dir, even if you want all compiled +code in the current working directory processed. + )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 Aldor. 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} + +The )compile command works with several file extensions. We saw above what +happens when it is invoked on a file with extension .as. A .ao file is a +portable binary compiled version of a .as file, and )compile simply passes +the .ao file onto AXIOM-XL. The generated Lisp file is compiled and )library +is automatically called, just as if you had specified a .as file. + +A .al file is an archive file containing .ao files. The archive is created +(on Unix systems) with the ar program. When )compile is given a .al file, it +creates a directory whose name is based on that of the archive. For example, +if you issue + )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 + +the directory mylib.axldir is created. All members of the archive are +unarchived into the directory and )compile is called on each .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 Aldor 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. - + +A .lsp file is a Lisp source file, presumably, in our context, generated by +AXIOM-XL when called with the -Flsp option. When )compile is used with a .lsp +file, the Lisp file is compiled and )library is called. You must also have +present a .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} + +You can compile category, domain, and package constructors contained in files +with file extension .spad. You can compile individual constructors or every +constructor in a file. + +The full filename is remembered between invocations of this command and )edit +commands. The sequence of commands + )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 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. -\index{abbreviation} - -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 {\tt 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 Aldor 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. 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} + +will call the compiler, edit, and then call the compiler again on the file +matrix.spad. If you do not specify a directory, the working current directory +(see description of command )cd ) 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 )abbreviation command in the file in which it +is defined. We suggest that you place the )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. + +The )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 .NRLIB file +extension. For example, the directory containing the compiled code for the +MATRIX constructor is called MATRIX.NRLIB. The )nolibrary option says that +such files should not be created. The default is )library. Note that the +semantics of )library and )nolibrary for the new AXIOM-XL compiler and for +the old system compiler are completely different. + +The )vartrace option causes the compiler to generate extra code for the +constructor to support conditional tracing of variable assignments. (see +description of command )trace ). Without this option, this code is suppressed +and one cannot use the )vars option for the trace command. + +The )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 )constructor. Thus either + )compile matrix.spad )constructor RectangularMatrix -\end{verbatim} + or -\begin{verbatim} + )compile matrix.spad )constructor RMATRIX -\end{verbatim} -compiles the {\tt 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. + +compiles the RectangularMatrix constructor defined in matrix.spad. + +The )break and )nobreak options determine what the old system compiler does +when it encounters an error. )break is the default and it indicates that +processing should stop at the first error. The value of the )set break +variable then controls what happens. + +Also See: +o )abbreviation +o )edit +o )library -\par\noindent{\bf Also See:} -{\tt )abbreviations}, -{\tt )edit}, and -{\tt )library} +@ +\footnote{ +\fnref{abbreviation} +\fnref{edit} +\fnref{library}} -\section{Variables Used} \section{Functions} \defun{compiler}{compiler} <>= @@ -2612,13 +3802,262 @@ The value of the {\tt )set break} variable then controls what happens. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{copyright} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +Axiom is distributed under terms of the Modified BSD license. +Axiom was released under this license as of September 3, 2002. +Source code is freely available at: +http://savannah.nongnu.org/projects/axiom +Copyrights remain with the original copyright holders. +Use of this material is by permission and/or license. +Individual files contain reference to these applicable copyrights. +The copyright and license statements are collected here for reference. + +Portions Copyright (c) 2003- The Axiom Team + +The Axiom Team is the collective name for the people who have +contributed to this project. Where no other copyright statement +is noted in a file this copyright will apply. + +Portions Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd. +All rights reserved. -\section{Variables Used} +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + - Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + - Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + - Neither the name of The Numerical ALgorithms Group Ltd. nor the + names of its contributors may be used to endorse or promote products + derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS +IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER +OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, +PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Portions Copyright (C) 1989-95 GROUPE BULL + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to +deal in the Software without restriction, including without limitation the +rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +sell copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN +AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Except as contained in this notice, the name of GROUPE BULL shall not be +used in advertising or otherwise to promote the sale, use or other dealings +in this Software without prior written authorization from GROUPE BULL. + +Portions Copyright (C) 2002, Codemist Ltd. All rights reserved. +acn@codemist.co.uk + + + CCL Public License 1.0 + ====================== + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +(1) Redistributions of source code must retain the above copyright notice, +this list of conditions and the following disclaimer. + +(2) Redistributions in binary form must reproduce the above copyright +notice, +this list of conditions and the following disclaimer in the documentation +and/or other materials provided with the distribution. + +(3) Neither the name of Codemist nor the names of other contributors may +be used to endorse or promote products derived from this software without +specific prior written permission. + +(4) If you distribute a modified form or either source or binary code + (a) you must make the source form of these modification available + to Codemist; + (b) you grant Codemist a royalty-free license to use, modify + or redistribute your modifications without limitation; + (c) you represent that you are legally entitled to grant these rights + and that you are not providing Codemist with any code that violates + any law or breaches any contract. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +Portions Copyright (C) 1995-1997 Eric Young (eay@mincom.oz.au) +All rights reserved. + +This package is an SSL implementation written +by Eric Young (eay@mincom.oz.au). +The implementation was written so as to conform with Netscapes SSL. + +This library is free for commercial and non-commercial use as long as +the following conditions are aheared to. The following conditions +apply to all code found in this distribution, be it the RC4, RSA, +lhash, DES, etc., code; not just the SSL code. The SSL documentation +included with this distribution is covered by the same copyright terms +except that the holder is Tim Hudson (tjh@mincom.oz.au). + +Copyright remains Eric Young's, and as such any Copyright notices in +the code are not to be removed. +If this package is used in a product, Eric Young should be given attribution +as the author of the parts of the library used. +This can be in the form of a textual message at program startup or +in documentation (online or textual) provided with the package. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: +1. Redistributions of source code must retain the copyright + notice, this list of conditions and the following disclaimer. +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. +3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: + "This product includes cryptographic software written by + Eric Young (eay@mincom.oz.au)" + The word 'cryptographic' can be left out if the rouines from the library + being used are not cryptographic related :-). +4. If you include any Windows specific code (or a derivative thereof) from + the apps directory (application code) you must include an acknowledgement: + "This product includes software written by Tim Hudson (tjh@mincom.oz.au)" + +THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +The licence and distribution terms for any publically available version or +derivative of this code cannot be changed. i.e. this code cannot simply be +copied and put under another distribution licence +[including the GNU Public Licence.] + +Portions Copyright (C) 1988 by Leslie Lamport. + +Portions Copyright (c) 1998 Free Software Foundation, Inc. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, distribute with modifications, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, +DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR +OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR +THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Except as contained in this notice, the name(s) of the above copyright +holders shall not be used in advertising or otherwise to promote the +sale, use or other dealings in this Software without prior written +authorization. + +Portions Copyright 1989-2000 by Norman Ramsey. All rights reserved. + +Noweb is protected by copyright. It is not public-domain +software or shareware, and it is not protected by a ``copyleft'' +agreement like the one used by the Free Software Foundation. + +Noweb is available free for any use in any field of endeavor. You may +redistribute noweb in whole or in part provided you acknowledge its +source and include this COPYRIGHT file. You may modify noweb and +create derived works, provided you retain this copyright notice, but +the result may not be called noweb without my written consent. + +You may sell noweb if you wish. For example, you may sell a CD-ROM +including noweb. + +You may sell a derived work, provided that all source code for your +derived work is available, at no additional charge, to anyone who buys +your derived work in any form. You must give permisson for said +source code to be used and modified under the terms of this license. +You must state clearly that your work uses or is based on noweb and +that noweb is available free of change. You must also request that +bug reports on your work be reported to you. + +Portions Copyright (c) 1987 The RAND Corporation. All rights reserved. + +Portions Copyright 1988-1995 by Stichting Mathematisch Centrum, Amsterdam, The +Netherlands. + + All Rights Reserved + +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the names of Stichting Mathematisch +Centrum or CWI not be used in advertising or publicity pertaining to +distribution of the software without specific, written prior permission. + +STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO +THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE +FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +Portions Copyright (c) Renaud Rioboo and the University Paris 6. + +Portions Copyright (c) 2003-2009 Jocelyn Guidry + +Portions Copyright (c) 2001-2009 Timothy Daly + +@ \section{Functions} \defun{copyright}{copyright} <>= (defun |copyright| () - (obey (strconc "cat " (getenviron "AXIOM") "/lib/copyright"))) + (obey (strconc "cat " (getenviron "AXIOM") "/doc/spadhelp/spadhelp.help"))) @ @@ -2649,101 +4088,87 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{display} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{verbatim} - )display abbreviations - )display abbreviations [obj] - )display all - )display macros - )display mode all - )display mode [obj1 [obj2 ...]] - )display names - )display operations opname - )display properties - )display properties all - )display properties [obj1 [obj2 ...]] - )display value all - )display value [obj1 [obj2 ...]] -\end{verbatim} - -This command is used to display the contents of the workspace and -signatures of functions with a given name. A signature gives the -argument and return types of a function. - -The command -\begin{verbatim} - )display abbreviations - )display abbreviations [obj] -\end{verbatim} -will show all of the abbreviations in the current workspace. - -The command -\begin{verbatim} - )display all -\end{verbatim} -is equivalent to -\begin{verbatim} - )display properties -\end{verbatim} - -The command -\begin{verbatim} - )display macros -\end{verbatim} -will show all of the macros in the current workspace. - +<>= +==================================================================== +A.8. )display +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )display all + - )display properties + - )display properties all + - )display properties [obj1 [obj2 ...]] + - )display value all + - )display value [obj1 [obj2 ...]] + - )display mode all + - )display mode [obj1 [obj2 ...]] + - )display names + - )display operations opName + +Command Description: + +This command is used to display the contents of the workspace and signatures +of functions with a given name. (A 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. - -To just show the declared mode of ``d'', issue -\begin{verbatim} - )display mode d -\end{verbatim} - -All modemaps for a given operation may be displayed by using -\begin{verbatim} - )display operations -\end{verbatim} - -A 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 {\bf complex}: -\begin{verbatim} - )d op complex -\end{verbatim} - -In addition to the modemaps for an operation the request to display -an operation will be followed by examples of the operation from each -domain. - + +)display names + +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 ``d'', issue -\begin{verbatim} - )display properties d -\end{verbatim} + +)display all +)display properties +)display properties all + +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 d, issue + +)display properties d + +To just show the value (and the type) of d, issue + +)display value d + +To just show the declared mode of d, issue + +)display mode d + +All modemaps for a given operation may be displayed by using )display +operations. A 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 FromcomplexComplexCategory: + +)d op complex + +Also See: +o )clear +o )history +o )set +o )show +o )what + +@ +\footnote{ +\fnref{clear} +\fnref{history} +\fnref{set} +\fnref{show} +\fnref{what}} -To just show the value (and the type) of ``d'', issue -\begin{verbatim} - )display value d -\end{verbatim} -\section{Variables Used} \defdollar{displayOptions} The current value of \$displayOptions is <>= @@ -3006,62 +4431,57 @@ next brace but the problem does not arise in practice. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{edit} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )edit} \lanb{}{\it filename}\ranb{} -\end{list} -\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} +<>= +==================================================================== +A.9. )edit +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )edit [filename] + +Command Description: + +This command is used to edit files. It works in conjunction with the )read +and )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 + )edit /u/julius/matrix.input -\end{verbatim} -will place you in an editor looking at the file -{\tt /u/julius/matrix.input}. -\index{editing files} -By default, the editor is {\tt vi}, -\index{vi} -but if you have an EDITOR shell environment variable defined, that editor -will be used. -When Axiom 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. -\index{Korn shell} -For example, under the Korn shell, if you issue -\begin{verbatim} + +will place you in an editor looking at the file /u/julius/matrix.input. By +default, the editor is vi, but if you have an EDITOR shell environment +variable defined, that editor will be used. When AXIOM is running under the X +Window System, it will try to open a separate xterm running your editor if it +thinks one is necessary. For example, under the Korn shell, if you issue + export EDITOR=emacs -\end{verbatim} -then the emacs -\index{emacs} -editor will be used by {\tt )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} + +then the emacs editor will be used by )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 )system command to edit a file directly. For +example, + )system emacs /etc/rc.tcpip -\end{verbatim} -calls {\tt emacs} to edit the file. -\index{emacs} - -\par\noindent{\bf Also See:} -\fnref{system}, -\fnref{compiler}, and -\fnref{read} + +calls emacs to edit the file. + +Also See: +o )system +o )compile +o )read + +@ +\footnote{ +\fnref{system} +\fnref{compile} +\fnref{read}} -\section{Variables Used} \section{Functions} \defun{edit}{edit} <>= @@ -3099,27 +4519,32 @@ calls {\tt emacs} to edit the file. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{fin} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +==================================================================== +A.10. )fin +==================================================================== + +User Level Required: development + +Command Syntax: + + - )fin + +Command Description: + +This command is used by AXIOM developers to leave the AXIOM system and return +to the underlying Lisp system. To return to AXIOM, issue the ``(|spad|)'' +function call to Lisp. + +Also See: +o )pquit +o )quit + +@ +\footnote{ +\fnref{pquit} +\fnref{quit}} -\par\noindent{\bf User Level Required:} development - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )fin} -\end{list} -\par\noindent{\bf Command Description:} - -This command is used by Axiom -developers to leave the Axiom system and return -to the underlying Common Lisp system. -To return to Axiom, issue the -``{\tt (\vertline{}spad\vertline{})}'' -function call to Common Lisp. - -\par\noindent{\bf Also See:} -\fnref{pquit} and -\fnref{quit} - -\section{Variables Used} \section{Functions} This command is in the list of \verb|$noParseCommands| @@ -3130,119 +4555,103 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{frame} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )frame new {\it frameName}} -\item{\tt )frame drop {\it [frameName]}} -\item{\tt )frame next} -\item{\tt )frame last} -\item{\tt )frame names} -\item{\tt )frame import {\it frameName} {\it [objectName1 [objectName2 ...]]}} -\item{\tt )set message frame on | off} -\item{\tt )set message prompt frame} -\end{list} - -\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 HyperDoc program and these can -have pretty strange names, since they are generated automatically. -\index{frame names} -To find out the names +<>= +==================================================================== +A.11. )frame +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )frame new frameName + - )frame drop [frameName] + - )frame next + - )frame last + - )frame names + - )frame import frameName [objectName1 [objectName2 ...]] + - )set message frame on | off + - )set message prompt frame + +Command Description: + +A 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 step number, environment and history. You can have a +variable named a in one frame and it will have nothing to do with anything +that might be called a in any other frame. + +Some frames are created by the HyperDoc program and these can have pretty +strange names, since they are generated automatically. 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 -\index{frame new} -``{\bf quark}'' by issuing -\begin{verbatim} + +You create a new frame ``quark'' by issuing + )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 Axiom 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 -\index{frame next} -``{\bf initial}'' frame, use -\index{frame last} -\begin{verbatim} + +The history facility can be turned on by issuing either )set history on or +)history )on. If the history facility is on and you are saving history +information in a file rather than in the AXIOM environment then a history +file with filename quark.axh will be created as you enter commands. If you +wish to go back to what you were doing in the ``initial'' frame, use + )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} + +to cycle through the ring of available frames to get back to ``initial''. + +If you want to throw away a frame (say ``quark''), issue + )frame drop quark -\end{verbatim} + If you omit the name, the current frame is dropped. -\index{frame drop} - -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. -\index{file!history} -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 -\index{frame import} -{\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} + +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. These are directories, so +you may want to issue a command like rm -r quark.axh to the operating system. + +You can bring things from another frame by using )frame import. For example, +to bring the f and g from the frame ``quark'' to the current frame, issue + )frame import quark f g -\end{verbatim} -If you want everything from the frame ``{\bf quark}'', issue -\begin{verbatim} + +If you want everything from the frame ``quark'', issue + )frame import quark -\end{verbatim} + You will be asked to verify that you really want everything. - -There are two {\tt )set} flags -\index{set message frame} -to make it easier to tell where you are. -\begin{verbatim} + +There are two )set flags to make it easier to tell where you are. + )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} + +will print more messages about frames when it is set on. By default, it is +off. + )set message prompt frame -\end{verbatim} -will give a prompt -\index{set message prompt frame} -that looks like -\begin{verbatim} + +will give a prompt that looks like + initial (1) -> -\end{verbatim} -\index{prompt!with frame name} -when you start up. In this case, the frame name and step make up the -prompt. - -\par\noindent{\bf Also See:} -\fnref{history} and -\fnref{set} + +when you start up. In this case, the frame name and step make up the prompt. + +Also See: +o )history +o )set + +@ +\footnote{ +\fnref{history} +\fnref{set}} \section{Variables Used} The frame mechanism uses several dollar variables. @@ -3803,37 +5212,140 @@ S2IZ0079 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{help} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +==================================================================== +A.12. )help +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )help + - )help commandName + - )help syntax + +Command Description: + +This command displays help information about system commands. If you issue + +)help + +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, + +)help clear + +will display the description of the )clear system command. -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )help} -\item{\tt )help} {\it commandName} -\end{list} +The command -\par\noindent{\bf Command Description:} +)help syntax -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. +will give further information about the Axiom language syntax. + +All this material is available in the AXIOM User Guide and in HyperDoc. In +HyperDoc, choose the Commands item from the Reference menu. + +==================================================================== +A.1. Introduction +==================================================================== + + +System commands are used to perform AXIOM environment management. Among the +commands are those that display what has been defined or computed, set up +multiple logical AXIOM environments (frames), clear definitions, read files +of expressions and commands, show what functions are available, and terminate +AXIOM. + +Some commands are restricted: the commands + +)set userlevel interpreter +)set userlevel compiler +)set userlevel development + +set the user-access level to the three possible choices. All commands are +available at development level and the fewest are available at interpreter +level. The default user-level is interpreter. In addition to the )set command +(discussed in description of command )set ) you can use the HyperDoc settings +facility to change the user-level. Click on [Settings] 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 AXIOM or be +included in .input files. + +A system command argument is a word that directly follows the command name +and is not followed or preceded by a right parenthesis. A system command +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: + + )syscmd arg1 arg2 )opt1 opt1arg1 opt1arg2 )opt2 opt2arg1 ... + +In the system command descriptions, optional arguments and options are +enclosed in brackets (``['' and ``]''). 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 + +)read fileName [)quietly] + +would imply that you must provide an actual file name for fileName but need +not use the )quietly option. Thus + +)read matrix.input + +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 + +)s Integer + +is not a valid abbreviation for the )set command, because both )set and )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 ``|'' to indicate that you +must specify one of the listed choices. For example, in + +)set output fortran on | off + +only on and off are acceptable words for following 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. + +==================================================================== +Other help topics +==================================================================== +Available help topics are: + +abbreviations assignment blocks browse boot cd +clear clef close collection compile display +edit fin for frame help history +if iterate leave library lisp load +ltrace parallel pquit quit read repeat +savesystem set show spool suchthat synonym +system syntax trace undo what while + +Available algebra help topics are: -All this material is available in the Axiom User Guide -and in HyperDoc. -In HyperDoc, choose the {\bf Commands} item from the -{\bf Reference} menu. +@ -\section{Variables Used} \section{Functions} \defun{help}{help} <>= @@ -3889,187 +5401,150 @@ In HyperDoc, choose the {\bf Commands} item from the %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{history} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )history )on} -\item{\tt )history )off} -\item{\tt )history )write} {\it historyInputFileName} -\item{\tt )history )show [{\it n}] [both]} -\item{\tt )history )save} {\it savedHistoryName} -\item{\tt )history )restore} [{\it savedHistoryName}] -\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 | off} -\end{list} - -\par\noindent{\bf Command Description:} - -The {\it history} facility within Axiom 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 -\index{file!input} -Axiom. - -Axiom 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} +<>= +==================================================================== +A.13. )history +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )history )on + - )history )off + - )history )write historyInputFileName + - )history )show [n] [both] + - )history )save savedHistoryName + - )history )restore [savedHistoryName] + - )history )reset + - )history )change n + - )history )memory + - )history )file + - % + - %%(n) + - )set history on | off + +Command Description: + +The history facility within AXIOM 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 .input +file of the lines typed to AXIOM. + +AXIOM saves your input and output if the history facility is turned on (which +is the default). This information is saved if either of + )set history on )history )on -\end{verbatim} -has been issued. -Issuing either -\begin{verbatim} + +has been issued. Issuing either + )set history off )history )off -\end{verbatim} + will discontinue the recording of information. -\index{history )on} -\index{set history on} -\index{set history off} -\index{history )off} - -Whether the facility is disabled or not, -the value of {\tt \%} in Axiom always -refers to the result of the last computation. -If you have not yet entered anything, -{\tt \%} evaluates to an object of type -{\tt Variable('\%)}. -The function {\tt \%\%} 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, Axiom will signal an error. - -The {\it environment} information can either be saved in a file or entirely in -memory (the default). -Each frame -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. - -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: - -\begin{description} -\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}. -\index{history )change} - -\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 -Common Lisp system. -Like {\tt )history )change}, this option only has real effect when -history data is being saved in a file. - -\item[{\tt )restore} [{\it savedHistoryName}]] -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. - -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 -Axiom session) or last did a {\tt )clear all} or -{\tt )clear completely}. - -\item[{\tt )show} [{\it n}] [{\tt both}]] -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 Axiom process -the contents. -\end{description} - -\par\noindent{\bf Also See:} -{\tt )frame}, -{\tt )read}, -{\tt )set}, and -{\tt )undo} - + +Whether the facility is disabled or not, the value of % in AXIOM always +refers to the result of the last computation. If you have not yet entered +anything, % evaluates to an object of type Variable('%). The function %% may +be used to refer to other previous results if the history facility is +enabled. In that case, %%(n) is the output from step n if n > 0. If n < 0, +the step is computed relative to the current step. Thus %%(-1) is also the +previous step, %%(-2), is the step before that, and so on. If an invalid step +number is given, AXIOM will signal an error. + +The environment information can either be saved in a file or entirely in +memory (the default). Each frame ( description of command )frame ) 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 FRAME.axh where ``FRAME'' is the name of the +current frame. The history file is placed in the current working directory +(see description of command )cd ). 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 )history command are as follows: + + )change n + will set the number of steps that are saved in memory to n. This option + only has effect when the history data is maintained in a file. If you + have issued )history )memory (or not changed the default) there is no + need to use )history )change. + + )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 )set history on. + + )off + will stop the recording of information. The )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 )set + history off. + + )file + indicates that history data should be saved in an external file on disk. + + )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. + + )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 )history )change, this option only has real effect when + history data is being saved in a file. + + )restore [savedHistoryName] + completely clears the environment and restores it to a saved session, if + possible. The )save option below allows you to save a session to a file + with a given name. If you had issued )history )save jacobi the command + )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 last.axh. + + )save savedHistoryName + is used to save a snapshot of the environment in a file. This file is + placed in the current working directory (see description of command )cd + ). Use )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 AXIOM session) or last did a )clear all or + )clear completely. + + )show [n] [both] + can show previous input lines and output results. )show will display up + to twenty of the last input lines (fewer if you haven't typed in twenty + lines). )show n will display up to n of the last input lines. )show both + will display up to five of the last input lines and output results. )show + n both will display up to n of the last input lines and output results. + + )write historyInputFile + creates an .input file with the input lines typed since the start of the + session/frame or the last )clear all or )clear completely. If + historyInputFileName does not contain a period (``.'') in the filename, + .input is appended to it. For example, )history )write chaos and )history + )write chaos.input both write the input lines to a file called + chaos.input in your current working directory. If you issued one or more + )undo commands, )history )write eliminates all input lines backtracked + over as a result of )undo. You can edit this file and then use )read to + have AXIOM process the contents. + +Also See: +o )frame +o )read +o )set +o )undo + +@ +\footnote{ +\fnref{frame} +\fnref{read} +\fnref{set} +\fnref{undo}} History recording is done in two different ways: \begin{itemize} @@ -5412,21 +6887,21 @@ S2IH0038 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{include} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= -\par\noindent{\bf User Level Required:} interpreter +User Level Required: interpreter -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )include {\it filename}} -\end{list} +Command Syntax: -\par\noindent{\bf Command Description:} + )include filename -The \verb|)include| command can be used in \verb|.input| files -to place the contents of another file inline with the current file. -The path can be an absolute or relative pathname. +Command Description: -\section{Variables Used} +The )include command can be used in .input files to place the contents +of another file inline with the current file. The path can be an +absolute or relative pathname. + +@ \section{Functions} \defun{ncloopInclude1}{ncloopInclude1} <>= @@ -5486,102 +6961,105 @@ token in the string. If the string only 0 or more blanks it returns nil. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{library} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\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{list} - -\par\noindent{\bf Command Description:} - -This command replaces the {\tt )load} system command that -was available in Axiom releases before version 2.0. -The {\tt )library} command makes available to Axiom 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 Axiom 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 +<>= +==================================================================== +A.14. )library +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )library libName1 [libName2 ...] + - )library )dir dirName + - )library )only objName1 [objlib2 ...] + - )library )noexpose + +Command Description: + +This command replaces the )load system command that was available in AXIOM +releases before version 2.0. The )library command makes available to AXIOM +the compiled objects in the libraries listed. + +For example, if you )compile dopler.as in your home directory, issue )library +dopler to have AXIOM 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 )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 NRLIB +present, for example, DOPLER.NRLIB, where DOPLER is a constructor +abbreviation. The command )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 {\tt )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, + +To tell the system about all libraries in a directory, use )library )dir +dirName where 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 )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 )only option. The command )library dopler +)only Test1 will only cause the Test1 constructor to be analyzed, autoloaded, etc.. + +Finally, each constructor in a library are usually automatically exposed when +the )library command is used. Use the )noexpose option if you not want them +exposed. At a later time you can use )set expose add constructor to expose +any hidden constructors. + +Note for AXIOM beta testers: At various times this command was called )local +and )with before the name )library became the official name. + +Also See: +o )cd +o )compile +o )frame +o )set + +@ +\footnote{ +\fnref{cd} +\fnref{compile} +\fnref{frame} +\fnref{set}} -Finally, each constructor in a library are usually automatically exposed when the -{\tt )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 Axiom 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:} -\fnref{cd}, -\fnref{compiler}, -\fnref{frame}, and -\fnref{set} - -\section{Variables Used} -\section{Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{lisp} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +==================================================================== +A.15. )lisp +==================================================================== + +User Level Required: development + +Command Syntax: + + - )lisp [lispExpression] + +Command Description: + +This command is used by AXIOM system developers to have single expressions +evaluated by the Lisp system on which AXIOM is built. The 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 )fin +command may be used to drop out of AXIOM into Lisp. + +Also See: +o )system +o )boot +o )fin + +@ +\footnote{ +\fnref{system} +\fnref{boot} +\fnref{fin}} -\par\noindent{\bf User Level Required:} development - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )lisp} {\it\lanb{}lispExpression\ranb{}} -\end{list} - -\par\noindent{\bf Command Description:} - -This command is used by Axiom system developers to have single -expressions evaluated by the Common Lisp system on which -Axiom is built. -The {\it lispExpression} is read by the Common 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 Axiom into Common Lisp. - -\par\noindent{\bf Also See:} -\fnref{system}, -\fnref{boot}, and -\fnref{fin} - -\section{Variables Used} \section{Functions} This command is in the list of \verb|$noParseCommands| @@ -5592,96 +7070,107 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{load} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +==================================================================== +A.16. )load +==================================================================== + +User Level Required: interpreter + +Command Description: + +This command is obsolete. Use )library instead. + +@ -\par\noindent{\bf User Level Required:} interpreter -\par\noindent{\bf Command Description:} - -This command is obsolete. Use {\tt )library} instead. - -\section{Variables Used} -\section{Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{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:} -\fnref{boot}, -\fnref{lisp}, and -\fnref{trace} +<>= +==================================================================== +A.17. )ltrace +==================================================================== + +User Level Required: development + +Command Syntax: + +This command has the same arguments as options as the )trace command. + +Command Description: + +This command is used by AXIOM system developers to trace Lisp or BOOT +functions. It is not supported for general use. + +Also See: +o )boot +o )lisp +o )trace + +@ +\footnote{ +\fnref{boot} +\fnref{lisp} +\fnref{trace}} \section{Variables Used} \section{Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{pquit} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= +==================================================================== +A.18. )pquit +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )pquit + +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 )history )restore +command to try to restore your working environment, you cannot return to +AXIOM in the same state. + +)pquit differs from the )quit in that it always asks for confirmation that +you want to terminate AXIOM (the ``p'' is for ``protected''). When you enter +the )pquit command, AXIOM responds + + Please enter y or yes if you really want to leave the interactive + environment and return to the operating system: + +If you respond with y or yes, you will see the message + + You are now leaving the AXIOM interactive environment. + Issue the command axiom to the operating system to start a new session. + +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 y or yes, then the message + + You have chosen to remain in the AXIOM interactive environment. + +will be displayed and, indeed, AXIOM would still be running. + +Also See: +o )fin +o )history +o )close +o )quit +o )system + +@ +\footnote{ +\fnref{fin} +\fnref{history} +\fnref{close} +\fnref{quit} +\fnref{system}} -\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:} -\fnref{fin}, -\fnref{history}, -\fnref{close}, -\fnref{quit}, and -\fnref{system} - -\section{Variables Used} \section{Functions} \defun{pquit}{pquit} <>= @@ -5706,55 +7195,56 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{quit} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )quit} -\item{\tt )set quit protected \vertline{} unprotected} -\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 )quit} differs from the {\tt )pquit} in that it asks for -\index{pquit} -confirmation only if the command -\begin{verbatim} +<>= +==================================================================== +A.19. )quit +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )quit + - )set quit protected | unprotected + +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 )history )restore +command to try to restore your working environment, you cannot return to +AXIOM in the same state. + +)quit differs from the )pquit in that it asks for confirmation only if the +command + )set quit protected -\end{verbatim} -has been issued. -\index{set quit protected} -Otherwise, {\tt )quit} will make Axiom 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} + +has been issued. Otherwise, )quit will make AXIOM terminate and return you to +the operating system (or the environment from which you invoked the system). + +The default setting is )set quit protected so that )quit and )pquit behave in +the same way. If you do issue + )set quit unprotected -\end{verbatim} -we -\index{set quit unprotected} -suggest that you do not (somehow) assign {\tt )quit} to be -executed when you press, say, a function key. - -\par\noindent{\bf Also See:} -\fnref{fin}, -\fnref{history}, -\fnref{close}, -\fnref{pquit}, and -\fnref{system} + +we suggest that you do not (somehow) assign )quit to be executed when you +press, say, a function key. + +Also See: +o )fin +o )history +o )close +o )pquit +o )system + +@ +\footnote{ +\fnref{fin} +\fnref{history} +\fnref{close} +\fnref{pquit} +\fnref{system}} -\section{Variables Used} \section{Functions} \defun{quit}{quit} <>= @@ -5789,70 +7279,76 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{read} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )read} {\it \lanb{}fileName\ranb{}} -\item {\tt )read} {\it \lanb{}fileName\ranb{}} \lanb{}{\tt )quiet}\ranb{} \lanb{}{\tt )ifthere}\ranb{} -\end{list} -\par\noindent{\bf Command Description:} - -This command is used to read {\bf .input} files into Axiom. -\index{file!input} -The command -\begin{verbatim} +<>= +==================================================================== +A.20. )read +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )read [fileName] + - )read [fileName] [)quiet] [)ifthere] + +Command Description: + +This command is used to read .input files into AXIOM. The command + )read matrix.input -\end{verbatim} -will read the contents of the file {\bf matrix.input} into -Axiom. -The ``.input'' file extension is optional. - -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:} -\fnref{compiler}, -\fnref{edit}, and -\fnref{history} + +will read the contents of the file matrix.input into AXIOM. The ``.input'' +file extension is optional. See the AXIOM User Guide index for more +information about .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 )ifthere option checks to see whether the .input file exists. If it does +not, the )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 .input +file. + +The )quiet option suppresses output while the file is being read. + +Also See: +o )compile +o )edit +o )history + +@ +\footnote{ +\fnref{compile} +\fnref{edit} +\fnref{history}} -\section{Variables Used} -\section{Functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{savesystem} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter +<>= +==================================================================== +A.8. )savesystem +==================================================================== -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )savesystem filename} -\end{list} -\par\noindent{\bf Command Description:} +User Level Required: interpreter + + +Command Syntax: -This command is used to save an AXIOM image to disk. This creates an + - )savesystem filename + +Command Description: + + This command is used to save an AXIOM image to disk. This creates an executable file which, when started, has everything loaded into it that was there when the image was saved. Thus, after executing commands which cause the loading of some packages, the command: -\begin{verbatim} )savesystem /tmp/savesys -\end{verbatim} will create an image that can be restarted with the UNIX command: -\begin{verbatim} axiom -ws /tmp/savesys -\end{verbatim} This new system will not need to reload the packages and domains that were already loaded when the system was saved. @@ -5860,74 +7356,67 @@ were already loaded when the system was saved. There is currently a restriction that only systems started with the command "AXIOMsys" may be saved. -\section{Variables Used} -\section{Functions} +@ + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{set} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )set} -\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{}} -\item {\tt )set} {\it label1 \lanb{}... labelN\ranb{} newValue} -\end{list} -\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 Axiom 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 Axiom working environment. -There is a HyperDoc version of this same facility available from the -main HyperDoc menu. - - -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} +<>= +==================================================================== +A.21. )set +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )set + - )set label1 [... labelN] + - )set label1 [... labelN] newValue + +Command Description: + +The )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 AXIOM 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 )set options to +familiarize yourself with how you can modify your AXIOM working environment. +There is a HyperDoc version of this same facility available from the main +HyperDoc menu. Click [here] to go to it. + +The )set command is command-driven with a menu display. It is +tree-structured. To see all top-level nodes, issue )set by itself. + )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} + +Variables with values have them displayed near the right margin. Subtrees of +selections have ``...'' displayed in the value field. For example, there are +many kinds of messages, so issue )set message to see the choices. + )set message -\end{verbatim} -The current setting for the variable that displays -\index{computation timings!displaying} -whether computation times -\index{timings!displaying} -are displayed is visible in the menu displayed by the last command. -To see more information, issue -\begin{verbatim} + +The current setting for the variable that displays whether computation times +are displayed is visible in the menu displayed by the last command. To see +more information, issue + )set message time -\end{verbatim} -This shows that time printing is on now. -To turn it off, issue -\begin{verbatim} + +This shows that time printing is on now. To turn it off, issue + )set message time off -\end{verbatim} -\index{set message time} - -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} + +As noted above, not all settings have so many qualifiers. For example, to +change the )quit command to being unprotected (that is, you will not be +prompted for verification), you need only issue + )set quit unprotected -\end{verbatim} -\index{set quit unprotected} + +Also See: +o )quit -\par\noindent{\bf Also See:} -\fnref{quit} +@ +\footnote{\fnref{quit}} \section{Overview} This section contains tree of information used to initialize the {\bf )set} @@ -10741,159 +12230,192 @@ which gets called with \verb|%describe%| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{show} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item {\tt )show {\it nameOrAbbrev}} -\item {\tt )show {\it nameOrAbbrev} )operations} -\item {\tt )show {\it nameOrAbbrev} )attributes} -\end{list} - -\par\noindent{\bf Command Description:} -This command displays information about Axiom -domain, package and category {\it constructors}. -If no options are given, the {\tt )operations} option is assumed. -For example, -\begin{verbatim} +<>= +==================================================================== +A.22. )show +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )show nameOrAbbrev + - )show nameOrAbbrev )operations + - )show nameOrAbbrev )attributes + +Command Description: +This command displays information about AXIOM domain, package and category +constructors. If no options are given, the )operations option is assumed. For +example, + )show POLY )show POLY )operations )show Polynomial )show Polynomial )operations -\end{verbatim} -each display basic information about the -{\tt Polynomial} domain constructor and then provide a -listing of operations. -Since {\tt Polynomial} requires a {\tt Ring} (for example, -{\tt Integer}) as argument, the above commands all refer -to a unspecified ring {\tt R}. -In the list of operations, {\tt \$} means -{\tt 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} + +each display basic information about the Polynomial domain constructor and +then provide a listing of operations. Since Polynomial requires a Ring (for +example, Integer) as argument, the above commands all refer to a unspecified +ring R. In the list of operations, $ means Polynomial(R). + +The basic information displayed includes the signature of the constructor +(the name and arguments), the constructor abbreviation, the exposure status +of the constructor, and the name of the 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, + )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 {\tt Polynomial(Integer)} (as opposed to the general -{\it domain constructor} {\tt Polynomial}). -Attributes may be listed by using the {\tt )attributes} option. - -\par\noindent{\bf Also See:} -\fnref{display}, -\fnref{set}, and -\fnref{what} + +are among the combinations that will display the operations exported by the +domain Polynomial(Integer) (as opposed to the general domain constructor +Polynomial). Attributes may be listed by using the )attributes option. + +Also See: +o )display +o )set +o )what + +@ +\footnote{ +\fnref{display} +\fnref{set} +\fnref{what}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{spool} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )spool} \lanb{}{\it fileName}\ranb{} -\item{\tt )spool} -\end{list} - -\par\noindent{\bf Command Description:} - -This command is used to save {\it (spool)} all Axiom input and output -\index{file!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} +<>= +==================================================================== +A.23. )spool +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )spool [fileName] + - )spool + +Command Description: + +This command is used to save (spool) all AXIOM input and output into a file, +called a spool file. You can only have one spool file active at a time. To +start spool, issue this command with a filename. For example, + )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 -\index{directory!for spool files} -{\it current directory.} -The current directory is the directory from which you started -Axiom or is the directory you specified using the -{\tt )cd} command. -\index{cd} - -\par\noindent{\bf Also See:} -\fnref{cd} + +To stop spooling, issue )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 current directory. The current directory is the directory +from which you started AXIOM or is the directory you specified using the )cd +command. + +Also See: +o )cd + +@ +\footnote{\fnref{cd}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{summary} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= + )credits : list the people who have contributed to Axiom + + )help gives more information + )quit : exit AXIOM + + )abbreviation : query, set and remove abbreviations for constructors + )cd : set working directory + )clear : remove declarations, definitions or values + )close : throw away an interpreter client and workspace + )compile : invoke constructor compiler + )display : display Library operations and objects in your workspace + )edit : edit a file + )frame : manage interpreter workspaces + )history : manage aspects of interactive session + )library : introduce new constructors + )lisp : evaluate a LISP expression + )read : execute AXIOM commands from a 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 + )trace : trace execution of functions + )undo : restore workspace to earlier state + )what : search for various things by name +@ \defun{summary}{summary} <>= (defun |summary| (l) (declare (ignore l)) - (obey (strconc "cat " (getenviron "AXIOM") "/lib/summary"))) + (obey (strconc "cat " (getenviron "AXIOM") "/doc/spadhelp/summary.help"))) @ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{synonym} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )synonym} -\item{\tt )synonym} {\it synonym fullCommand} -\item{\tt )what synonyms} -\end{list} - -\par\noindent{\bf Command Description:} - +<>= +==================================================================== +A.24. )synonym +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )synonym + - )synonym synonym fullCommand + - )what synonyms + +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} +For example, the following synonyms might simplify commands you often use. + )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} + +Once defined, synonyms can be used in place of the longer command +expressions. Thus + )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} + +To list, say, all synonyms that contain the substring ``ap'', issue + )what synonyms ap -\end{verbatim} - -\par\noindent{\bf Also See:} -\fnref{set} and -\fnref{what} + +Also See: +o )set +o )what + +@ +\footnote{ +\fnref{set} +\fnref{what}} This command is in the list of \verb|$noParseCommands| \ref{noParseCommands} which means that its arguments are passed @@ -10903,45 +12425,48 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{system} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )system} {\it cmdExpression} -\end{list} - -\par\noindent{\bf Command Description:} - +<>= +==================================================================== +A.25. )system +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )system cmdExpression + +Command Description: + This command may be used to issue commands to the operating system while -remaining in Axiom. -The {\it cmdExpression} is passed to the operating system for +remaining in AXIOM. The cmdExpression is passed to the operating system for execution. - -To get an operating system shell, issue, for example, -{\tt )system sh}. -When you enter the key combination, -\fbox{\bf Ctrl}--\fbox{\bf D} -(pressing and holding the -\fbox{\bf Ctrl} key and then pressing the -\fbox{\bf D} key) -the shell will terminate and you will return to Axiom. -We do not recommend this way of creating a shell because -Common Lisp may field some interrupts instead of the shell. -If possible, use a shell running in another window. - + +To get an operating system shell, issue, for example, )system sh. When you +enter the key combination, Ctrl-D (pressing and holding the Ctrl key and then +pressing the D key) the shell will terminate and you will return to AXIOM. 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 -Axiom. -If this happens, you may have no other choice than to restart -Axiom and restore the environment via {\tt )history )restore}, if -possible. - -\par\noindent{\bf Also See:} -\fnref{boot}, -\fnref{fin}, -\fnref{lisp}, -\fnref{pquit}, and -\fnref{quit} +AXIOM. If this happens, you may have no other choice than to restart AXIOM +and restore the environment via )history )restore, if possible. + +Also See: +o )boot +o )fin +o )lisp +o )pquit +o )quit + +@ +\footnote{ +\fnref{boot} +\fnref{fin} +\fnref{lisp} +\fnref{pquit} +\fnref{quit}} This command is in the list of \verb|$noParseCommands| \ref{noParseCommands} which means that its arguments are passed @@ -10951,291 +12476,229 @@ verbatim. This will eventually result in a call to the function %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{trace} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\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{list} -% +<>= +==================================================================== +A.26. )trace +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )trace + - )trace )off + + - )trace function [options] + - )trace constructor [options] + - )trace domainOrPackage [options] + where options can be one or more of -% -\begin{list}{} -\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{list} - -\par\noindent{\bf Command Description:} - -This command is used to trace the execution of functions that make -up the Axiom system, functions defined by users, -and functions from the system library. -Almost all options are available for each type of function but + + - )after S-expression + - )before S-expression + - )break after + - )break before + - )cond S-expression + - )count + - )count n + - )depth n + - )local op1 [... opN] + - )nonquietly + - )nt + - )off + - )only listOfDataToDisplay + - )ops + - )ops op1 [... opN ] + - )restore + - )stats + - )stats reset + - )timer + - )varbreak + - )varbreak var1 [... varN ] + - )vars + - )vars var1 [... varN ] + - )within executingFunction + +Command Description: + +This command is used to trace the execution of functions that make up the +AXIOM 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} + +To list all functions, constructors, domains and packages that are traced, +simply issue + )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 Axiom 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} + +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 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 AXIOM 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 )trace. Any options that are present must follow the functions to +be traced. + )trace f -\end{verbatim} -traces the function {\tt f}. -To untrace {\tt f}, issue -\begin{verbatim} + +traces the function f. To untrace f, issue + )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} + +Note that if a function name contains a special character, it will be +necessary to escape the character with an underscore + )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} + +To trace all domains or packages that are or will be created from a +particular constructor, give the constructor name or abbreviation after +)trace. + )trace MATRIX )trace List Integer -\end{verbatim} -% -The first command traces all domains currently instantiated with -{\tt Matrix}. -If additional domains are instantiated with this constructor -(for example, if you have used {\tt Matrix(Integer)} and -{\tt Matrix(Float)}), they will be automatically traced. -The second command traces {\tt 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 -\begin{description} -%\item[{\tt )after} {\it S-expression}] -%causes the given Common Lisp {\it S-expression} to be -%executed after exiting the traced function. - -%\item[{\tt )before} {\it S-expression}] -%causes the given Common Lisp {\it S-expression} to be -%executed before entering the traced function. - -\item[{\tt )break after}] -causes a Common Lisp break loop to be entered after -exiting the traced function. - -\item[{\tt )break before}] -causes a Common Lisp break loop to be entered before -entering the traced function. - -\item[{\tt )break}] -is the same as {\tt )break before}. - -%\item[{\tt )cond} {\it S-expression}] -%causes trace information to be shown only if the given -%Common 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 \it n-th 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 {\bf fib}. - -\item[{\tt )math}] -causes the function arguments and return value to be displayed in the -Axiom 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: -\begin{description} -\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 -\end{description} -\end{description} -\begin{description} - -\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 Common 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 Common 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 -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 -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. -\end{description} - -The following are the options for tracing constructors, domains -and packages. - -\begin{description} -\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 -{\tt \_} 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 {\tt Integer}. Since -{\tt +} and {\tt -} are special -characters, it is necessary -to escape them with an underscore. -\end{description} - -\par\noindent{\bf Also See:} -\fnref{boot}, -\fnref{lisp}, and -\fnref{ltrace} + +The first command traces all domains currently instantiated with Matrix. If +additional domains are instantiated with this constructor (for example, if +you have used Matrix(Integer) and Matrix(Float)), they will be automatically +traced. The second command traces List(Integer). It is possible to trace +individual functions in a domain or package. See the )ops option below. + +The following are the general options for the )trace command. + + )break after + causes a Lisp break loop to be entered after exiting the traced function. + + )break before + causes a Lisp break loop to be entered before entering the traced + function. + + )break + is the same as )break before. + + )count + causes the system to keep a count of the number of times the traced + function is entered. The total can be displayed with )trace )stats and + cleared with )trace )stats reset. + + )count n + causes information about the traced function to be displayed for the + first n executions. After the nth execution, the function is untraced. + + )depth n + causes trace information to be shown for only n levels of recursion of + the traced function. The command + + )trace fib )depth 10 + + will cause the display of only 10 levels of trace information for the + recursive execution of a user function fib. + + )math + causes the function arguments and return value to be displayed in the + AXIOM monospace two-dimensional math format. + + )nonquietly + causes the display of additional messages when a function is traced. + + )nt + This suppresses all normal trace information. This option is useful if + the )count or )timer options are used and you are interested in the + statistics but not the function calling information. + + )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 )trace )restore. + + )only listOfDataToDisplay + causes only specific trace information to be shown. The items are listed + by using the following abbreviations: + + a display all arguments + v display return value + 1 display first argument + 2 display second argument + 15 display the 15th argument, and so on + + )restore + causes the last untraced functions to be retraced. If additional options + are present, they are added to those previously in effect. + + )stats + causes the display of statistics collected by the use of the )count and + )timer options. + + )stats reset + resets to 0 the statistics collected by the use of the )count and )timer + options. + + )timer + causes the system to keep a count of execution times for the traced + function. The total can be displayed with )trace )stats and cleared with + )trace )stats reset. + + )varbreak var1 [... varN] + causes a Lisp break loop to be entered after the assignment to any of the + listed variables in the traced function. + + )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 + description of command )compile ) using the )vartrace option in order to + support this option. + + )vars var1 [... varN] + 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 description of command )compile ) using the + )vartrace option in order to support this option. + + )within executingFunction + causes the display of trace information only if the traced function is + called when the given executingFunction is running. + +The following are the options for tracing constructors, domains and packages. + + )local [op1 [... opN]] + 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 _ before the semicolon. + + )trace FRAC )local + )trace FRAC_;cancelGcd )off + + )ops op1 [... opN] + 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 + + )trace Integer )ops min max _+ _- + + traces four operations from the domain Integer. Since + and - are special + characters, it is necessary to escape them with an underscore. + +Also See: +o )boot +o )lisp +o )ltrace + +@ +\footnote{ +\fnref{boot} +\fnref{lisp} +\fnref{ltrace}} \subsection{The trace global variables} This decides when to give trace and untrace messages. @@ -13238,77 +14701,69 @@ to convert the data into type "Expression" %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{undo} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\item{\tt )undo} -\item{\tt )undo} {\it integer} -\item{\tt )undo} {\it integer [option]} -\item{\tt )undo} {\tt )redo} -\end{list} -% -where {\it option} is one of -% -\begin{list}{} -\item{\tt )after} -\item{\tt )before} -\end{list} - -\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} +<>= +==================================================================== +A.27. )undo +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )undo + - )undo integer + - )undo integer [option] + - )undo )redo + +where option is one of + + - )after + - )before + +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 )undo is an +integer which must designate some step number in the interactive session. + )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 \tt n-th -previous command (that is, undoes the effects of the last $-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 $n$ and -$n + 1$ ($n > 0$), their effect is undone -for {\tt )undo m} for any $0 < m \leq 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} + +These commands return the state of the interactive environment to that +immediately after step n. If n is a positive number, then n refers to step +nummber n. If n is a negative number, it refers to the nth previous command +(that is, undoes the effects of the last -n commands). + +A )clear all resets the )undo facility. Otherwise, an )undo undoes the effect +of )clear with options properties, value, and mode, and that of a previous +undo. If any such system commands are given between steps n and n + 1 (n > +0), their effect is undone for )undo m for any 0 < m <= n . + +The command )undo is equivalent to )undo -1 (it undoes the effect of the +previous user expression). The command )undo 0 undoes any of the above system +commands issued since the last user expression. + )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} + +This command returns the state of the interactive environment to that +immediately before step n. Any )undo or )clear system commands given before +step n will not be undone. + )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}. + +This command reads the file redo.input. created by the last )undo command. +This file consists of all user input lines, excluding those backtracked over +due to a previous )undo. + +The command )history )write will eliminate the ``undone'' command lines of +your program. -\par\noindent{\bf Also See:} \fnref{history} +Also See: +o )history + +@ +\footnote{\fnref{history}} -The command {\tt )history )write} will eliminate the ``undone'' command -lines of your program. -\section{Variables Used} \section{Data Structures} \verb|$frameRecord = [delta1, delta2,... ]| where delta(i) contains changes in the ``backwards'' direction. @@ -13909,96 +15364,89 @@ Removing undo lines from \verb|)hist )write linelist| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{what} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\par\noindent{\bf User Level Required:} interpreter - -\par\noindent{\bf Command Syntax:} -\begin{list}{} -\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{list} - -\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} +<>= +==================================================================== +A.28. )what +==================================================================== + +User Level Required: interpreter + +Command Syntax: + + - )what categories pattern1 [pattern2 ...] + - )what commands pattern1 [pattern2 ...] + - )what domains pattern1 [pattern2 ...] + - )what operations pattern1 [pattern2 ...] + - )what packages pattern1 [pattern2 ...] + - )what synonym pattern1 [pattern2 ...] + - )what things pattern1 [pattern2 ...] + - )apropos pattern1 [pattern2 ...] + +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, + )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} + +displays all command synonyms containing the substring ``ver'', + )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} + +displays all command synonyms containing the substring ``ver'' or the +substring ``pr''. Output similar to the following will be displayed + ---------------- 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: - -\begin{description} -\item[{\tt categories}] displays a list of category constructors. -\index{what categories} -\item[{\tt commands}] displays a list of system commands available at your -user-level. -\index{what commands} -Your user-level -\index{user-level} -is set via the {\tt )set userlevel} command. -\index{set userlevel} -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. -\index{what domains} -\item[{\tt operations}] displays a list of operations in the system library. -\index{what operations} -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. -\index{what packages} -\item[{\tt synonym}] lists system command synonyms. -\index{what synonym} -\item[{\tt things}] displays all of the above types for items containing -\index{what things} -the pattern strings as substrings. -The command synonym {\tt )apropos} is equivalent to -\index{apropos} -{\tt )what things}. -\end{description} - -\par\noindent{\bf Also See:} -\fnref{display}, -\fnref{set}, and -\fnref{show} + +Several other things can be listed with the )what command: + + categories displays a list of category constructors. + commands displays a list of system commands available at your + user-level. Your user-level is set via the )set userlevel command. To get + a description of a particular command, such as ``)what'', issue )help + what. + domains displays a list of domain constructors. + operations displays a list of operations in the system library. + 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 )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 )clear all or )clear completely. It will be re-created if it is + needed again. + packages displays a list of package constructors. + synonym lists system command synonyms. + things displays all of the above types for items containing + the pattern strings as substrings. The command synonym )apropos is + equivalent to )what things. + +Also See: +o )display +o )set +o )show + +@ +\footnote{ +\fnref{display} +\fnref{set} +\fnref{show}} \defdollar{whatOptions} <>= @@ -14179,8 +15627,16 @@ This displays all operation names containing these fragments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \cmdhead{with} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +<>= + +This command is obsolete. +This has been renamed )library. -; )library top level command -- soon to be obsolete +See also: +o )library + +@ +\footnote{\fnref{library}} \defun{with}{with} <>= diff --git a/changelog b/changelog index 45c8aba..e6e1ddb 100644 --- a/changelog +++ b/changelog @@ -1,3 +1,9 @@ +20090408 tpd src/axiom-website/patches.html 20090408.01.tpd.patch +20090408 tpd src/interp/Makefile move help to bookvol5 +20090408 tpd src/doc/spadhelp removed, move help to bookvol5 +20090408 tpd src/doc/Makefile move help to bookvol5 +20090408 tpd src/algebra/Makefile move help to bookvol5 +20090408 tpd books/bookvol5 move help to bookvol5 20090407 tpd src/axiom-website/patches.html 20090407.01.tpd.patch 20090407 tpd src/doc/bookvol4 removed, rewritten as book/bookvol4 20090407 tpd src/doc/bookvol1.pdf removed, regenerated during build diff --git a/src/algebra/Makefile.pamphlet b/src/algebra/Makefile.pamphlet index d826254..53608a2 100644 --- a/src/algebra/Makefile.pamphlet +++ b/src/algebra/Makefile.pamphlet @@ -16429,7 +16429,7 @@ make to process this file. This keeps the regression test list in the algebra Makefile. <>= -HELPFILE=${INT}/doc/help.helplist +HELPFILE=${HELP}/help.help SPADHELP=\ ${HELP}/ApplicationProgramInterface.help \ @@ -17839,6 +17839,7 @@ ${HELP}/ZeroDimensionalSolvePackage.help: ${BOOKS}/bookvol10.4.pamphlet @${TANGLE} -R"ZeroDimensionalSolvePackage.input" \ ${BOOKS}/bookvol10.4.pamphlet \ >${INPUT}/ZeroDimensionalSolvePackage.input + @echo "ZeroDimensionalSolvePackage (ZDSOLVE)" >>${HELPFILE} @ diff --git a/src/axiom-website/patches.html b/src/axiom-website/patches.html index 8d8ddfd..0d6084e 100644 --- a/src/axiom-website/patches.html +++ b/src/axiom-website/patches.html @@ -1054,5 +1054,7 @@ index.html Axiom on Windows as html
bookvol5 add )set debug
20090407.01.tpd.patch src/doc remove unused files
+20090408.01.tpd.patch +bookvol5 collect help files
diff --git a/src/doc/Makefile.pamphlet b/src/doc/Makefile.pamphlet index e31c290..363b45a 100644 --- a/src/doc/Makefile.pamphlet +++ b/src/doc/Makefile.pamphlet @@ -94,31 +94,6 @@ ${INT}/booklet.c: ${IN}/booklet.c.pamphlet ${TANGLE} ${IN}/booklet.c.pamphlet >booklet.c ) @ -\section{The )help files} -This list is the same as the list at the end of the help section -in spadhelp.pamphlet. -<>= -SPADHELP=\ -abbreviations assignment boot blocks cd clear \ -clef close collection compile display edit \ -fin for frame help history if \ -iterate leave library lisp load ltrace \ -parallel pquit quit read repeat savesystem \ -set show spool suchthat synonym system \ -syntax trace undo what while - -@ -<>= -${DVI}/spadhelp/spadhelp.files: ${IN}/spadhelp.pamphlet - @echo 9 making ${DVI}/spadhelp from ${IN}/spadhelp.pamphlet - @(cd ${DVI}/spadhelp ; \ - for i in ${SPADHELP} ; do \ - ${TANGLE} -R"$$i" ${IN}/spadhelp.pamphlet >$$i.help ; \ - done ; \ - cat ${INT}/doc/help.helplist >>help.help ; \ - ls *.help >spadhelp.files ) - -@ \section{The Makefile} We need to document the commands. <<*>>= @@ -130,12 +105,10 @@ DVI=${MNT}/${SYS}/doc DOC=${INT}/doc FILES= ${MID}/axiom.bib ${STY}/axiom.sty ${DVI}/refcard.dvi \ - ${DVI}/endpaper.dvi ${DVI}/rosetta.dvi ${DVI}/spadhelp/spadhelp.files + ${DVI}/endpaper.dvi ${DVI}/rosetta.dvi CMDS=${OUT}/booklet -<> - all: ${FILES} ${CMDS} @echo 9 finished ${IN} @@ -145,8 +118,6 @@ all: ${FILES} ${CMDS} <> <> <> -<> - document: @echo 10 documenting ${SRC}/doc diff --git a/src/doc/spadhelp.pamphlet b/src/doc/spadhelp.pamphlet deleted file mode 100644 index 351564b..0000000 --- a/src/doc/spadhelp.pamphlet +++ /dev/null @@ -1,3193 +0,0 @@ -\documentclass{article} -\usepackage{axiom} -\begin{document} -\title{\$SPAD/src/doc spadhelp} -\author{Timothy Daly} -\maketitle -\begin{abstract} -This is a collection of the help commands available to the Axiom -command line )help command. -\end{abstract} -\eject -\tableofcontents -\eject -\section{command abbreviations} -<>= -==================================================================== -A.2. )abbreviation -==================================================================== - -User Level Required: compiler - -Command Syntax: - - - )abbreviation query [nameOrAbbrev] - - )abbreviation category abbrev fullname [)quiet] - - )abbreviation domain abbrev fullname [)quiet] - - )abbreviation package abbrev fullname [)quiet] - - )abbreviation remove nameOrAbbrev - -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. 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 query argument, 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 all constructors are listed. - -The following shows the abbreviation for the constructor List: - -)abbreviation query List - -The following shows the constructor name corresponding to the abbreviation -NNI: - -)abbreviation query NNI - -The following lists all constructor names and their abbreviations. - -)abbreviation query - -To add an abbreviation for a constructor, use this command with category, -domain or package. The following add abbreviations to the system for a -category, domain and package, respectively: - -)abbreviation domain SET Set -)abbreviation category COMPCAT ComplexCategory -)abbreviation package LIST2MAP ListToMap - -If the )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 remove argument is used. 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 VECTOR2 and the constructor name VectorFunctions2 -from the system: - -)abbreviation remove VECTOR2 -)abbreviation remove VectorFunctions2 - -Also See: -o )compile - -@ - -\section{syntax assignment} -<>= - -Immediate, Delayed, and Multiple Assignment - -==================================================================== -Immediate Assignment -==================================================================== - -A variable in Axiom refers to a value. A variable has a name beginning -with an uppercase or lowercase alphabetic character, "%", or "!". -Successive characters (if any) can be any of the above, digits, or "?". -Case is distinguished. The following are all examples of valid, distinct -variable names: - - a tooBig? a1B2c3%!? - A %j numberOfPoints - beta6 %J numberofpoints - -The ":=" operator is the immediate assignment operator. Use it to -associate a value with a variable. The syntax for immediate assignment -for a single variable is: - - variable := expression - -The value returned by an immediate assignment is the value of expression. - - a := 1 - 1 - Type: PositiveInteger - -The right-hand side of the expression is evaluated, yielding 1. The value -is then assigned to a. - - b := a - 1 - Type: PositiveInteger - -The right-hand side of the expression is evaluated, yieldig 1. This value -is then assigned to b. Thus a and b both have the value 1 after the sequence -of assignments. - - a := 2 - 2 - Type: PositiveInteger - -What is the value of b if a is assigned the value 2? - - b - 1 - Type: PositiveInteger - -The value of b is left unchanged. - -This is what we mean when we say this kind of assignment is immediate. -The variable b has no dependency on a after the initial assignment. This -is the usual notion of assignment in programming languages such as C, -Pascal, and Fortran. - -==================================================================== -Delayed Assignment -==================================================================== - -Axiom provides delayed assignment with "==". This implements a delayed -evaluation of the right-hand side and dependency checking. The syntax for -delayed assignment is - - variable == expression - -The value returned by a delayed assignment is the unique value of Void. - - a == 1 - Type: Void - - b == a - Type: Void - -Using a and b as above, these are the corresponding delayed assignments. - - a - Compiling body of rule a to compute value of type PositiveInteger - 1 - Type: PositiveInteger - -The right-hand side of each delayed assignment is left unevaluated until -the variables on the left-hand sides are evaluated. - - b - Compiling body of rule b to compute value of type PositiveInteger - 1 - Type: PositiveInteger - -This gives the same results as before. But if we change a to 2 - - a == 2 - Compiled code for a has been cleared. - Compiled code for b has been cleared. - 1 old definition(s) deleted for function or rule a - Type: Void - -Then a evaluates to 2, as expected - - a - Compiling body of rule a to compute value of type PositiveInteger - 2 - Type: PositiveInteger - -but the value of b reflects the change to a - - b - Compiling body of rule b to compute value of type PositiveInteger - 2 - Type: PositiveInteger - -==================================================================== -Multiple Immediate Assignments -==================================================================== - -It is possible to set several variables at the same time by using a -tuple of variables and a tuple of expressions. A tuple is a collection -of things separated by commas, often surrounded by parentheses. The -syntax for multiple immediate assignment is - - ( var1, var2, ..., varN ) := ( expr1, expr2, ..., exprN ) - -The value returned by an immediate assignment is the value of exprN. - - ( x, y ) := ( 1, 2 ) - 2 - Type: PositiveInteger - -This sets x to 1 and y to 2. Multiple immediate assignments are parallel -in the sense that the expressions on the right are all evaluated before -any assignments on the left are made. However, the order of evaluation -of these expressions is undefined. - - ( x, y ) := ( y, x ) - 1 - Type: PositiveInteger - - x - 2 - Type: PositiveInteger - -The variable x now has the previous value of y. - - y - 1 - Type: PositiveInteger - -The variable y now has the previous value of x. - -There is no syntactic form for multiple delayed assignments. - -@ - -\section{command boot} -<>= -==================================================================== -A.3. )boot -==================================================================== - -User Level Required: development - -Command Syntax: - - - )boot bootExpression - -Command Description: - -This command is used by AXIOM system developers to execute expressions -written in the BOOT language. For example, - -)boot times3(x) == 3*x - -creates and compiles the Lisp function ``times3'' obtained by translating the -BOOT code. - -Also See: -o )fin -o )lisp -o )set -o )system - -@ - -\section{syntax blocks} -<>= -==================================================================== -Blocks -==================================================================== - -A block is a sequence of expressions evaluated in the order that they -appear, except as modified by control expressions such as leave, return, -iterate, and if-then-else constructions. The value of a block is the -value of the expression last evaluated in the block. - -To leave a block early, use "=>". For example, - - i < 0 => x - -The expression before the "=>" must evaluate to true or false. The -expression following the "=>" is the return value of the block. - -A block can be constructed in two ways: - - 1. the expressions can be separated by semicolons and the resulting - expression surrounded by parentheses, and - 2. the expressions can be written on succeeding lines with each line - indented the same number of spaces (which must be greater than zero). - A block entered in this form is called a pile - -Only the first form is available if you are entering expressions directly -to Axiom. Both forms are available in .input files. The syntax for a simple -block of expressions entered interactively is - - ( expression1 ; expression2 ; ... ; expressionN ) - -The value returned by a block is the value of an "=>" expression, or -expressionN if no "=>" is encountered. - -In .input files, blocks can also be written in piles. The examples -given here are assumed to come from .input files. - - a := - i := gcd(234,672) - i := 2*i**5 - i + 1 - 1 / i - - 1 - ----- - 23323 - Type: Fraction Integer - -In this example, we assign a rational number to a using a block consisting -of three expressions. This block is written as a pile. Each expression in -the pile has the same indentation, in this case two spaces to the right of -the first line. - - a := ( i := gcd(234,672); i := 2*i**5 - i + 1; 1 / i ) - - 1 - ----- - 23323 - Type: Fraction Integer - -Here is the same block written on one line. This is how you are required -to enter it at the input prompt. - - ( a := 1; b := 2; c := 3; [a,b,c] ) - [1,2,3] - Type: List PositiveInteger - -AAxiom gives you two ways of writing a block and the preferred way in -an .input file is to use a pile. Roughly speaking, a pile is a block -whose consituent expressions are indented the same amount. You begin a -pile by starting a new line for the first expression, indenting it to -the right of the previous line. You then enter the second expression on -a new line, vertically aligning it with the first line. And so on. If -you need to enter an inner pile, further indent its lines to the right -of the outer pile. Axiom knows where a pile ends. It ends when a subsequent -line is indented to the left of the pile or the end of the file. - -Also See: -o )help if -o )help repeat -o )help while -o )help for -o )help suchthat -o )help parallel -o )help lists - -@ - -\section{command cd} -<>= -==================================================================== -A.4. )cd -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )cd directory - -Command Description: - -This command sets the AXIOM working current directory. The current directory -is used for looking for input files (for )read), AXIOM library source files -(for )compile), saved history environment files (for )history )restore), -compiled AXIOM library files (for )library), and files to edit (for )edit). -It is also used for writing spool files (via )spool), writing history input -files (via )history )write) and history environment files (via )history -)save),and compiled AXIOM library files (via )compile). - -If issued with no argument, this command sets the AXIOM current directory to -your home directory. If an argument is used, it must be a valid directory -name. Except for the ``)'' at the beginning of the command, this has the same -syntax as the operating system cd command. - -Also See: -o )compile -o )edit -o )history -o )library -o )read -o )spool - -@ - -\section{command clear} -<>= -==================================================================== -A.6. )clear -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )clear all - - )clear completely - - )clear properties all - - )clear properties obj1 [obj2 ...] - - )clear value all - - )clear value obj1 [obj2 ...] - - )clear mode all - - )clear mode obj1 [obj2 ...] - -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 - -)clear all - -To remove everything in the workspace but not reset the step counter, issue - -)clear properties all - -To remove everything about the object x, issue - -)clear properties x - -To remove everything about the objects x, y and f, issue - -)clear properties x y f - -The word properties may be abbreviated to the single letter ``p''. - -)clear p all -)clear p x -)clear p x y f - -All definitions of functions and values of variables may be removed by either - -)clear value all -)clear v all - -This retains whatever declarations the objects had. To remove definitions and -values for the specific objects x, y and f, issue - -)clear value x y f -)clear v x y f - -To remove the declarations of everything while leaving the definitions and -values, issue - -)clear mode all -)clear m all - -To remove declarations for the specific objects x, y and f, issue - -)clear mode x y f -)clear m x y f - -The )display names and )display properties commands may be used to see what -is currently in the workspace. - -The command - -)clear completely - -does everything that )clear all does, and also clears the internal system -function and constructor caches. - -Also See: -o )display -o )history -o )undo - -@ - -\section{system clef} -<>= - -Entering printable keys generally inserts new text into the buffer (unless -in overwrite mode, see below). Other special keys can be used to modify -the text in the buffer. In the description of the keys below, ^n means -Control-n, or holding the CONTROL key down while pressing "n". Errors -will ring the terminal bell. - -^A/^E : Move cursor to beginning/end of the line. -^F/^B : Move cursor forward/backward one character. -^D : Delete the character under the cursor. -^H, DEL : Delete the character to the left of the cursor. -^K : Kill from the cursor to the end of line. -^L : Redraw current line. -^O : Toggle overwrite/insert mode. Initially in insert mode. Text - added in overwrite mode (including yanks) overwrite - existing text, while insert mode does not overwrite. -^P/^N : Move to previous/next item on history list. -^R/^S : Perform incremental reverse/forward search for string on - the history list. Typing normal characters adds to the current - search string and searches for a match. Typing ^R/^S marks - the start of a new search, and moves on to the next match. - Typing ^H or DEL deletes the last character from the search - string, and searches from the starting location of the last search. - Therefore, repeated DEL's appear to unwind to the match nearest - the point at which the last ^R or ^S was typed. If DEL is - repeated until the search string is empty the search location - begins from the start of the history list. Typing ESC or - any other editing character accepts the current match and - loads it into the buffer, terminating the search. -^T : Toggle the characters under and to the left of the cursor. -^Y : Yank previously killed text back at current location. Note that - this will overwrite or insert, depending on the current mode. -^U : Show help (this text). -TAB : Perform command completion based on word to the left of the cursor. - Words are deemed to contain only the alphanumeric and the % ! ? _ - characters. -NL, CR : returns current buffer to the program. - -DOS and ANSI terminal arrow key sequences are recognized, and act like: - - up : same as ^P - down : same as ^N - left : same as ^B - right : same as ^F - -@ - -\section{command close} -<>= -==================================================================== -A.5. )close -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )close - - )close )quietly - -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 - -)close - -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 - - This is the last AXIOM session. Do you want to kill AXIOM? - -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 )quietly option to force AXIOM to close down the interpreter -client process without closing down the entire AXIOM session. - -Also See: -o )quit -o )pquit - -@ - -\section{syntax collection} -<>= -==================================================================== -Collection -- Creating Lists and Streams with Iterators -==================================================================== - -All of the loop expressions which do not use the repeat leave or -iterate words can be used to create lists and streams. For example: - -This creates a simple list of the integers from 1 to 10: - - list := [i for i in 1..10] - [1,2,3,4,5,6,7,8,9,10] - Type: List PositiveInteger - -Create a stream of the integers greater than or equal to 1: - - stream := [i for i in 1..] - [1,2,3,4,5,6,7,...] - Type: Stream PositiveInteger - -This is a list of the prime numbers between 1 and 10, inclusive: - - [i for i in 1..10 | prime? i] - [2,3,5,7] - Type: List PositiveInteger - -This is a stream of the prime integers greater than or equal to 1: - - [i for i in 1.. | prime? i] - [2,3,5,7,11,13,17,...] - Type: Stream PositiveInteger - -This is a list of the integers between 1 and 10, inclusive, whose -squares are less than 700: - - [i for i in 1..10 while i*i < 700] - [1,2,3,4,5,6,7,8,9,10] - Type: List PositiveInteger - -This is a stream of the integers greater than or equal to 1 whose -squares are less than 700: - - [i for i in 1.. while i*i < 700] - [1,2,3,4,5,6,7,...] - Type: Stream PositiveInteger - -The general syntax of a collection is - - [ collectExpression iterator1 iterator2 ... iteratorN ] - -where each iterator is either a for or a while clause. The loop -terminates immedidately when the end test of any iterator succeeds -or when a return expression is evaluated in collectExpression. The -value returned by the collection is either a list or a stream of -elements, one for each iteration of the collectExpression. - -Be careful when you use while to create a stream. By default Axiom -tries to compute and display the first ten elements of a stream. If -the while condition is not satisfied quickly, Axiom can spend a long -(potentially infinite) time trying to compute the elements. Use - - )set streams calculate - -to change the defaults to something else. This also affects the number -of terms computed and displayed for power series. For the purposes of -these examples we have use this system command to display fewer than -ten terms. - -@ - -\section{command compile} -<>= -==================================================================== -A.7. )compile -==================================================================== - -User Level Required: compiler - -Command Syntax: - - - )compile - - )compile fileName - - )compile fileName.as - - )compile directory/fileName.as - - )compile fileName.ao - - )compile directory/fileName.ao - - )compile fileName.al - - )compile directory/fileName.al - - )compile fileName.lsp - - )compile directory/fileName.lsp - - )compile fileName.spad - - )compile directory/fileName.spad - - )compile fileName )new - - )compile fileName )old - - )compile fileName )translate - - )compile fileName )quiet - - )compile fileName )noquiet - - )compile fileName )moreargs - - )compile fileName )onlyargs - - )compile fileName )break - - )compile fileName )nobreak - - )compile fileName )library - - )compile fileName )nolibrary - - )compile fileName )vartrace - - )compile fileName )constructor nameOrAbbrev - -Command Description: - -You use this command to invoke the new AXIOM library compiler or the old -AXIOM system compiler. The )compile system command is actually a combination -of AXIOM processing and a call to the AXIOM-XL compiler. It is performing -double-duty, acting as a front-end to both the AXIOM-XL compiler and the old -AXIOM system compiler. (The old AXIOM system compiler was written in Lisp and -was an integral part of the AXIOM environment. The AXIOM-XL compiler is -written in C and executed by the operating system when called from within -AXIOM.) - -The command compiles files with file extensions .as, .ao and .al with the -AXIOM-XL compiler and files with file extension .spad with the old AXIOM -system compiler. It also can compile files with file extension .lsp. These -are assumed to be Lisp files genererated by the AXIOM-XL compiler. If you -omit the file extension, the command looks to see if you have specified the -)new or )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 .as, .ao and .al and -then files with extension .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 )translate option is used to invoke a special version of the old system -compiler that will translate a .spad file to a .as file. That is, the .spad -file will be parsed and analyzed and a file using the new syntax will be -created. By default, the .as file is created in the same directory as the -.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 )translate implies the )old option so the file -extension can safely be omitted. If )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 AXIOM-XL compiler and make any necessary corrections. - -We now describe the options for the new AXIOM-XL compiler. - -The first thing )compile does is look for a source code filename among its -arguments. Thus - -)compile mycode.as -)compile /u/jones/as/mycode.as -)compile mycode - -all invoke )compiler on the file /u/jones/as/mycode.as if the current AXIOM -working directory is /u/jones/as. (Recall that you can set the working -directory via the )cd command. If you don't set it explicitly, it is the -directory from which you started AXIOM.) - -This is frequently all you need to compile your file. This simple command: - - - Invokes the AXIOM-XL compiler and produces Lisp output. - - Calls the Lisp compiler if the AXIOM-XL compilation was - successful. - - Use the )library command to tell AXIOM about - the contents of your compiled file and arrange to have those contents - loaded on demand. - -Should you not want the )library command automatically invoked, call )compile -with the )nolibrary option. For example, - -)compile mycode.as )nolibrary - -The general description of AXIOM-XL command line arguments is in the AXIOM-XL -documentation. The default options used by the )compile command can be viewed -and set using the )set compiler args AXIOM system command. The current -defaults are - --O -Fasy -Fao -Flsp -laxiom -Mno-AXL_W_WillObsolete -DAxiom - -These options mean: - - - -O: perform all optimizations, - - -Fasy: generate a .asy file, - - -Fao: generate a .ao file, - - -Flsp: generate a .lsp (Lisp) - file, - - -laxiom: use the axiom library libaxiom.al, - - -Mno-AXL_W_WillObsolete: do not display messages - about older generated files becoming obsolete, and - - -DAxiom: define the global assertion Axiom so that the - AXIOM-XL libraries for generating stand-alone code are not accidentally - used with AXIOM. - -To supplement these default arguments, use the )moreargs option on )compile. -For example, - -)compile mycode.as )moreargs "-v" - -uses the default arguments and appends the -v (verbose) argument flag. The -additional argument specification must be enclosed in double quotes. - -To completely replace these default arguments for a particular use of -)compile, use the )onlyargs option. For example, - -)compile mycode.as )onlyargs "-v -O" - -only uses the -v (verbose) and -O (optimize) arguments. The argument -specification must be enclosed in double quotes. In this example, Lisp code -is not produced and so the compilation output will not be available to AXIOM. - -To completely replace the default arguments for all calls to )compile within -your AXIOM session, use )set compiler args. For example, to use the above -arguments for all compilations, issue - -)set compiler args "-v -O" - -Make sure you include the necessary -l and -Y arguments along with those -needed for Lisp file creation. As above, the argument specification must be -enclosed in double quotes. - -By default, the )library system command exposes all domains and categories it -processes. This means that the AXIOM 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 )library command should still be used, though, so that the -code will be loaded on demand. In this case, you should use the )nolibrary -option on )compile and the )noexpose option in the )library command. For -example, - -)compile mycode.as )nolibrary -)library mycode )noexpose - -Once you have established your own collection of compiled code, you may find -it handy to use the )dir option on the )library command. This causes )library -to process all compiled code in the specified directory. For example, - -)library )dir /u/jones/as/quantum - -You must give an explicit directory after )dir, even if you want all compiled -code in the current working directory processed. - -)library )dir . - -The )compile command works with several file extensions. We saw above what -happens when it is invoked on a file with extension .as. A .ao file is a -portable binary compiled version of a .as file, and )compile simply passes -the .ao file onto AXIOM-XL. The generated Lisp file is compiled and )library -is automatically called, just as if you had specified a .as file. - -A .al file is an archive file containing .ao files. The archive is created -(on Unix systems) with the ar program. When )compile is given a .al file, it -creates a directory whose name is based on that of the archive. For example, -if you issue - -)compile mylib.al - -the directory mylib.axldir is created. All members of the archive are -unarchived into the directory and )compile is called on each .ao file found. -It is your responsibility to remove the directory and its contents, if you -choose to do so. - -A .lsp file is a Lisp source file, presumably, in our context, generated by -AXIOM-XL when called with the -Flsp option. When )compile is used with a .lsp -file, the Lisp file is compiled and )library is called. You must also have -present a .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 .spad. You can compile individual constructors or every -constructor in a file. - -The full filename is remembered between invocations of this command and )edit -commands. The sequence of commands - -)compile matrix.spad -)edit -)compile - -will call the compiler, edit, and then call the compiler again on the file -matrix.spad. If you do not specify a directory, the working current directory -(see description of command )cd ) 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 )abbreviation command in the file in which it -is defined. We suggest that you place the )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. - -The )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 .NRLIB file -extension. For example, the directory containing the compiled code for the -MATRIX constructor is called MATRIX.NRLIB. The )nolibrary option says that -such files should not be created. The default is )library. Note that the -semantics of )library and )nolibrary for the new AXIOM-XL compiler and for -the old system compiler are completely different. - -The )vartrace option causes the compiler to generate extra code for the -constructor to support conditional tracing of variable assignments. (see -description of command )trace ). Without this option, this code is suppressed -and one cannot use the )vars option for the trace command. - -The )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 )constructor. Thus either - -)compile matrix.spad )constructor RectangularMatrix - -or - -)compile matrix.spad )constructor RMATRIX - -compiles the RectangularMatrix constructor defined in matrix.spad. - -The )break and )nobreak options determine what the old system compiler does -when it encounters an error. )break is the default and it indicates that -processing should stop at the first error. The value of the )set break -variable then controls what happens. - -Also See: -o )abbreviation -o )edit -o )library - -@ - -\section{command display} -<>= -==================================================================== -A.8. )display -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )display all - - )display properties - - )display properties all - - )display properties [obj1 [obj2 ...]] - - )display value all - - )display value [obj1 [obj2 ...]] - - )display mode all - - )display mode [obj1 [obj2 ...]] - - )display names - - )display operations opName - -Command Description: - -This command is used to display the contents of the workspace and signatures -of functions with a given name. (A signature gives the argument and return -types of a function.) - -The command - -)display names - -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 - -)display all -)display properties -)display properties all - -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 d, issue - -)display properties d - -To just show the value (and the type) of d, issue - -)display value d - -To just show the declared mode of d, issue - -)display mode d - -All modemaps for a given operation may be displayed by using )display -operations. A 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 FromcomplexComplexCategory: - -)d op complex - -Also See: -o )clear -o )history -o )set -o )show -o )what - -@ - -\section{command edit} -<>= -==================================================================== -A.9. )edit -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )edit [filename] - -Command Description: - -This command is used to edit files. It works in conjunction with the )read -and )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 - -)edit /u/julius/matrix.input - -will place you in an editor looking at the file /u/julius/matrix.input. By -default, the editor is vi, but if you have an EDITOR shell environment -variable defined, that editor will be used. When AXIOM is running under the X -Window System, it will try to open a separate xterm running your editor if it -thinks one is necessary. For example, under the Korn shell, if you issue - -export EDITOR=emacs - -then the emacs editor will be used by )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 )system command to edit a file directly. For -example, - -)system emacs /etc/rc.tcpip - -calls emacs to edit the file. - -Also See: -o )system -o )compile -o )read - - -@ - -\section{command fin} -<>= -==================================================================== -A.10. )fin -==================================================================== - -User Level Required: development - -Command Syntax: - - - )fin - -Command Description: - -This command is used by AXIOM developers to leave the AXIOM system and return -to the underlying Lisp system. To return to AXIOM, issue the ``(|spad|)'' -function call to Lisp. - -Also See: -o )pquit -o )quit - - -@ - -\section{syntax for} -<>= -==================================================================== -for loops -==================================================================== - -Axiom provide the for and in keywords in repeat loops, allowing you -to integrate across all elements of a list, or to have a variable take -on integral values from a lower bound to an upper bound. We shall refer -to these modifying clauses of repeat loops as for clauses. These clauses -can be present in addition to while clauses (See )help while). As with -all other types of repeat loops, leave (see )help leave) can be used to -prematurely terminate evaluation of the loop. - -The syntax for a simple loop using for is - - for iterator repeat loopbody - -The iterator has several forms. Each form has an end test which is -evaluted before loopbody is evaluated. A for loop terminates immediately -when the end test succeeds (evaluates to true) or when a leave or return -expression is evaluated in loopbody. The value returned by the loop is -the unique value of Void. - -==================================================================== -for i in n..m repeat -==================================================================== - -If for is followed by a variable name, the in keyword and then an integer -segment of the form n..m, the end test for this loop is the predicate -i > m. The body of the loop is evaluated m-n+1 times if this number is -greater than 0. If this number is less than or equal to 0, the loop body -is not evaluated at all. - -The variable i has the value n, n+1, ..., m for successive iterations -of the loop body. The loop variable is a local variable within the loop -body. Its value is not available outside the loop body and its value and -type within the loop body completely mask any outer definition of a -variable with the same name. - - for i in 10..12 repeat output(i**3) - 1000 - 1331 - 1728 - Type: Void - -The loop prints the values of 10^3, 11^3, and 12^3. - - a := [1,2,3] - [1,2,3] - Type: List PositiveInteger - - for i in 1..#a repeat output(a.i) - 1 - 2 - 3 - Type: Void - -Iterate across this list using "." to access the elements of a list -and the # operation to count its elements. - -This type of iteration is applicable to anything that uses ".". You -can also use it with functions that use indices to extract elements. - - m := matrix [[1,2],[4,3],[9,0]] - +- -+ - | 1 2 | - | 4 3 | - | 9 0 | - +- -+ - Type: Matrix Integer - -Define m to be a matrix. - - for i in 1..nrows(m) repeat output row(m.i) - [1,2] - [4,3] - [9,0] - Type: Void - -Display the rows of m. - -You can iterate with for-loops. - - for i in 1..5 repeat - if odd?(i) then iterate - output(i) - 2 - 4 - Type: Void - -Display the even integers in a segment. - -==================================================================== -for i in n..m by s repeat -==================================================================== - -By default, the difference between values taken on by a variable in -loops such as - - for i in n..m repeat ... - -is 1. It is possible to supply another, possibly negative, step value -by using the by keyword along with for and in. Like the upper and lower -bounds, the step value following the by keyword must be an integer. Note -that the loop - - for i in 1..2 by 0 repeat output(i) - -will not terminate by itself, as the step value does not change the -index from its initial value of 1. - - for i in 1..5 by 2 repeat output(i) - 1 - 3 - 5 - Type: Void - -This expression displays the odd integers between two bounds. - - for i in 5..1 by -2 repeat output(i) - 5 - 3 - 1 - Type: Void - -Use this to display the numbers in reverse order. - -==================================================================== -for i in n.. repeat -==================================================================== - -If the value after the ".." is omitted, the loop has no end test. A -potentially infinite loop is thus created. The variable is given the -successive values n, n+1, n+2, ... and the loop is terminated only -if a leave or return expression is evaluated in the loop body. However, -you may also add some other modifying clause on the repeat, for example, -a while clause, to stop the loop. - - for i in 15.. while not prime?(i) repeat output(i) - 15 - 16 - Type: Void - -This loop displays the integers greater than or equal to 15 and less -than the first prime number greater than 15. - -==================================================================== -for x in l repeat -==================================================================== - -Another variant of the for loop has the form: - - for x in list repeat loopbody - -This form is used when you want to iterate directly over the elements -of a list. In this form of the for loop, the variable x takes on the -value of each successive element in l. The end test is most simply -stated in English: "are there no more x in l?" - - l := [0, -5, 3] - [0, -5, 3] - Type: List Integer - - for x in l repeat output(x) - 0 - -5 - 3 - Type: Void - -This displays all of the elements of the list l, one per line. - -Since the list constructing expression - - expand [n..m] - -creates the list - - [n, n+1, ..., m] - -you might be tempted to think that the loops - - for i in n..m repeat output(i) - -and - - for x in expand [n..m] repeat output(x) - -are equivalent. The second form first creates the expanded list -(no matter how large it might be) and then does the iteration. The -first form potentially runs in much less space, as the index variable -i is simply incremented once per loop and the list is not actually -created. Using the first form is much more efficient. - -Of course, sometimes you really want to iterate across a specific list. -This displays each of the factors of 2400000: - - for f in factors(factor(2400000)) repeat output(f) - [factor= 2, exponent= 8] - [factor= 3, exponent= 1] - [factor= 5, exponent= 5] - Type: Void - -@ - -\section{command frame} -<>= -==================================================================== -A.11. )frame -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )frame new frameName - - )frame drop [frameName] - - )frame next - - )frame last - - )frame names - - )frame import frameName [objectName1 [objectName2 ...]] - - )set message frame on | off - - )set message prompt frame - -Command Description: - -A 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 step number, environment and history. You can have a -variable named a in one frame and it will have nothing to do with anything -that might be called a in any other frame. - -Some frames are created by the HyperDoc program and these can have pretty -strange names, since they are generated automatically. To find out the names -of all frames, issue - -)frame names - -It will indicate the name of the current frame. - -You create a new frame ``quark'' by issuing - -)frame new quark - -The history facility can be turned on by issuing either )set history on or -)history )on. If the history facility is on and you are saving history -information in a file rather than in the AXIOM environment then a history -file with filename quark.axh will be created as you enter commands. If you -wish to go back to what you were doing in the ``initial'' frame, use - -)frame next - -or - -)frame last - -to cycle through the ring of available frames to get back to ``initial''. - -If you want to throw away a frame (say ``quark''), issue - -)frame drop quark - -If you omit the name, the current frame is dropped. - -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. These are directories, so -you may want to issue a command like rm -r quark.axh to the operating system. - -You can bring things from another frame by using )frame import. For example, -to bring the f and g from the frame ``quark'' to the current frame, issue - -)frame import quark f g - -If you want everything from the frame ``quark'', issue - -)frame import quark - -You will be asked to verify that you really want everything. - -There are two )set flags to make it easier to tell where you are. - -)set message frame on | off - -will print more messages about frames when it is set on. By default, it is -off. - -)set message prompt frame - -will give a prompt that looks like - -initial (1) -> - -when you start up. In this case, the frame name and step make up the prompt. - -Also See: -o )history -o )set - -@ - -\section{command help} -<>= -==================================================================== -A.12. )help -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )help - - )help commandName - - )help syntax - -Command Description: - -This command displays help information about system commands. If you issue - -)help - -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, - -)help clear - -will display the description of the )clear system command. - -The command - -)help syntax - -will give further information about the Axiom language syntax. - -All this material is available in the AXIOM User Guide and in HyperDoc. In -HyperDoc, choose the Commands item from the Reference menu. - -==================================================================== -A.1. Introduction -==================================================================== - - -System commands are used to perform AXIOM environment management. Among the -commands are those that display what has been defined or computed, set up -multiple logical AXIOM environments (frames), clear definitions, read files -of expressions and commands, show what functions are available, and terminate -AXIOM. - -Some commands are restricted: the commands - -)set userlevel interpreter -)set userlevel compiler -)set userlevel development - -set the user-access level to the three possible choices. All commands are -available at development level and the fewest are available at interpreter -level. The default user-level is interpreter. In addition to the )set command -(discussed in description of command )set ) you can use the HyperDoc settings -facility to change the user-level. Click on [Settings] 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 AXIOM or be -included in .input files. - -A system command argument is a word that directly follows the command name -and is not followed or preceded by a right parenthesis. A system command -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: - - )syscmd arg1 arg2 )opt1 opt1arg1 opt1arg2 )opt2 opt2arg1 ... - -In the system command descriptions, optional arguments and options are -enclosed in brackets (``['' and ``]''). 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 - -)read fileName [)quietly] - -would imply that you must provide an actual file name for fileName but need -not use the )quietly option. Thus - -)read matrix.input - -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 - -)s Integer - -is not a valid abbreviation for the )set command, because both )set and )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 ``|'' to indicate that you -must specify one of the listed choices. For example, in - -)set output fortran on | off - -only on and off are acceptable words for following 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. - -==================================================================== -Other help topics -==================================================================== -Available help topics are: - -abbreviations assignment boot blocks cd clear -clef close collection compile display edit -fin for frame help history if -iterate leave library lisp load ltrace -parallel pquit quit read repeat savesystem -set show spool suchthat synonym system -syntax trace undo what while - -Available algebra help topics are: - -@ - -\section{command history} -<>= -==================================================================== -A.13. )history -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )history )on - - )history )off - - )history )write historyInputFileName - - )history )show [n] [both] - - )history )save savedHistoryName - - )history )restore [savedHistoryName] - - )history )reset - - )history )change n - - )history )memory - - )history )file - - % - - %%(n) - - )set history on | off - -Command Description: - -The history facility within AXIOM 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 .input -file of the lines typed to AXIOM. - -AXIOM saves your input and output if the history facility is turned on (which -is the default). This information is saved if either of - -)set history on -)history )on - -has been issued. Issuing either - -)set history off -)history )off - -will discontinue the recording of information. - -Whether the facility is disabled or not, the value of % in AXIOM always -refers to the result of the last computation. If you have not yet entered -anything, % evaluates to an object of type Variable('%). The function %% may -be used to refer to other previous results if the history facility is -enabled. In that case, %%(n) is the output from step n if n > 0. If n < 0, -the step is computed relative to the current step. Thus %%(-1) is also the -previous step, %%(-2), is the step before that, and so on. If an invalid step -number is given, AXIOM will signal an error. - -The environment information can either be saved in a file or entirely in -memory (the default). Each frame ( description of command )frame ) 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 FRAME.axh where ``FRAME'' is the name of the -current frame. The history file is placed in the current working directory -(see description of command )cd ). 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 )history command are as follows: - - )change n - will set the number of steps that are saved in memory to n. This option - only has effect when the history data is maintained in a file. If you - have issued )history )memory (or not changed the default) there is no - need to use )history )change. - - )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 )set history on. - - )off - will stop the recording of information. The )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 )set - history off. - - )file - indicates that history data should be saved in an external file on disk. - - )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. - - )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 )history )change, this option only has real effect when - history data is being saved in a file. - - )restore [savedHistoryName] - completely clears the environment and restores it to a saved session, if - possible. The )save option below allows you to save a session to a file - with a given name. If you had issued )history )save jacobi the command - )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 last.axh. - - )save savedHistoryName - is used to save a snapshot of the environment in a file. This file is - placed in the current working directory (see description of command )cd - ). Use )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 AXIOM session) or last did a )clear all or - )clear completely. - - )show [n] [both] - can show previous input lines and output results. )show will display up - to twenty of the last input lines (fewer if you haven't typed in twenty - lines). )show n will display up to n of the last input lines. )show both - will display up to five of the last input lines and output results. )show - n both will display up to n of the last input lines and output results. - - )write historyInputFile - creates an .input file with the input lines typed since the start of the - session/frame or the last )clear all or )clear completely. If - historyInputFileName does not contain a period (``.'') in the filename, - .input is appended to it. For example, )history )write chaos and )history - )write chaos.input both write the input lines to a file called - chaos.input in your current working directory. If you issued one or more - )undo commands, )history )write eliminates all input lines backtracked - over as a result of )undo. You can edit this file and then use )read to - have AXIOM process the contents. - -Also See: -o )frame -o )read -o )set -o )undo - -@ - -\section{syntax if} -<>= -==================================================================== -If-then-else -==================================================================== - -Like many other programming languages, Axiom uses the three keywords -if, then, and else to form conditional expressions. The else part of -the conditional is optional. The expression between the if and then -keywords is a predicate: an expression that evaluates to or is -convertible to either true or false, that is, a Boolean. - -The syntax for conditional expressions is - - if predicate then expression1 else expression2 - -where the "else expression2" part is optional. The value returned from -a conditional expression is expression1 if the predicate evaluates to -true and expression2 otherwise. If no else clause is given, the value -is always the unique value of Void. - -An if-then-else expression always returns a value. If the else clause -is missing then the entire expression returns the unique value of Void. -If both clauses are present, the type of the value returned by if is -obtained by resolving the types of the values of the two clauses. - -The predicate must evaluate to, or be convertible to, an object of type -Boolean: true or false. By default, the equal sign "=" creates an equation. - - x + 1 = y - x + 1 = y - Type: Equation Polynomial Integer - -This is an equation, not a boolean condition. In particular, it is -an object of type Equation Polynomial Integer. - -However, for predicates in if expressions, Axiom places a default -target type of Boolean on the predicate and equality testing is performed. -Thus you need not qualify the "=" in any way. In other contexts you may -need to tell Axiom that you want to test for equality rather than create -an equation. In these cases, use "@" and a target type of Boolean. - -The compound symbol meaning "not equal" in Axiom is "~=". This can be -used directly without a package call or a target specification. The -expression "a ~= b" is directly translated to "not(a = b)". - -Many other functions have return values of type Boolean. These include -<, <=, >, >=, ~=, and member?. By convention, operations with names -ending in "?" return Boolean values. - -The usual rules for piles are suspended for conditional expressions. In -.input files, the then and else keywords can begin in the same column -as the corresponding if by may also appear to the right. Each of the -following styles of writing if-then-else expressions is acceptable: - - if i>0 then output("positive") else output("nonpositive") - - if i>0 then output("positive") - else output("nonpositive") - - if i>0 then output("positive") - else output("nonpositive") - - if i>0 - then output("positive") - else output("nonpositive") - - if i>0 - then output("positive") - else output("nonpositive") - -A block can follow the then or else keywords. In the following two -assignments to a, the then and else clauses each are followed by two -line piles. The value returned in each is the value of the second line. - - a := - if i > 0 then - j := sin(i * pi()) - exp(j + 1/j) - else - j := cos(i * 0.5 * pi()) - log(abs(j)**5 + i) - - - a := - if i > 0 - then - j := sin(i * pi()) - exp(j + 1/j) - else - j := cos(i * 0.5 * pi()) - log(abs(j)**5 + i) - -These are both equivalent to the following: - - a := - if i > 0 then (j := sin(i * pi()); exp(j + 1/j)) - else (j := cos(i * 0.5 * pi()); log(abs(j)**5 + i)) - -@ - -\section{syntax iterate} -<>= -==================================================================== -iterate in loops -==================================================================== - -Axiom provides an iterate expression that skips over the remainder -of a loop body and starts the next loop execution. We first initialize -a counter. - - i := 0 - 0 - Type: NonNegativeInteger - -Display the even integers from 2 to 5: - - repeat - i := i + 1 - if i > 5 then leave - if odd?(i) then iterate - output(i) - 2 - 4 - Type: Void - -@ - -\section{syntax leave} -<>= -==================================================================== -leave in loops -==================================================================== - -The leave keyword is often more useful in terminating a loop. A -leave causes control to transfer to the expression immediately following -the loop. As loops always return the unique value of Void, you cannot -return a value with leave. That is, leave takes no argument. - - f() == - i := 1 - repeat - if factorial(i) > 1000 then leave - i := i + 1 - i - Type: Void - -This example is a modification of the last example in the previous -section. Instead of using return we'll use leave. - - f() - 7 - Type: PositiveInteger - -The loop terminates when factorial(i) gets big enough. The last line -of the function evaluates to the corresponding "good" value of i -and the function terminates, returning that value. - -You can only use leave to terminate the evaluation of one loop. Lets -consider a loop within a loop, that is, a loop with a nested loop. -First, we initialize two counter variables. - - (i,j) := (1,1) - 1 - Type: PositiveInteger - - repeat - repeat - if (i + j) > 10 then leave - j := j + 1 - if (i + j) > 10 then leave - i := i + 1 - Type: Void - -Nested loops must have multiple leave expressions at the appropriate -nesting level. How would you rewrite this so (i + j) > 10 is only -evaluated once? - -==================================================================== -leave vs => in loop bodies -==================================================================== - -Compare the following two loops: - - i := 1 i := 1 - repeat repeat - i := i + 1 i := i + 1 - i > 3 => i if i > 3 then leave - output(i) output(i) - -In the example on the left, the values 2 and 3 for i are displayed but -then the "=>" does not allow control to reach the call to output again. -The loop will not terminate until you run out of space or interrupt the -execution. The variable i will continue to be incremented because the -"=>" only means to leave the block, not the loop. - -In the example on the right, upon reaching 4, the leave will be executed, -and both the block and the loop will terminate. This is one of the reasons -why both "=>" and leave are provided. Using a while clase with the "=>" -lets you simulate the action of leave. - -@ - -\section{command library} -<>= -==================================================================== -A.14. )library -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )library libName1 [libName2 ...] - - )library )dir dirName - - )library )only objName1 [objlib2 ...] - - )library )noexpose - -Command Description: - -This command replaces the )load system command that was available in AXIOM -releases before version 2.0. The )library command makes available to AXIOM -the compiled objects in the libraries listed. - -For example, if you )compile dopler.as in your home directory, issue )library -dopler to have AXIOM 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 )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 NRLIB -present, for example, DOPLER.NRLIB, where DOPLER is a constructor -abbreviation. The command )library DOPLER will then do the analysis and -database updates as above. - -To tell the system about all libraries in a directory, use )library )dir -dirName where 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 )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 )only option. The command )library dopler -)only Test1 will only cause the Test1 constructor to be analyzed, autoloaded, -etc.. - -Finally, each constructor in a library are usually automatically exposed when -the )library command is used. Use the )noexpose option if you not want them -exposed. At a later time you can use )set expose add constructor to expose -any hidden constructors. - -Note for AXIOM beta testers: At various times this command was called )local -and )with before the name )library became the official name. - -Also See: -o )cd -o )compile -o )frame -o )set - -@ - -\section{command lisp} -<>= -==================================================================== -A.15. )lisp -==================================================================== - -User Level Required: development - -Command Syntax: - - - )lisp [lispExpression] - -Command Description: - -This command is used by AXIOM system developers to have single expressions -evaluated by the Lisp system on which AXIOM is built. The 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 )fin -command may be used to drop out of AXIOM into Lisp. - -Also See: -o )system -o )boot -o )fin - -@ - -\section{command load} -<>= -==================================================================== -A.16. )load -==================================================================== - -User Level Required: interpreter - -Command Description: - -This command is obsolete. Use )library instead. - -@ - -\section{command ltrace} -<>= -==================================================================== -A.17. )ltrace -==================================================================== - -User Level Required: development - -Command Syntax: - -This command has the same arguments as options as the )trace command. - -Command Description: - -This command is used by AXIOM system developers to trace Lisp or BOOT -functions. It is not supported for general use. - -Also See: -o )boot -o )lisp -o )trace - -@ - - -\section{syntax parallel} -<>= -==================================================================== -parallel iteration -==================================================================== - -Sometimes you want to iterate across two lists in parallel, or perhaps -you want to traverse a list while incrementing a variable. - -The general syntax of a repeat loop is - - iterator1, iterator2, ..., iteratorN repeat loopbody - -where each iterator is either a for or a while clause. The loop -terminates immediately when the end test of any iterator succeeds or -when a leave or return expression is evaluated in loopbody. The value -returned by the loop is the unique value of Void. - - l := [1,3,5,7] - [1,3,5,7] - Type: List PositiveInteger - - m := [100,200] - [100,200] - Type: List PositiveInteger - - sum := 0 - 0 - Type: NonNegativeInteger - -Here we write a loop to iterate across two lists, computing the sum -of the pairwise product of the elements: - - for x in l for y in m repeat - sum := sum + x*y - Type: Void - -The last two elements of l are not used in the calculation because -m has two fewer elements than l. - - sum - 700 - Type: NonNegativeInteger - -This is the "dot product". - -Next we write a loop to compute the sum of the products of the loop -elements with their positions in the loop. - - l := [2,3,5,7,11,13,17,19,23,29,31,37] - [2,3,5,7,11,13,17,19,23,29,31,37] - Type: List PositiveInteger - - sum := 0 - 0 - Type: NonNegativeInteger - - for i in 0.. for x in l repeat sum := i * x - Type: Void - -Here looping stops when the list l is exhaused, even though the -for i in 0.. specifies no terminating condition. - - sum - 407 - Type: NonNegativeInteger - -When "|" is used to qualify any of the for clauses in a parallel -iteration, the variables in the predicates can be from an outer -scope or from a for clause in or to the left of the modified clause. - -This is correct: - - for i in 1..10 repeat - for j in 200..300 | ood? (i+j) repeat - output [i,j] - -But this is not correct. The variable j has not been defined outside -the inner loop: - - for i in 1..01 | odd? (i+j) repeat -- wrong, j not defined - for j in 200..300 repeat - output [i,j] - -It is possible to mix several of repeat modifying clauses on a loop: - - for i in 1..10 - for j in 151..160 | odd? j - while i + j < 160 repeat - output [i,j] - [1,151] - [3,153] - Type: Void - -Here are useful rules for composing loop expressions: - - 1. while predicates can only refer to variables that are global (or - in an outer scope) or that are defined in for clauses to the left - of the predicate. - 2. A "such that" predicate (somthing following "|") must directly - follow a for clause and can only refer to variables that are - global (or in an outer scope) or defined in the modified for clause - or any for clause to the left. - -@ - -\section{command pquit} -<>= -==================================================================== -A.18. )pquit -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )pquit - -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 )history )restore -command to try to restore your working environment, you cannot return to -AXIOM in the same state. - -)pquit differs from the )quit in that it always asks for confirmation that -you want to terminate AXIOM (the ``p'' is for ``protected''). When you enter -the )pquit command, AXIOM responds - - Please enter y or yes if you really want to leave the interactive - environment and return to the operating system: - -If you respond with y or yes, you will see the message - - You are now leaving the AXIOM interactive environment. - Issue the command axiom to the operating system to start a new session. - -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 y or yes, then the message - - You have chosen to remain in the AXIOM interactive environment. - -will be displayed and, indeed, AXIOM would still be running. - -Also See: -o )fin -o )history -o )close -o )quit -o )system - -@ - -\section{command quit} -<>= -==================================================================== -A.19. )quit -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )quit - - )set quit protected | unprotected - -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 )history )restore -command to try to restore your working environment, you cannot return to -AXIOM in the same state. - -)quit differs from the )pquit in that it asks for confirmation only if the -command - -)set quit protected - -has been issued. Otherwise, )quit will make AXIOM terminate and return you to -the operating system (or the environment from which you invoked the system). - -The default setting is )set quit protected so that )quit and )pquit behave in -the same way. If you do issue - -)set quit unprotected - -we suggest that you do not (somehow) assign )quit to be executed when you -press, say, a function key. - -Also See: -o )fin -o )history -o )close -o )pquit -o )system - -@ - -\section{command read} -<>= -==================================================================== -A.20. )read -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )read [fileName] - - )read [fileName] [)quiet] [)ifthere] - -Command Description: - -This command is used to read .input files into AXIOM. The command - -)read matrix.input - -will read the contents of the file matrix.input into AXIOM. The ``.input'' -file extension is optional. See the AXIOM User Guide index for more -information about .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 )ifthere option checks to see whether the .input file exists. If it does -not, the )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 .input -file. - -The )quiet option suppresses output while the file is being read. - -Also See: -o )compile -o )edit -o )history - -@ - -\section{syntax repeat} -<>= -==================================================================== -Repeat Loops -==================================================================== - -A loop is an expression that contains another expression, called the loop -body, which is to be evaluated zero or more times. All loops contain the -repeat keyword and return the unique value of Void. Loops can contain -inner loops to any depth. - -The most basic loop is of the form - - repeat loopbody - -Unless loopbody contains a leave or return expression, the loop repeats -foreer. The value returned by the loop is the unique value of Void. - -Axiom tries to determine completely the type of every object in a loop -and then to translate the loop body to Lisp or even to machine code. This -translation is called compilation. - -If Axiom decides that it cannot compile the loop, it issues a message -stating the problem and then the following message: - - We will attemp to step through and interpret the code - -It is still possible that Axiom can evalute the loop but in interpret-code -mode. - -==================================================================== -Return in Loops -==================================================================== - -A return expression is used to exit a function with a particular value. -In particular, if a return is in a loop within the function, the loop -is terminated whenever the return is evaluated. - - f() == - i := 1 - repeat - if factorial(i) > 1000 then return i - i := i + 1 - Type: Void - - f() - Type: Void - -When factorial(i) is big enough, control passes from inside the loop -all the way outside the function, returning the value of i (so we think). -What went wrong? Isn't it obvious that this function should return an -integer? Well, Axiom makes no attempt to analyze the structure of a -loop to determine if it always returns a value because, in general, this -is impossible. So Axiom has this simple rule: the type of the function is -determined by the type of its body, in this case a block. The normal value -of a block is the value of its last expression, in this case, a loop. And -the value of every loop is the unique value of Void. So the return type -of f is Void. - -There are two ways to fix this. The best way is for you to tell Axiom -what the return type of f is. You do this by giving f a declaration - - f:() -> Integer - -prior to calling for its value. This tells Axiom "trust me -- an integer -is returned". Another way is to add a dummy expression as follows. - - f() == - i := 1 - repeat - if factorial(i) > 1000 then return i - i := i + 1 - 0 - Type: Void - -Note that the dummy expression will never be evaluated but it is the -last expression in the function and will determine the return type. - - f() - 7 - Type: PositiveInteger - -==================================================================== -leave in loops -==================================================================== - -The leave keyword is often more useful in terminating a loop. A -leave causes control to transfer to the expression immediately following -the loop. As loops always return the unique value of Void, you cannot -return a value with leave. That is, leave takes no argument. - - f() == - i := 1 - repeat - if factorial(i) > 1000 then leave - i := i + 1 - i - Type: Void - -This example is a modification of the last example in the previous -section. Instead of using return we'll use leave. - - f() - 7 - Type: PositiveInteger - -The loop terminates when factorial(i) gets big enough. The last line -of the function evaluates to the corresponding "good" value of i -and the function terminates, returning that value. - -You can only use leave to terminate the evaluation of one loop. Lets -consider a loop within a loop, that is, a loop with a nested loop. -First, we initialize two counter variables. - - (i,j) := (1,1) - 1 - Type: PositiveInteger - - repeat - repeat - if (i + j) > 10 then leave - j := j + 1 - if (i + j) > 10 then leave - i := i + 1 - Type: Void - -Nested loops must have multiple leave expressions at the appropriate -nesting level. How would you rewrite this so (i + j) > 10 is only -evaluated once? - -==================================================================== -leave vs => in loop bodies -==================================================================== - -Compare the following two loops: - - i := 1 i := 1 - repeat repeat - i := i + 1 i := i + 1 - i > 3 => i if i > 3 then leave - output(i) output(i) - -In the example on the left, the values 2 and 3 for i are displayed but -then the "=>" does not allow control to reach the call to output again. -The loop will not terminate until you run out of space or interrupt the -execution. The variable i will continue to be incremented because the -"=>" only means to leave the block, not the loop. - -In the example on the right, upon reaching 4, the leave will be executed, -and both the block and the loop will terminate. This is one of the reasons -why both "=>" and leave are provided. Using a while clase with the "=>" -lets you simulate the action of leave. - -==================================================================== -iterate in loops -==================================================================== - -Axiom provides an iterate expression that skips over the remainder -of a loop body and starts the next loop execution. We first initialize -a counter. - - i := 0 - 0 - Type: NonNegativeInteger - -Display the even integers from 2 to 5: - - repeat - i := i + 1 - if i > 5 then leave - if odd?(i) then iterate - output(i) - 2 - 4 - Type: Void - -Also See: -o )help blocks -o )help if -o )help while -o )help for -o )help suchthat -o )help parallel -o )help lists - -@ -\section{command savesystem} -<>= -==================================================================== -A.8. )savesystem -==================================================================== - -User Level Required: interpreter - - -Command Syntax: - - - )savesystem filename - -Command Description: - - This command is used to save an AXIOM image to disk. This creates an -executable file which, when started, has everything loaded into it -that was there when the image was saved. Thus, after executing commands -which cause the loading of some packages, the command: - -)savesystem /tmp/savesys - -will create an image that can be restarted with the UNIX command: - -axiom -ws /tmp/savesys - -This new system will not need to reload the packages and domains that -were already loaded when the system was saved. - -There is currently a restriction that only systems started with the -command "AXIOMsys" may be saved. - -@ - -\section{command set} -<>= -==================================================================== -A.21. )set -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )set - - )set label1 [... labelN] - - )set label1 [... labelN] newValue - -Command Description: - -The )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 AXIOM 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 )set options to -familiarize yourself with how you can modify your AXIOM working environment. -There is a HyperDoc version of this same facility available from the main -HyperDoc menu. Click [here] to go to it. - -The )set command is command-driven with a menu display. It is -tree-structured. To see all top-level nodes, issue )set by itself. - -)set - -Variables with values have them displayed near the right margin. Subtrees of -selections have ``...'' displayed in the value field. For example, there are -many kinds of messages, so issue )set message to see the choices. - -)set message - -The current setting for the variable that displays whether computation times -are displayed is visible in the menu displayed by the last command. To see -more information, issue - -)set message time - -This shows that time printing is on now. To turn it off, issue - -)set message time off - -As noted above, not all settings have so many qualifiers. For example, to -change the )quit command to being unprotected (that is, you will not be -prompted for verification), you need only issue - -)set quit unprotected - -Also See: -o )quit - -@ - -\section{command show} -<>= -==================================================================== -A.22. )show -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )show nameOrAbbrev - - )show nameOrAbbrev )operations - - )show nameOrAbbrev )attributes - -Command Description: -This command displays information about AXIOM domain, package and category -constructors. If no options are given, the )operations option is assumed. For -example, - -)show POLY -)show POLY )operations -)show Polynomial -)show Polynomial )operations - -each display basic information about the Polynomial domain constructor and -then provide a listing of operations. Since Polynomial requires a Ring (for -example, Integer) as argument, the above commands all refer to a unspecified -ring R. In the list of operations, $ means Polynomial(R). - -The basic information displayed includes the signature of the constructor -(the name and arguments), the constructor abbreviation, the exposure status -of the constructor, and the name of the 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, - -)show POLY INT -)show POLY INT )operations -)show Polynomial Integer -)show Polynomial Integer )operations - -are among the combinations that will display the operations exported by the -domain Polynomial(Integer) (as opposed to the general domain constructor -Polynomial). Attributes may be listed by using the )attributes option. - -Also See: -o )display -o )set -o )what - -@ - -\section{command spool} -<>= -==================================================================== -A.23. )spool -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )spool [fileName] - - )spool - -Command Description: - -This command is used to save (spool) all AXIOM input and output into a file, -called a spool file. You can only have one spool file active at a time. To -start spool, issue this command with a filename. For example, - -)spool integrate.out - -To stop spooling, issue )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 current directory. The current directory is the directory -from which you started AXIOM or is the directory you specified using the )cd -command. - -Also See: -o )cd - -@ - -\section{syntax suchthat} -<>= -==================================================================== -Such that predicates -==================================================================== - -A for loop can be followed by a "|" and then a predicate. The predicate -qualifies the use of the values from the iterator that follows the for. -Think of the vertical bar "|" as the phrase "such that". - - for n in 0..4 | odd? n repeat output n - 1 - 3 - Type: Void - -This loop expression prints out the integers n in the given segment -such that n is odd. - -A for loop can also be written - - for iterator | predicate repeat loopbody - -which is equivalent to: - - for iterator repeat if predicate then loopbody else iterate - -The predicate need not refer only to the variable in the for clause. -Any variable in an outer scope can be part of the predicate. - - for i in 1..50 repeat - for j in 1..50 | factorial(i+j) < 25 repeat - output [i,j] - [1,1] - [1,2] - [1,3] - [2,1] - [2,2] - [3,1] - Type: Void - -@ - -\section{command synonym} -<>= -==================================================================== -A.24. )synonym -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )synonym - - )synonym synonym fullCommand - - )what synonyms - -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. - -)synonym save history )save -)synonym restore history )restore -)synonym mail system mail -)synonym ls system ls -)synonym fortran set output fortran - -Once defined, synonyms can be used in place of the longer command -expressions. Thus - -)fortran on - -is the same as the longer - -)set fortran output on - -To list all defined synonyms, issue either of - -)synonyms -)what synonyms - -To list, say, all synonyms that contain the substring ``ap'', issue - -)what synonyms ap - -Also See: -o )set -o )what - -@ - -\section{command system} -<>= -==================================================================== -A.25. )system -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )system cmdExpression - -Command Description: - -This command may be used to issue commands to the operating system while -remaining in AXIOM. The cmdExpression is passed to the operating system for -execution. - -To get an operating system shell, issue, for example, )system sh. When you -enter the key combination, Ctrl-D (pressing and holding the Ctrl key and then -pressing the D key) the shell will terminate and you will return to AXIOM. 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 -AXIOM. If this happens, you may have no other choice than to restart AXIOM -and restore the environment via )history )restore, if possible. - -Also See: -o )boot -o )fin -o )lisp -o )pquit -o )quit - -@ - -\section{syntax syntax} -<>= - -The Axiom Interactive Language has the following features documented here. - -More information is available by typing - - )help feature - -where feature is one of: - - assignment -- Immediate and delayed assignments - blocks -- Blocks of expressions - collection -- creating lists with iterators - for -- for loops - if -- If-then-else statements - iterate -- using iterate in loops - leave -- using leave in loops - parallel -- parallel iterations - repeat -- repeat loops - suchthat -- suchthat predicates - while -- while loops - -@ - -\section{command trace} -<>= -==================================================================== -A.26. )trace -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )trace - - )trace )off - - - )trace function [options] - - )trace constructor [options] - - )trace domainOrPackage [options] - -where options can be one or more of - - - )after S-expression - - )before S-expression - - )break after - - )break before - - )cond S-expression - - )count - - )count n - - )depth n - - )local op1 [... opN] - - )nonquietly - - )nt - - )off - - )only listOfDataToDisplay - - )ops - - )ops op1 [... opN ] - - )restore - - )stats - - )stats reset - - )timer - - )varbreak - - )varbreak var1 [... varN ] - - )vars - - )vars var1 [... varN ] - - )within executingFunction - -Command Description: - -This command is used to trace the execution of functions that make up the -AXIOM 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 - -)trace - -To untrace everything that is traced, issue - -)trace )off - -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 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 AXIOM 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 )trace. Any options that are present must follow the functions to -be traced. - -)trace f - -traces the function f. To untrace f, issue - -)trace f )off - -Note that if a function name contains a special character, it will be -necessary to escape the character with an underscore - -)trace _/D_,1 - -To trace all domains or packages that are or will be created from a -particular constructor, give the constructor name or abbreviation after -)trace. - -)trace MATRIX -)trace List Integer - -The first command traces all domains currently instantiated with Matrix. If -additional domains are instantiated with this constructor (for example, if -you have used Matrix(Integer) and Matrix(Float)), they will be automatically -traced. The second command traces List(Integer). It is possible to trace -individual functions in a domain or package. See the )ops option below. - -The following are the general options for the )trace command. - - )break after - causes a Lisp break loop to be entered after exiting the traced function. - - )break before - causes a Lisp break loop to be entered before entering the traced - function. - - )break - is the same as )break before. - - )count - causes the system to keep a count of the number of times the traced - function is entered. The total can be displayed with )trace )stats and - cleared with )trace )stats reset. - - )count n - causes information about the traced function to be displayed for the - first n executions. After the nth execution, the function is untraced. - - )depth n - causes trace information to be shown for only n levels of recursion of - the traced function. The command - - )trace fib )depth 10 - - will cause the display of only 10 levels of trace information for the - recursive execution of a user function fib. - - )math - causes the function arguments and return value to be displayed in the - AXIOM monospace two-dimensional math format. - - )nonquietly - causes the display of additional messages when a function is traced. - - )nt - This suppresses all normal trace information. This option is useful if - the )count or )timer options are used and you are interested in the - statistics but not the function calling information. - - )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 )trace )restore. - - )only listOfDataToDisplay - causes only specific trace information to be shown. The items are listed - by using the following abbreviations: - - a display all arguments - v display return value - 1 display first argument - 2 display second argument - 15 display the 15th argument, and so on - - )restore - causes the last untraced functions to be retraced. If additional options - are present, they are added to those previously in effect. - - )stats - causes the display of statistics collected by the use of the )count and - )timer options. - - )stats reset - resets to 0 the statistics collected by the use of the )count and )timer - options. - - )timer - causes the system to keep a count of execution times for the traced - function. The total can be displayed with )trace )stats and cleared with - )trace )stats reset. - - )varbreak var1 [... varN] - causes a Lisp break loop to be entered after the assignment to any of the - listed variables in the traced function. - - )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 - description of command )compile ) using the )vartrace option in order to - support this option. - - )vars var1 [... varN] - 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 description of command )compile ) using the - )vartrace option in order to support this option. - - )within executingFunction - causes the display of trace information only if the traced function is - called when the given executingFunction is running. - -The following are the options for tracing constructors, domains and packages. - - )local [op1 [... opN]] - 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 _ before the semicolon. - - )trace FRAC )local - )trace FRAC_;cancelGcd )off - - )ops op1 [... opN] - 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 - - )trace Integer )ops min max _+ _- - - traces four operations from the domain Integer. Since + and - are special - characters, it is necessary to escape them with an underscore. - -Also See: -o )boot -o )lisp -o )ltrace - -@ - -\section{command undo} -<>= -==================================================================== -A.27. )undo -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )undo - - )undo integer - - )undo integer [option] - - )undo )redo - -where option is one of - - - )after - - )before - -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 )undo is an -integer which must designate some step number in the interactive session. - -)undo n -)undo n )after - -These commands return the state of the interactive environment to that -immediately after step n. If n is a positive number, then n refers to step -nummber n. If n is a negative number, it refers to the nth previous command -(that is, undoes the effects of the last -n commands). - -A )clear all resets the )undo facility. Otherwise, an )undo undoes the effect -of )clear with options properties, value, and mode, and that of a previous -undo. If any such system commands are given between steps n and n + 1 (n > -0), their effect is undone for )undo m for any 0 < m <= n . - -The command )undo is equivalent to )undo -1 (it undoes the effect of the -previous user expression). The command )undo 0 undoes any of the above system -commands issued since the last user expression. - -)undo n )before - -This command returns the state of the interactive environment to that -immediately before step n. Any )undo or )clear system commands given before -step n will not be undone. - -)undo )redo - -This command reads the file redo.input. created by the last )undo command. -This file consists of all user input lines, excluding those backtracked over -due to a previous )undo. - -Also See: -o )history -The command )history )write will eliminate the ``undone'' command lines of -your program. - -@ - -\section{command what} -<>= -==================================================================== -A.28. )what -==================================================================== - -User Level Required: interpreter - -Command Syntax: - - - )what categories pattern1 [pattern2 ...] - - )what commands pattern1 [pattern2 ...] - - )what domains pattern1 [pattern2 ...] - - )what operations pattern1 [pattern2 ...] - - )what packages pattern1 [pattern2 ...] - - )what synonym pattern1 [pattern2 ...] - - )what things pattern1 [pattern2 ...] - - )apropos pattern1 [pattern2 ...] - -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, - -)what synonym - -displays all command synonyms, - -)what synonym ver - -displays all command synonyms containing the substring ``ver'', - -)what synonym ver pr - -displays all command synonyms containing the substring ``ver'' or the -substring ``pr''. Output similar to the following will be displayed - ----------------- System Command Synonyms ----------------- - - -user-defined synonyms satisfying patterns: - ver pr - - - )apr ........................... )what things - )apropos ....................... )what things - )prompt ........................ )set message prompt - )version ....................... )lisp *yearweek* - -Several other things can be listed with the )what command: - - categories displays a list of category constructors. - commands displays a list of system commands available at your - user-level. Your user-level is set via the )set userlevel command. To get - a description of a particular command, such as ``)what'', issue )help - what. - domains displays a list of domain constructors. - operations displays a list of operations in the system library. - 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 )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 )clear all or )clear completely. It will be re-created if it is - needed again. - packages displays a list of package constructors. - synonym lists system command synonyms. - things displays all of the above types for items containing - the pattern strings as substrings. The command synonym )apropos is - equivalent to )what things. - -Also See: -o )display -o )set -o )show - -@ - -\section{syntax while} -<>= -==================================================================== -while loops -==================================================================== - -The repeat in a loop can be modified by adding one or more while -clauses. Each clause contains a predicate immediately following the -while keyword. The predicate is tested before the evaluation of the -body of the loop. The loop body is evaluated whenever the predicate -in a while clause is true. - -The syntax for a simple loop using while is - - while predicate repeat loopbody - -The predicate is evaluated before loopbody is evaluated. A while loop -terminates immediately when predicate evaluates to false or when a -leave or return expression is evaluted. See )help repeat for more -information on leave and return. - -Here is a simple example of using while in a loop. We first initialize -the counter. - - i := 1 - 1 - Type: PositiveInteger - - while i < 1 repeat - output "hello" - i := i + 1 - Type: Void - -The steps involved in computing this example are - (1) set i to 1 - (2) test the condition i < 1 and determine that it is not true - (3) do not evaluate the loop body and therefore do not display "hello" - - (x, y) := (1, 1) - 1 - Type: PositiveInteger - -If you have multiple predicates to be tested use the logical and -operation to separate them. Axiom evaluates these predicates from -left to right. - - while x < 4 and y < 10 repeat - output [x,y] - x := x + 1 - y := y + 2 - [1,1] - [2,3] - [3,5] - Type: Void - - -A leave expression can be included in a loop body to terminate a loop -even if the predicate in any while clauses are not false. - - (x, y) := (1, 1) - 1 - Type: PositiveInteger - - while x < 4 and y < 10 repeat - if x + y > 7 then leave - output [x,y] - x := x + 1 - y := y + 2 - [1,1] - [2,3] - Type: Void - -@ -\section{license} -<>= -Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd. -All rights reserved. -Text for this document is released under the license: -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - - - Neither the name of The Numerical ALgorithms Group Ltd. nor the - names of its contributors may be used to endorse or promote products - derived from this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS -IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A -PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER -OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF -LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -@ -\eject -\begin{thebibliography}{99} -\bibitem{1} Jenks, R.J. and Sutor, R.S. -``Axiom -- The Scientific Computation System'' -Springer-Verlag New York (1992) -ISBN 0-387-97855-0 -\end{thebibliography} -\end{document} diff --git a/src/interp/Makefile.pamphlet b/src/interp/Makefile.pamphlet index 0f2f801..7c48134 100644 --- a/src/interp/Makefile.pamphlet +++ b/src/interp/Makefile.pamphlet @@ -56,6 +56,38 @@ MID=${INT}/interp OUT=${OBJ}/${SYS}/interp DOC=${MNT}/${SYS}/doc/src/interp BOOK=${MNT}/${SYS}/doc +HELP=${MNT}/${SYS}/doc/spadhelp +BOOKSRC=${SPD}/books/bookvol5.pamphlet + +@ +<>= +SPADHELP=\ +abbreviations.help assignment.help blocks.help boot.help \ +browse.help cd.help clear.help clef.help \ +close.help collection.help compiler.help copyright.help \ +display.help edit.help fin.help for.help \ +frame.help help.help history.help if.help \ +include.help iterate.help leave.help library.help \ +lisp.help load.help ltrace.help parallel.help \ +pquit.help quit.help read.help repeat.help \ +savesystem.help set.help show.help spool.help \ +suchthat.help summary.help synonym.help syntax.help \ +system.help trace.help undo.help what.help \ +while.help with.help +@ + +This creates all of the help files in the SPADHELP list from the +interpreter book (volume 5). +<>= +spadhelp: + @echo 9 making ${HELP} files from ${BOOKSRC} + @(mkdir -p ${HELP} ; \ + cd ${HELP} ; \ + for i in ${SPADHELP} ; do \ + ${TANGLE} -R"$$i" ${BOOKSRC} >$$i ; \ + done ; \ + cat ${INT}/doc/help.helplist >>help.help ; \ + ls *.help >spadhelp.files ) @ @@ -8418,7 +8450,7 @@ ${OUT}/database.date: <> -all: ${SAVESYS} ${DOCFILES} ${DEBUGSYS} +all: ${SAVESYS} ${DOCFILES} ${DEBUGSYS} spadhelp @echo 618 finished ${IN} clean: @@ -8428,6 +8460,7 @@ clean: <> <> <> +<> <> <>