;;; -*- Mode:LISP; -*- ;;; Scheme Documentation Book: Scheme Manual, Version 4 ;Description: Contributors to the DECsystem-20 Manual and/or the Scheme Manual: ; Hal Abelson, Joseph A. Bowbeer, George J. Carrette, Soma Chaudhuri, ; Bill Chiarchiaro, Christopher P. Hanson, Steven T. Kirsch, ; Leigh L. Klotz, Wayne J. Noss, Patrick O'Donnell, Kent M. Pitman, ; Jon A. Reese, Guillermo Rozas, Kevin B. Theobald, Guy L. Steele, Jr., ; Gerald Jay Sussman, Julie Sussman, Daniel Weise, Jon L. White Copyright: Massachusetts Institute of Technology Break: No-Left-Hand-Pages: Chapter: Special Forms Begin-Entry: LAMBDA SpecialForm: (LAMBDA (var1 var2 ...) exp1 exp2 ...) Description: LAMBDA constructs procedure objects. It makes an unnamed procedure with formal parameters var1, var2, ... and a body consisting of exp1, exp2, .... A procedure object is executed by applying it to a number of arguments equal to the number of formal parameters. In a procedure application, each formal parameter is bound to the value of the corresponding argument supplied to the procedure. This produces an environment frame in which variable references in the body of the procedure can be resolved. The expressions in the body are then evaluated sequentially and the value of the last is returned as the value of the application. Free variables of the procedure (i.e. variables occurring in the body of the procedure which are not formal parameters of the procedure) find their values in the lexically enclosing environment. A LAMBDA combination consists of a LAMBDA expression together with argument expressions. Demo: ;; A lambda expression: ;; X, Y are formal parameters; +, Z are free variables. ==> (LAMBDA (X Y) (+ X Y Z)) [LAMBDA-PROCEDURE 143562] ;; A lambda combination ==> ((LAMBDA (X) (+ X 3)) 5) 8 ;; Name scoping is lexical: ==> (((LAMBDA (X) (LAMBDA (Y) (+ X Y))) 3) 4) 7 Description: SCHEME procedures can be defined to take variable numbers of arguments. This is an advanced feature. The general idea is that the formal parameter specification of a procedure is a pattern which is matched against the argument list. Variables in the formal parameters are bound to the corresponding parts of the argument list. The rule for fixed numbers of arguments given above is a special case of this rule. Thus, for example, the following work: Demo: ==> ((LAMBDA X X) 1 2 3) (1 2 3) ==> ((LAMBDA X (LENGTH X)) 1 2 3) 3 ==> ((LAMBDA (A B . C) (* A (+ B (LENGTH C)))) 3 4 'A 5) 18 End-Entry: LAMBDA Page-Break: Begin-Entry: LET SpecialForm: (LET bindings exp1 exp2 ...) Description: LET is used to define and initialize local variables, or, in other words, add a new frame of bindings to the environment. "Bindings" is an association list of the names of the local variables and the expressions whose values will be bound to these variables. The variables are bound to the given values only in the body of the LET. This is called the "scope" of the variables (i.e. nothing outside the body of the LET will know of the new frame -- thus it is local). All of the expressions whose values are being named in the LET are evaluated in the environment before the new frame is created. Therefore, the value of a variable in the bindings list will not depend on the new value bound to any other variable being bound in the let. The expressions in the body of the LET are sequentially evaluated and the value of the last one is returned. LET is "syntactic sugar" for the LAMBDA combination: ((LAMBDA (name1 name2 ...) exp1 exp2 ...) val1 val2 ...). Demo: ==> (DEFINE X 3) X ==> (LET ((X 5) (Y (+ X 1))) (+ X Y)) 9 ==> X 3 ==> (LET ((X 3) (Y 4)) (LET ((Z (+ X Y)) (X 1)) (* X Y Z))) 28 End-Entry: LET Begin-Entry: QUOTE SpecialForm: (QUOTE obj) Description: QUOTE returns obj unevaluated. A symbolic constant is notated using QUOTE. 'obj is a syntactic abbreviation for (QUOTE obj); both forms are equivalent, but the abbreviation is preferable for legibility. Example: (QUOTE (A B)) => (A B) Example: (QUOTE (+ 3 5)) => (+ 3 5) Example: '(+ 3 5) => (+ 3 5) Example: 'X => X End-Entry: QUOTE Page-Break: Begin-Entry: DEFINE SpecialForm: (DEFINE name exp) Description: Defines name to be a local variable and initializes it to the value of exp (name is not evaluated). A special syntax is provided for defining named procedures, namely, Code: (DEFINE (name var1 var2 ...) exp1 exp2 ...) Description: which is equivalent to Code: (DEFINE name (LAMBDA (var1 var2 ...) exp1 exp2)). Example: (DEFINE H 4) => H Example: H => 4 Example: (DEFINE J (LAMBDA (X) (+ 2 X))) => J Example: (J 4) => 6 Example: (DEFINE (F X) (+ X 5)) => F Example: (F 23) => 28 Example: (DEFINE (G X Y) (* (F X) X Y)) => G Example: (G 3 4) => 96 Description: The special syntax for defining named procedures, shown above, is a special case of the more general rule for defining procedures which return procedures as their values. Thus, for example Code: (DEFINE ((DERIV F DX) X) (/ (-- (F (+ X DX)) (F X)) DX)) Description: is equivalent to Code: (DEFINE DERIV (LAMBDA (F DX) (LAMBDA (X) (/ (-- (F (+ X DX)) (F X)) DX)))) End-Entry: DEFINE Begin-Entry: SET! SpecialForm: (SET! var exp) Description: SET! is used to assign a new value to a previously DEFINE'd (or LAMBDA bound) variable. The value of exp becomes the new value of var. var itself is not evaluated. An error will occur if var has not been already DEFINE'd (or LAMBDA bound). Use of SET! is rare in well written SCHEME code. End-Entry: SET! Begin-Entry: SEQUENCE SpecialForm: (SEQUENCE exp1 exp2 ...) Description: SEQUENCE is used for the evaluation of sequential expressions. It evaluates exp1 exp2 ... in order (from left to right!) and returns the value of the last evaluation. End-Entry: SEQUENCE Page-Break: Begin-Entry: IF SpecialForm: (IF predicate consequent alternative) Description: The primitive conditional expression. If the predicate expression has a value which is not NIL, the consequent expression is evaluated, otherwise the alternative expression is evaluated. If no alternative is supplied and the predicate fails, NIL is returned. Example: (IF (NIL? NIL) 'A 'B) => A Example: (IF (= 3 4) 'yes 'no) => no Example: (IF NIL 0 (+ 3 4)) => 7 End-Entry: IF Begin-Entry: COND SpecialForm: (COND clause1 clause2 ...) Description: A generalized conditional expression. Each clause is a list (P E1 E2 ...) consisting of a predicate expression, and any number of consequent expressions, E1, E2, .... The predicate expressions are evaluated sequentially until one evaluates to a value which is not NIL. When such a predicate is found, its associated consequents are evaluated sequentially and the value of the last is returned. The symbol ELSE may be used as the predicate part of the final clause, causing the consequent sequence of that clause to be evaluated when the predicates of all other clauses evaluate to NIL. If all of the predicates have value NIL and there is no ELSE clause, the value of the COND is NIL. Example: (COND (NIL 'LOSE) ((ZERO? 1) 3) (ELSE 'WIN)) => WIN Example: (COND ((EQ? 'A 'A) 'SAME) (ELSE 'HUH?)) => SAME Example: (COND ((EQ? 'A 'B) 'FOO)) => NIL End-Entry: COND Begin-Entry: AND SpecialForm: (AND exp1 exp2 ...) Description: AND evaluates expressions from left to right. If any expression evaluates to NIL, AND returns NIL and the remaining expressions are not evaluated. Otherwise AND returns the value of the last expression. Example: (AND (< 3 4) (> 6 5)) =>  Example: (AND (> 3 4) (> 6 5)) => NIL ;(> 6 5) is not evaluated. End-Entry: AND Begin-Entry: OR SpecialForm: (OR exp1 exp2 ...) Description: OR evaluates expressions from left to right. If some expression evaluates to a non-NIL value, OR returns the value of that expression and the remaining expressions are not evaluated. Otherwise, OR returns NIL. Example: (OR (EQ? 'X 'Y) (EQ? 'Z 'Y)) => NIL Example: (OR (NOT (NUMBER? X)) (> X 0) (= X 0) (< X 0)) =>  End-Entry: OR Page-Break: Begin-Entry: NOT Syntax: (NOT obj) Args: 1 arg Type: Procedure Description: NOT is used to complement a true/false value. NOT evaluates obj and returns  if its value is NIL, and returns NIL if its value is non-NIL. Example: (NOT (EQ? 'A 'A)) => NIL Example: (NOT (EQ? 'A 'B)) =>  End-Entry: NOT Begin-Entry: NIL? Syntax: (NIL? obj) Args: 1 arg Type: Procedure Description: NIL? evaluates obj and returns  if its value is NIL, and returns NIL if its value is non-NIL. NOT is equivalent to NIL?. The former is often used as a logical operator while the latter is used as a predicate. Stylistic conventions determine which is more appropriate in a particular context. End-Entry: NIL? Page-break: Chapter: Arithmetic Begin-Family: Numerical Functions Begin-Entry: + Syntax: (+ n1 n2 ...) Args: 0 or more args Type: Procedure Description: Returns the sum of its arguments. End-Entry: + Begin-Entry: 1+ Syntax: (1+ n) Args: 1 arg Type: Procedure Description: Adds one to its argument. End-Entry: 1+ Begin-Entry: -- Syntax: (-- n1 n2 n3 ...) Args: 0 or more args Type: Procedure Description: Returns the difference of its arguments, n1-n2-n3-... When applied to one argument, negates the argument. Example: (-- 10) => --10 Example: (-- 3 --7) => 10 End-Entry: -- Begin-Entry: --1+ Syntax: (--1+ n) Args: 1 arg Type: Procedure Description: Subtracts one from its argument. End-Entry: --1+ Begin-Entry: * Syntax: (* n1 n2 ...) Args: 0 or more args Type: Procedure Description: Returns the product of its arguments. End-Entry: * Begin-Entry: / Syntax: (/ x1 x2 ...) Args: 1 or more args Type: Procedure Description: Divides the first argument by all the subsequent ones. When applied to one argument, returns its reciprocal. Example: (/ 5) => 0.2 Example: (/ 8 4 2) => 1 End-Entry: / Begin-Entry: QUOTIENT Syntax: (QUOTIENT x1 x2) Args: 2 args Type: Procedure Description: Integer division. Returns the integer part of the quotient of x1 and x2. Example: (QUOTIENT 10 5) => 2 Example: (QUOTIENT 11 3) => 3 Example: (QUOTIENT 10 2.5) => 4 End-Entry: QUOTIENT Page-Break: Begin-Entry: MOD Syntax: (MOD x1 x2) Args: 2 args Type: Procedure Description: Returns the remainder of dividing x1 by x2. End-Entry: MOD Begin-Entry: REMAINDER Syntax: (REMAINDER x1 x2) Args: 2 args Type: Procedure Description: Returns the remainder of dividing x1 by x2. End-Entry: REMAINDER Begin-Entry: INTEGER-DIVIDE Syntax: (INTEGER-DIVIDE x1 x2) Args: 2 args Type: Procedure Description: Returns the dotted pair of the QUOTIENT and REMAINDER of x1 and x2. Example: (INTEGER-DIVIDE 11 3) => (3 . 2) End-Entry: INTEGER-DIVIDE Begin-Entry: GCD Syntax: (GCD n1 n2) Args: 1 or more arguments Type: Procedure Description: Returns the Greatest Common Divisor of n1 and n2. End-Entry: GCD Begin-Entry: ABS Syntax: (ABS n) Args: 1 arg Type: Procedure Description: Absolute value function. Example: (ABS --3.2) => 3.2 Example: (ABS 0) => 0 Example: (ABS 3.2) => 3.2 End-Entry: ABS Begin-Entry: FLOOR Syntax: (FLOOR n) Args: 1 arg Type: Procedure Description: Returns the greatest integer, i, such that i is less than or equal to n. Example: (FLOOR 2.4) => 2 Example: (FLOOR --2.4) => --3 Example: (FLOOR 2) => 2 End-Entry: FLOOR Begin-Entry: CEILING Syntax: (CEILING n) Args: 1 arg Type: Procedure Description: Returns the smallest integer, i, such that i is greater than or equal to n. Example: (CEILING 4.2) => 5 Example: (CEILING --4.2) => --4 Example: (CEILING --4) => --4 End-Entry: CEILING Page-Break: Begin-Entry: TRUNCATE Syntax: (TRUNCATE n) Args: 1 arg Type: Procedure Description: Returns the integer part of the number n. For positive numbers, this is the same as FLOOR while for negative numbers, this is the same as CEILING. Example: (TRUNCATE 2.4) => 2 Example: (TRUNCATE --4.2) => --4 End-Entry: TRUNCATE Begin-Entry: ROUND Syntax: (ROUND n) Args: 1 arg Type: Procedure Description: Rounds off the number n to the nearest integer. If n is halfway between two integers, ROUND selects the larger integer. Example: (ROUND 7.8) => 8 Example: (ROUND --3.5) => --3 End-Entry: ROUND Begin-Entry: MAX Syntax: (MAX n1 n2 ...) Args: 1 or more args Type: Procedure Description: Returns its largest argument. list. Example: (MAX --1 3 0) => 3 End-Entry: MAX Begin-Entry: MIN Syntax: (MIN n1 n2 ...) Args: 1 or more args Type: Procedure Description: Returns its smallest argument. Example: (MIN --1 3 0) => --1 End-Entry: MIN Page-Break: Begin-Entry: SIN Syntax: (SIN n) Args: 1 arg Type: Procedure Description: Returns the trigonometric sine of the angle n. n is assumed to be given in radians. End-Entry: SIN Begin-Entry: ASIN Syntax: (ASIN y r) Args: 2 args Type: Procedure Description: Returns the arc sine, in radians, of y/r. This is the measure of the angle of a right triangle with hypotenuse of length r and side opposite to angle of length y. End-Entry: ASIN Begin-Entry: COS Syntax: (COS n) Args: 1 arg Type: Procedure Description: Returns the trigonometric cosine of the angle n. n is assumed to be given in radians. End-Entry: COS Begin-Entry: ACOS Syntax: (ACOS x r) Args: 2 args Type: Procedure Description: Returns the arc cosine, in radians, of x/r. This is the measure of the angle of a right triangle with hypotenuse of length r and side adjacent to angle of length x. End-Entry: ACOS Begin-Entry: TAN Syntax: (TAN n) Args: 1 arg Type: Procedure Description: Returns the tangent of the angle n. n is assumed to be given in radians. End-Entry: TAN Begin-Entry: ATAN Syntax: (ATAN y x) Args: 2 args Type: Procedure Description: Returns the arc tangent, in radians, of y/x. This is the measure of the angle of a right triangle with side opposite to angle of length y, and side adjacent to angle of length x. Note: We pass two arguments, y and x, to ATAN, rather than their quotient because dividing loses the signs of y and x, thus losing information about which quadrant the desired angle is in. End-Entry: ATAN Begin-Entry: LOG Syntax: (LOG n) Args: 1 arg Type: Procedure Description: Natural logarithm. Returns the log, base e, of n. End-Entry: LOG Begin-Entry: EXP Syntax: (EXP x) Args: 1 arg Type: Procedure Description: Returns e raised to the x power. End-Entry: EXP Begin-Entry: EXPT Syntax: (EXPT x y) Args: 2 args Type: Procedure Description: Exponentiation. Returns x raised to the power of y. End-Entry: EXPT Begin-Entry: SQRT Syntax: (SQRT n) Args: 1 arg Type: Procedure Description: Square root. Returns the square root of n. End-Entry: SQRT End-Family: Numerical Functions Page-Break: Begin-Family: Numerical Predicates Begin-Entry: NUMBER? Syntax: (NUMBER? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is a number, otherwise returns NIL. Example: (NUMBER? 'A) => NIL Example: (NUMBER? 3) =>  Example: (NUMBER? 2.3) =>  End-Entry: NUMBER? Begin-Entry: INTEGER? Syntax: (INTEGER? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is an integer, otherwise returns NIL. End-Entry: INTEGER? Begin-Entry: ODD? Syntax: (ODD? n) Args: 1 arg Type: Procedure Description: Returns  if n is an odd integer, returns NIL if even. May only be applied to an integer. End-Entry: ODD? Begin-Entry: EVEN? Syntax: (EVEN? n) Args: 1 arg Type: Procedure Description: Returns  if n is an even integer, returns NIL if odd. May only be applied to an integer. End-Entry: EVEN? Begin-Entry: ZERO? Syntax: (ZERO? n) Args: 1 arg Type: Procedure Description: N must be a number. Returns  if n = 0, otherwise returns NIL. Example: (ZERO? 0) =>  Example: (ZERO? 65) => NIL End-Entry: ZERO? Begin-Entry: NEGATIVE? Syntax: (NEGATIVE? n) Args: 1 arg Type: Procedure Description: N must be a number. Returns  if n < 0, otherwise returns NIL. Example: (NEGATIVE? --238472234234234233) =>  Example: (NEGATIVE? 0) => NIL Example: (NEGATIVE? 4.5) => NIL End-Entry: NEGATIVE? Begin-Entry: POSITIVE? Syntax: (POSITIVE? n) Args: 1 arg Type: Procedure Description: N must be a number. Returns  if n > 0, otherwise returns NIL. Example: (POSITIVE? 4) =>  Example: (POSITIVE? 0.0) => NIL Example: (POSITIVE? --0.0002) => NIL End-Entry: POSITIVE? Page-Break: Begin-Entry: = Syntax: (= x1 x2 ...) Args: 2 or more args Type: Procedure Description: Returns  if all of the arguments have the same numerical value, otherwise returns NIL. The arguments must be numbers. Example: (= 3 3.0) =>  Example: (= 3.5 3.0) => NIL End-Entry: = Begin-Entry: > Syntax: (> x1 x2 ...) Args: 2 or more args Type: Procedure Description: Returns  if each argument is strictly greater than all subsequent arguments, otherwise returns NIL. The arguments must be numbers. Example: (> 3.0 4 5.6) => NIL Example: (> 5.3 3 2) =>  Example: (> 5.3 2 3) => NIL End-Entry: > Begin-Entry: >= Syntax: (>= x1 x2 ...) Args: 2 or more args Type: Procedure Description: Returns  if each argument is greater than or equal to all subsequent arguments, otherwise returns NIL. The arguments must be numbers. Example: (>= 4.0 5.0 5.0) => NIL Example: (>= 4.6 3.8 3.8) =>  End-Entry: >= Begin-Entry: < Syntax: (< x1 x2 ...) Args: 2 or more args Type: Procedure Description: Returns  if each argument is strictly less than all subsequent arguments, otherwise returns NIL. The arguments must be numbers. Example: (< 3.0 4 5.6) =>  Example: (< 5.3 3 2) => NIL Example: (< 5.3 2 3) => NIL End-Entry: < Begin-Entry: <= Syntax: (<= x1 x2 ...) Args: 2 or more args Type: Procedure Description: Returns  if each argument is less than or equal to all subsequent arguments, otherwise returns NIL. The arguments must be numbers. Example: (<= 3 3 4 5.8) =>  Example: (<= 2 1.7 4 4) => NIL End-Entry: <= End-Family: Numerical Predicates Page-Break: Begin-Family: Miscellaneous Numerical Procedures Begin-Entry: RANDOM Syntax: (RANDOM [n]) Args: 0 or1 args Type: Procedure Description: Returns a random integer between 0 and n-1, inclusive. If no argument is given, RANDOM returns any integer. End-Entry: RANDOM Begin-Entry: RANDOMIZE Syntax: (RANDOMIZE q) Args: 1 arg Type: Procedure Description: RANDOMIZE is used to initialize the random number generator. If q is NIL, the generator is initialized with an arbitrary (random) seed. Otherwise, q should be an integer and the generator is initialized with q as its seed. End-Entry: RANDOMIZE Begin-Entry: HASH Syntax: (HASH object n) Args: 2 args Type: Procedure Description: Returns an integer between 0 and n-1, inclusive, which can be used as a hash value for object. Example: (HASH 'ABC 87) => 18 Example: (HASH 'DEF 87) => 69 Example: (HASH '(A B) 23) => 12 End-Entry: HASH End-Family: Miscellaneous Numerical Procedures Chapter: Compound Data Begin-Family: List Structure Constructors Description: The pair is an object which is used to bond two objects together. These component objects may be atoms or pairs. Any structure built out of pairs is called a "list structure", but confusingly enough, list itself describes a special type of list structure. In a "normal" list, the CDR of each pair is another pair, with the exception that the CDR of the last pair is a special atom , the empty list. Thus the elements of a list are stored in the CAR slots of its pairs, while the CDR slots are used to link the elements together. Begin-Entry: CONS Syntax: (CONS obj1 obj2) Args: 2 args Type: Procedure Description: CONS is the constructor of a pair whose CAR is obj1 and whose CDR is obj2. By definition, (CAR (CONS a b)) = a and (CDR (CONS a b)) = b. If obj2 is a list, CONS makes a new list which has obj1 as its first element and obj2 as the rest of the elements. Example: (CONS '(A B) '(C D)) => ((A B) C D) Example: (CONS 'A '(B C)) => (A B C) Example: (CONS 'A 'B) => (A . B) End-Entry: CONS Begin-Entry: CONS* Syntax: (CONS* obj1 obj2 ...) Args: 0 or more args Type: Procedure Description: CONS* CONSes together an arbitrary number of arguments. CONS* constructs a pair whose CAR is obj1 and whose CDR is (CONS* obj2 ...) : (CONS obj1 (CONS* obj2 ...)). When it has only two arguments, it behaves in the same way as CONS. Example: (CONS* 'A 'B 'C) => (A B . C) Example: (CONS* '(A B) 'C '(D E)) => ((A B) C D E) Example: (CONS* 'A 'B) => (A . B) End-Entry: CONS* Begin-Entry: LIST Syntax: (LIST obj1 obj2 ...) Args: 0 or more args Type: Procedure Description: LIST constructs a list whose elements are obj1, obj2,.. etc. Example: (LIST 'A 'B 'C) => (A B C) Example: (LIST '(A B) '3 '(FOO BAR)) => ((A B) 3 (FOO BAR)) End-Entry: LIST End-Family: List Structure Constructors Page-Break: Begin-Family: List Structure Selectors Begin-Entry: CAR Syntax: (CAR pair) Args: 1 arg Type: Procedure Description: CAR selects the CAR component of a pair. If pair is a list, the CAR is the first element of the list. Example: (CAR '(A)) => A Example: (CAR '(A B)) => A Example: (CAR '((A B) C D)) => (A B) Example: (CAR NIL) => NIL ; By convention Example: (CAR '((A B) . (C D))) => (A B) Example: (CAR '(Y . X)) => Y End-Entry: CAR Begin-Entry: CDR Syntax: (CDR pair) Args: 1 arg Type: Procedure Description: CDR selects the CDR component of a pair. If pair is a list, the CDR is the list of all of the elements except the first one. Example: (CDR '(A)) => NIL Example: (CDR '(A B)) => (B) Example: (CDR '((A B) C D)) => (C D) Example: (CDR NIL) => NIL ;By convention Example: (CDR '((A B) . (C D))) => (C D) Example: (CDR '(Y . X)) => X End-Entry: CDR Begin-Entry: C...R Syntax: (C...R l) Type: Procedure Args: 1 arg Description: Short names for up to four levels of CAR/CDR compositions are provided in Scheme. eg, (CAAR l) is (CAR (CAR l)) and (CADAAR l) is (CAR (CDR (CAR (CAR l)))). Example: (CAR '(A (B C) D)) => A Example: (CADR '(A (B C) D)) => (B C) Example: (CDDR '(A (B C) D)) => (D) Example: (CADADR '(A (B C) D)) => C End-Entry: C...R End-Family: List Structure Selectors Page-Break: Begin-Family: List Structure Mutators Description: Note: in the following descriptions, values are shown for calls to mutators only for completeness. Please do not use a mutator for its value. It is bad programming practice because it depends upon the order of evaluation of arguments. Thus we make no promises about whether the values indicated for the mutators (or SET!) will be the same in any future version of SCHEME. Begin-Entry: SET!-CAR Syntax: (SET!-CAR pair newcar) Args: 2 args Type: Procedure Description: Mutates a pair so that its CAR becomes newcar. Returns the pair. Example: (SET! A '(A B)) => (A B) Example: A => (A B) Example: (SET!-CAR (CDR A) 3) => (3) Example: A => (A 3) End-Entry: SET!-CAR Begin-Entry: SET!-CDR Syntax: (SET!-CDR pair newcdr) Args: 2 args Type: Procedure Description: Mutates a pair so that its CDR becomes newcdr. Returns the pair. Example: (SET! B '(A B C)) => (A B C) Example: (SET!-CDR B 'E) => (A . E) Example: B => (A . E) End-Entry: SET!-CDR End-Family: List Structure Mutators Begin-Family: List Structure Predicates Begin-Entry: ATOM? Syntax: (ATOM? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is an atom and otherwise returns NIL. Pairs are the bond by which list structure is constructed from the basic elements, or atoms. An atom is anything which cannot be further decomposed via CAR or CDR; in other words, everything that is not a pair is an atom. Example: (ATOM? 3) =>  Example: (ATOM? 'CAR) =>  Example: (ATOM? CAR) =>  Example: (ATOM? '(A 3)) => NIL Example: (ATOM? '()) =>  Example: (ATOM? NIL) =>  End-Entry: ATOM? Page-Break: Begin-Entry: SYMBOL? Syntax: (SYMBOL? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is an atomic symbol (variable or NIL), otherwise returns NIL. Example: (SYMBOL? 3) => NIL Example: (SYMBOL? 'CAR) =>  Example: (SYMBOL? CAR) => NIL Example: (SYMBOL? NIL) =>  End-Entry: SYMBOL? Begin-Entry: PAIR? Syntax: (PAIR? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is of datatype PAIR. Note: The empty list, ', is a list but not a pair. Example: (PAIR? '(A B)) =>  Example: (PAIR? ') => NIL Example: (PAIR? 'A) => NIL Example: (PAIR? '(A . B)) =>  End-Entry: PAIR? Begin-Entry: LIST? Syntax: (LIST? obj) Args: 1 arg Type: Procedure Description: LIST? is used to determine whether an object is a list. A list is either NIL or a pair whose CDR is a list. Example: (LIST? 'A) => NIL Example: (LIST? ') =>  Example: (LIST? '(A B)) =>  Example: (LIST? '(A . B)) => NIL End-Entry: LIST? Begin-Entry: NULL? Syntax: (NULL? obj) Args: 1 arg Type: Procedure Description: Returns  if obj is ', and NIL if obj is non-'. Example: (NULL? '(A B C)) => NIL Example: (NULL? ') =>  Example: (NULL? NIL) =>  End-Entry: NULL? Page-Break: Begin-Entry: EQ? Syntax: (EQ? obj1 obj2) Args: 2 args Type: Procedure Description: EQ? is the primitive equivalence predicate. It returns  if obj1 and obj2 are the same object. Unless you are rather advanced, do not use EQ? to test identity of objects other than atomic symbols. In particular, two numbers which are equal in value may not be EQ?; use "=" to test numerical equality. Also, two lists which have the same elements and print the same may not be EQ?; use EQUAL? to test if lists have the same elements. Description: For more advanced users only: Two structures are EQ? if any attempt to modify one of them modifies the other in the same way. From a pragmatic point of view, EQ? tests if the two structures share the same location in the memory space. Example: (DEFINE X '(A B)) => X Example: (DEFINE Y '(A B)) => Y Example: (DEFINE Z X) => Z Example: (EQ? X Y) => NIL Example: (EQ? X Z) =>  Example: (EQ? Y Z) => NIL Example: (SET! X 'FOO) => FOO Example: (SET! Y 'FOO) => FOO Example: (SET! Z X) => FOO Example: (EQ? X Y) =>  Example: (EQ? X Z) =>  Example: (EQ? Y Z) =>  Example: (EQ? 1000 1000) => NIL Example: (EQ? 3 3) =>  End-Entry: EQ? Begin-Entry: EQUAL? Syntax: (EQUAL? obj1 obj2) Args: 2 args Type: Procedure Description: EQUAL? is a list structure equivalence predicate which returns  if both args are EQ? atoms, or = numbers, or are lists of the same length and component-wise EQUAL?. That is, EQUAL? lists have an identical arrangement of atoms, with each such atom in obj1 being EQ? (or =) to the corresponding atom in obj2. As illustrated below, EQ? and EQUAL? are quite different. Example: (EQ? '(A B) '(A B)) => NIL Example: (EQUAL? '(A B) '(A B)) =>  Example: (DEFINE X '(A B)) => (A B) Example: (DEFINE Y '(A B)) => (A B) Example: (EQUAL? X Y) =>  Example: (EQUAL? 3 3) =>  Example: (EQUAL? 1000 1000) =>  End-Entry: EQUAL? End-Family: List Structure Predicates Page-Break: Begin-Family: Commonly Useful List Functions Begin-Entry: NTHCDR Syntax: (NTHCDR n l) Args: 2 args Type: Procedure Description: NTHCDR selects the nth CDR of the list l. (if n is 0, l is returned). Example: (NTHCDR 0 '(A B)) => (A B) Example: (NTHCDR 2 '(A B C D)) => (C D) End-Entry: NTHCDR Begin-Entry: NTH Syntax: (NTH n l) Args: 2 args Type: Procedure Description: NTH is the short form for (CAR (NTHCDR n l)). It selects the (n+1)th element of the list l. If n=0, NTH returns the CAR of the list. Example: (NTH 0 '(A B C D)) => A Example: (NTH 2 '(A B C)) => C Example: (NTH 4 '(A B)) => NIL End-Entry: NTH Begin-Entry: LAST Syntax: (LAST list) Args: 1 arg Type: Procedure Description: Returns the last pair of list. Example: (LAST '(A B C)) => (C) End-Entry: LAST Begin-Entry: LENGTH Syntax: (LENGTH l) Args: 1 arg Type: Procedure Description: Returns the length of its argument l, which must be a list. Example: (LENGTH '()) => 0 Example: (LENGTH '(A B C)) => 3 End-Entry: LENGTH Begin-Entry: APPEND Syntax: (APPEND l1 l2 ...) Args: 0 or more args Type: Procedure Description: Constructs a list whose elements are, in order, the elements of each of the lists given as its arguments. Cf. LIST. Example: (APPEND '(A) '(B C) '(D)) => (A B C D) Example: (APPEND '((A B) C) '((D E))) => ((A B) C (D E)) Example: (APPEND '(A B) '()) => (A B) End-Entry: APPEND Page-Break: Begin-Entry: REVERSE Syntax: (REVERSE l) Args: 1 arg Type: Procedure Description: Constructs a list which contains the elements of the list l in reverse order. Example: (DEFINE A '(A B C)) => A Example: (REVERSE A) => (C B A) Example: A => (A B C) Example: (REVERSE '(A (B C) D)) => (D (B C) A) End-Entry: REVERSE Begin-Entry: CONC! Syntax: (CONC! list1 list2) Args: 2 args Type: Procedure Description: Mutates list1 so that it includes all the elements of the original list1 and the elements of list2 in that order. CONC! is similar to APPEND except that it is a mutator while APPEND is a constructor. Example: (DEFINE L1 '(A B)) => L1 Example: (DEFINE L2 '(C D)) => L2 Example: (APPEND L1 L2) => (A B C D) Example: L1 => (A B) Example: L2 => (C D) Example: (CONC! L1 L2) => (A B C D) Example: L1 => (A B C D) Example: L2 => (C D) End-Entry: CONC! Begin-Entry: MAPCAR Syntax: (MAPCAR fn list1 list2 ...) Args: 2 or more args Type: Procedure Description: fn must be a procedure which takes as many arguments as there are lists supplied to MAPCAR. Applies fn to the successive lists of CARs of all of the lists supplied, CONSing up a list of the results. Example: (MAPCAR length '((a b) (c d) (e (f g) h))) => (2 2 3) Example: (MAPCAR + '(1 2 3) '(4 5 6)) => (5 7 9) End-Entry: MAPCAR Begin-Entry: MAPCAN Syntax: (MAPCAN fn list1 list2 ...) Args: 2 or more args Type: Procedure Description: fn must be a procedure which takes as many arguments as there are lists supplied to MAPCAN. Applies fn to the successive lists of CARs of all of the lists supplied, CONC!ing up a list of the results. Each result, of course, has to be a list. End-Entry: MAPCAN Begin-Entry: MAPC Syntax: (MAPC fn list1 list2 ...) Args: 2 or more args Type: Procedure Description: fn must be a procedure which takes as many arguments as there are lists supplied to MAP. Applies fn to the successive lists of CARs of all of the lists supplied. This is done for effect, the results are ignored. End-Entry: MAPC End-Family: Commonly Useful List Functions Page-Break: Begin-Family: Lists as sets and tables Begin-Entry: MEMQ Syntax: (MEMQ obj list) Args: 2 args Type: Procedure Description: Using EQ?, tests each object in list to see if it is the same as obj. Returns the first sublist of list beginning with obj, or NIL if obj doesn't occur in list. Example: (MEMQ 'B '(A B C A B C)) => (B C A B C) Example: (MEMQ 'Q '(A B C A B C)) => NIL Example: (MEMQ 'A '((A B) A D)) => (A D) Example: (MEMQ '(A B) '(A (A B) C)) => NIL End-Entry: MEMQ Begin-Entry: MEMBER Syntax: (MEMBER obj list) Args: 2 args Type: Procedure Description: Using EQUAL?, tests each object in list to see if it is the same as obj. Returns the first sublist of list beginning with obj, or NIL if obj doesn't occur in list. Example: (MEMBER '(A B) '(A (A B) C)) => ((A B) C) Example: (MEMBER 'B '(A B C)) => (B C) Example: (MEMBER 3.0 '(3 4 5)) => (3 4 5) End-Entry: MEMBER Begin-Entry: ASSQ Syntax: (ASSQ obj alist) Args: 2 args Type: Procedure Description: alist is presumed to be a list of pairs representing a table. The CAR of each pair is the key to the table and the CDR is the information stored in the table under that key. ASSQ tests each pair in alist to see if its CAR is EQ? to obj. ASSQ returns the first element of alist whose CAR is obj, or NIL if obj doesn't occur in the CAR of any element of alist. Thus ASSQ is useful for table lookup if the keys are atomic symbols. Example: (ASSQ 'A '((D E) (A B) (C D))) => (A B) Example: (ASSQ '(A B) '((D E) ((A B) C) (B D))) => NIL ;see below End-Entry: ASSQ Begin-Entry: ASSOC Syntax: (ASSOC obj alist) Args: 2 args Type: Procedure Description: alist is presumed to be a list of pairs representing a table. The CAR of each pair is the key to the table and the CDR is the information stored in the table under that key. ASSOC tests each pair in alist to see if its CAR is EQUAL? to obj. ASSOC returns the first element of alist whose CAR is obj, or NIL if obj doesn't occur in the CAR of any element of alist. Thus ASSOC is useful for table lookup in situations where the table keys are not symbols. Example: (ASSQ '(A B) '((D E) ((A B) C) (B D))) => ((A B) C) Example: (ASSOC 3 '((1 A) (2 B) (3 C))) => (3 C) Example: (ASSOC 4 '((1 A) (2 B) (3 C))) => NIL End-Entry: ASSOC End-Family: Lists as sets and tables Page-Break: Begin-Family: Arrays Description: There are two sets of commands for creating and using arrays. MAKE-ARRAY and AMAKE are similar in that they both create initialized arrays. SET!-ARRAY and ASET! are similar in that they are both used to assign values to the cells in arrays. ACCESS-ARRAY and AREF are similar in that they are both used to retrieve values from the cells in arrays. However, they differ in the way cells are referenced. In MAKE-ARRAY, SET!-ARRAY and ACCESS-ARRAY, the cell is specified by one argument, a list of the coordinates of the cell. AMAKE, ASET! and AREF, on the other hand, accept the coordinates as individual arguments. Though the syntax used in the former case is more systematic and consistent, the syntax of the latter case is easier for typing. Begin-Entry: MAKE-ARRAY Syntax: (MAKE-ARRAY bounds initproc) Args: 2 args Type: Procedure Description: Constructs an array with the given bounds and initializes cells as specified by initproc. The variable "bounds" is a list of integers, each of whose elements gives the number of distinct subscript values for the corresponding dimension. Arrays in SCHEME are zero-based; the maximum subscript along any dimension is one less than the bound. initproc is a procedure of one argument, a list of coordinates identifying one array cell, which computes the initial value for that array cell. initproc can be NIL, in which case the array is not initialized. End-Entry: MAKE-ARRAY Begin-Entry: ACCESS-ARRAY Syntax: (ACCESS-ARRAY a coords) Args: 2 args Type: Procedure Description: Returns the value located in the cell of the array, a, specified by coords, the list of subscript values i1, i2, ... End-Entry: ACCESS-ARRAY Begin-Entry: SET!-ARRAY Syntax: (SET!-ARRAY a coords val) Args: 3 args Type: Procedure Description: Stores val into the cell of the array, a, specified by coords, the list of subscript values i1, i2, ... Example: (DEFINE A (MAKE-ARRAY '(10 20) (LAMBDA (coords) (+ (CAR coords) (CADR coords))))) => A Example: (ACCESS-ARRAY A '(3 14)) => 17 Example: (SET!-ARRAY A '(3 14) 'FOO) => FOO Example: (ACCESS-ARRAY A '(3 14)) => FOO Example: (DEFINE B (MAKE-ARRAY '(5 5) NIL)) => B Example: (SET!-ARRAY B '(2 1) 'BAR) => BAR Example: (ACCESS-ARRAY B '(2 1)) => BAR End-Entry: SET!-ARRAY Page-Break: Begin-Entry: DIMENSIONS-ARRAY Syntax: (DIMENSIONS-ARRAY ar) Args: 1 arg Type: Procedure Description: Returns a list of the bounds of the array, ar. Example: (DIMENSIONS-ARRAY (MAKE-ARRAY '(3 5) NIL)) => (3 5) End-Entry: DIMENSIONS-ARRAY Begin-Entry: ARRAY? Syntax: (ARRAY? obj) Args: 1 arg Type: Procedure Description: Predicate; returns  if obj is an ARRAY, otherwise returns NIL. Example: (DEFINE A (MAKE-ARRAY '(10) NIL)) => A Example: (ARRAY? A) =>  Example: (ARRAY? 'A) => NIL End-Entry: ARRAY? Begin-Entry: AMAKE Syntax: (AMAKE initproc bound1 bound2 ...) Args: 2 or more args Type: Procedure Description: Constructs an array with the given bounds. initproc, a procedure of n arguments (where n is the number of dimensions of the array), is used to initialize the array. When initproc is NIL, the array is not initialized. End-Entry: AMAKE Begin-Entry: AREF Syntax: (AREF a i1 i2 ...) Args: 2 or more args Type: Procedure Description: Returns the value located in the cell of the array, a, specified by the subscripts i1, i2, ... End-Entry: AREF Begin-Entry: ASET! Syntax: (ASET! val a i1 i2 ...) Args: 3 or more args Type: Procedure Description: Stores val into the cell of the array, a, specified by the subscripts i1, i2, ... Example: (DEFINE A (AMAKE (LAMBDA (X Y) (+ X Y)) 5 8)) => A Example: (AREF A 3 7) => 10 Example: (ASET! 'FOO A 3 7) => FOO Example: (AREF A 3 7) => FOO End-Entry: ASET! End-Family: Arrays Page-Break: Begin-Family: Properties Begin-Entry: PUT!-PROP Syntax: (PUT!-PROP sym propname val) Args: 3 args Type: Procedure Description: PUT!-PROP is used to specify the properties of an atomic symbol. It assigns val to the propname property of sym. End-Entry: PUT!-PROP Begin-Entry: GET-PROP Syntax: (GET-PROP sym propname) Args: 2 args Type: Procedure Description: GET-PROP is used to retrieve properties of atomic symbols. It gets the value of the propname property of sym. If none is found it returns NIL. End-Entry: GET-PROP Begin-Entry: REMOVE!-PROP Syntax: (REMOVE!-PROP sym propname) Args: 2 args Type: Procedure Description: REMOVE!-PROP is used to remove properties of atomic symbols. It removes the value assigned to the propname property of sym. If sym had such a value, the old value is returned; otherwise NIL is returned. End-Entry: REMOVE!-PROP Begin-Entry: LIST-PROP Syntax: (LIST-PROP sym) Args: 1 arg Type: Procedure Description: LIST-PROP returns an association list representing the property list of sym. This association list has the form: (...(propname2 val2) (propname1 val1)). Example: (LIST-PROP 'JOE) => NIL Example: (PUT!-PROP 'JOE 'FATHER 'ARTHUR) => ARTHUR Example: (LIST-PROP 'JOE) => ((FATHER ARTHUR)) Example: (GET-PROP 'JOE 'MOTHER) => NIL Example: (PUT!-PROP 'JOE 'MOTHER 'ANNE) => ANNE Example: (LIST-PROP 'JOE) => ((MOTHER ANNE) (FATHER ARTHUR)) Example: (GET-PROP 'JOE 'MOTHER) => ANNE Example: (REMOVE!-PROP 'JOE 'MOTHER) => ANNE Example: (LIST-PROP 'JOE) => ((FATHER ARTHUR)) End-Entry: LIST-PROP End-Family: Properties Page-Break: Begin-Family: Miscellaneous Begin-Entry: PRIMITIVE-TYPE Syntax: (PRIMITIVE-TYPE obj) Args: 1 arg Type: Procedure Description: Returns the datatype of obj. Example: (PRIMITIVE-TYPE 3) => NUMBER Example: (PRIMITIVE-TYPE 'A) => SYMBOL Example: (PRIMITIVE-TYPE NIL) => NULL Example: (PRIMITIVE-TYPE '(A B)) => PAIR Example: (PRIMITIVE-TYPE CAR) => PRIMITIVE-PROCEDURE Example: (PRIMITIVE-TYPE TOP-LEVEL-ENVIRONMENT) => ENVIRONMENT Example: (PRIMITIVE-TYPE (MAKE-ARRAY '(2 3) NIL)) => ARRAY Example: (PRIMITIVE-TYPE (LAMBDA (X) (* X X))) => COMPOUND-PROCEDURE End-Entry: PRIMITIVE-TYPE Begin-Entry: EXTEND? Syntax: (EXTEND? obj) Args: 1 arg Type: Procedure Description: EXTEND? is a predicate which returns  if obj is neither an atomic symbol nor a number nor a list, and returns NIL otherwise. Procedures, arrays, and environment representations are all extended objects. Example: (EXTEND? CAR) =>  Example: (EXTEND? 'CAR) => NIL End-Entry: EXTEND? Begin-Entry: APPLICABLE? Syntax: (APPLICABLE? obj) Args: 1 arg Type: Procedure Description: APPLICABLE? is a predicate which returns  if obj is either a primitive or compound procedure. Example: (APPLICABLE? CAR) =>  Example: (APPLICABLE? (LAMBDA (X) X)) =>  End-Entry: APPLICABLE? Begin-Entry: ALPHALESS? Syntax: (ALPHALESS? sym1 sym2) Args: 2 args Type: Procedure Description: Both arguments must be atomic symbols. ALPHALESS? returns  if sym1 precedes sym2 in alphabetical order, otherwise returns NIL. (Note that ASCII values are used for ordering, which means that lower case letters, digits, or other odd characters may cause unexpected results for those not familiar with the table of ASCII codes.) Example: (ALPHALESS? 'COT 'CAT) => NIL Example: (ALPHALESS? 'ANT 'AXE) =>  Example: (ALPHALESS? 'SAME 'SAME) => NIL End-Entry: ALPHALESS? End-Family: Miscellaneous Chapter: System Support Begin-Entry: LOAD Syntax: (LOAD filename [echo]) Args: 1 or 2 args Type: Procedure Description: Reads and evaluates sequentially each of the expressions in the specified filename. If echo is provided, and is non-NIL, the value of each expression will be typed on the console as it is loaded. End-Entry: LOAD Begin-Entry: PP Syntax: (PP expression) Args: 1 arg Type: Procedure Description: PP is the pretty-printer which prints out the expression in a nice form, so as to show up its structure easily. End-Entry: PP Begin-Entry: PHOTO Syntax: (PHOTO filename) Args: 1 arg Type: Procedure Description: Used in conjunction with TOFU and the TOPS-20 PRINT command to produce a hardcopy listing of your console session. PHOTO begins recording the console session; file filename is created to hold the photo. The TOFU command is used to stop the recording process. The TOPS-20 PRINT command should be used to actually print the photo on the lineprinter. End-Entry: PHOTO Begin-Entry: TOFU Syntax: (TOFU) Args: No args Type: Procedure Description: Closes the photo file and stops the recording process. End-Entry: TOFU Begin-Entry: BKPT Syntax: (BKPT message irritant) Args: 2 args Type: Procedure Description: Sets a breakpoint -- useful in debugging. message and irritant are typed and a breakpoint is set in the current environment. Within a breakpoint, expressions may be typed and will be evaluated in the breakpoint environment. To exit from the breakpoint and proceed with the interrupted process, type the symbol $P (escape P) followed by a space. Demo: ==> (SEQUENCE (PRINT 'FOO) (BKPT 'TEST-2 'TEST-3) (PRINT 'BAR) 'DONE) FOO Bkpt! TEST-2 TEST-3 Level : 2 Bkpt-> (+ 3 3) 6 Bkpt-> $P BAR DONE End-Entry: BKPT Page-Break: Begin-Entry: ERROR Syntax: (ERROR message irritant) Args: 2 args Description: Signals an error. Types message (and irritant) on the console and creates a debugging breakpoint in the current environment. message is a description of the error and irritant is the offending expression, or "irritant". End-Entry: ERROR Begin-Entry: QUIT Syntax: (QUIT) Args: No args Type: Procedure Description: Suspend SCHEME and return to the TOPS-20 monitor. QUIT doesn't reset the SCHEME fork. End-Entry: QUIT Begin-Entry: EDIT Syntax: (EDIT) Type: Procedure Description: Internal link to the text editor. Requests that SCHEME suspend itself temporarily and transfer to the editor, EMACS. Once in EMACS, make necessary fixes and use one or more of the following commands to send the altered code back to SCHEME. Note: EMACS automatically saves your buffer before returning to SCHEME. Display: {esc}Z Mark current DEFINE for eventual transmission back to SCHEME. ^X Z Return to Scheme, sending any marked DEFINE's. ^Z Y Transmit the current DEFINE back to SCHEME -- a combination of {esc}Z and ^X Z. {esc}O Transmit entire buffer back to SCHEME. End-Entry: EDIT Begin-Family: Advising Procedures Description: Giving advice to procedures is a powerful debugging technique. TRACE and BREAK are familiar examples of advice-giving procedures. The global variable *ADVISED-PROCEDURES* lists the procedures which have been advised. Begin-Entry: TRACE-ENTRY Syntax: (TRACE-ENTRY proc) Args: 1 arg Type: Procedure Description: Causes an informative message to be printed whenever the procedure proc is entered. The message is of the form "[Entering (fn v1 v2 ...)]", where "v1 v2 ..." is the list of values for the procedure's parameters. End-Entry: TRACE-ENTRY Begin-Entry: TRACE-EXIT Syntax: (TRACE-EXIT proc) Args: 1 arg Type: Procedure Description: Causes an informative message to be printed when procedure proc terminates. The message contains the procedure, its argument values, and the value of the last expression evaluated. End-Entry: TRACE-EXIT Begin-Entry: TRACE Syntax: (TRACE proc) Args: 1 arg Type: Procedure Description: TRACEs proc both when it is invoked and when it terminates. A combination of TRACE-ENTRY and TRACE-EXIT. End-Entry: TRACE Page-Break: Begin-Entry: UNTRACE-ENTRY Syntax: (UNTRACE-ENTRY [proc]) Args: 0 or 1 args Type: Procedure Description: Stops TRACing whenever the procedure proc is entered. If TRACE and UNTRACE-ENTRY are applied to proc in that order, it will be TRACEd only when proc terminates. When no procedure is specified, UNTRACE-ENTRY applies to all procedures which have been TRACEd. End-Entry: UNTRACE-ENTRY Begin-Entry: UNTRACE-EXIT Syntax: (UNTRACE-EXIT [proc]) Args: 0 or 1 args Type: Procedure Description: Stops TRACing when the procedure proc terminates. If TRACE and TRACE-EXIT are applied to proc in that order, it will be TRACEd only when proc is entered. When no procedure is specified, UNTRACE-EXIT applies to all procedures which have been TRACEd. End-Entry: UNTRACE-EXIT Begin-Entry: UNTRACE Syntax: (UNTRACE [proc]) Args: 0 or 1 arg Type: Procedure Description: Stops TRACing procedure both when it is invoked and when it terminates. When no procedure is specified, UNTRACE applies to all procedures which have been TRACEd. A combination of UNTRACE-ENTRY and UNTRACE-EXIT. End-Entry: UNTRACE Begin-Entry: BREAK-ENTRY Syntax: (BREAK-ENTRY proc) Args: 1 arg Type: Procedure Description: Like TRACE-ENTRY with the additional effect that a breakpoint is entered when procedure proc is invoked. proc and its arguments are saved in the global variables *PROC* and *ARGS*, respectively, for easy access inside the breakpoint. End-Entry: BREAK-ENTRY Begin-Entry: BREAK-EXIT Syntax: (BREAK-EXIT proc) Args: 1 arg Type: Procedure Description: Like TRACE-EXIT with the additional effect that a breakpoint is entered just prior to leaving procedure proc. proc, its arguments, and the result are saved in the global variables *PROC*, *ARGS*, and *RESULT*, respectively, for easy access inside the breakpoint. The result computed by proc is normally returned after proceeding from the breakpoint, but the user may return any value by setting *RESULT* prior to proceeding via $p. End-Entry: BREAK-EXIT Begin-Entry: BREAK Syntax: (BREAK proc) Args: 1 arg Type: Procedure Description: Sets a breakpoint at the beginning and at the end of proc. A combination of BREAK-ENTRY and BREAK-EXIT. End-Entry: BREAK Page-Break: Begin-Entry: ADVISE-ENTRY Syntax: (ADVISE-ENTRY proc advice) Args: 2 args Type: Procedure Description: General entry-advising procedure. TRACE-ENTRY and BREAK-ENTRY are examples of entry-advising procedures. ADVISE-ENTRY gives advice to proc. advice should be a procedure of three arguments. When proc is invoked, advice is passed proc, a list of proc's argument values, and the current environment. End-Entry: ADVISE-ENTRY Begin-Entry: ADVISE-EXIT Syntax: (ADVISE-EXIT proc advice) Args: 2 args Type: Procedure Description: The general exit-advising procedure. TRACE-EXIT and BREAK-EXIT are implemented as calls to ADVISE-EXIT. advice should accept four arguments: proc, its argument values, the result computed by proc, and the current environment. advice is responsible for returning the value produced to be returned by proc. End-Entry: ADVISE-EXIT Begin-Entry: ADVICE Syntax: (ADVICE proc) Args: 1 arg Type: Procedure Description: Returns the advice, if any, given to proc. Example: (DEFINE (ID X) X) => ID Example: (ADVICE ID) => NIL Example: (TRACE-ENTRY ID) => (ID) Example: (ADVICE ID) => (TRACE-ENTRY-ADVICE) End-Entry: ADVICE Begin-Entry: UNADVISE-ENTRY Syntax: (UNADVISE-ENTRY proc) Args: 1 arg Type: Procedure Description: Removes entry advice from proc. End-Entry: UNADVISE-ENTRY Begin-Entry: UNADVISE-EXIT Syntax: (UNADVISE-EXIT proc) Args: 1 arg Type: Procedure Description: Removes exit advice from proc. End-Entry: UNADVISE-EXIT Begin-Entry: UNADVISE Syntax: (UNADVISE proc) Args: 1 arg Type: Procedure Description: Removes all advice from proc -- a combination of UNADVISE-ENTRY and UNADVISE-EXIT. End-Entry: UNADVISE End-Family: Advising Procedures Page-Break: Begin-Family: Debugging Features Description: An important step in debugging is to locate the piece of code from which the error is signalled. The SCHEME debugger contains a history examiner and an environment examiner to aid the user in locating a bug. A detailed account of this, with examples, is given in the SCHEME section of the TOPS-20 manual. Begin-Entry: SETUP-HISTORY Syntax: (SETUP-HISTORY l r x) Args: 3 args Type: Procedure Description: Initializes the history recording mechanism, setting the maximum number of sub-problem levels to be l, the maximum number of reductions at each level to be r, and the maximum number of sub-expressions to be x. These arguments are referred in the read-eval-print loop as max-subproblems max-reductions and max-subexpressions respectively. End-Entry: SETUP-HISTORY Begin-Entry: DEBUG Syntax: (DEBUG) Args: 0 args Description: The function DEBUG gets the user into the history examination system, which allows the user to examine the history of execution of an expression after it has been executed. The environment of any procedure application may then be examined and the interrupted process may be proceeded from any of the displayed nodes of evaluation. The history system has two modes. The first time the debugger is called, it enters the character command mode, but enters the last mode called every subsequent time. In the character command mode, a read-execute-print loop is entered and single letter commands are available. The extended command mode is the more complex and complete of the two, in which a special READ-EVAL-PRINT is entered so that all the internal functions and variables of the history system are available to the user, who can write his own display and manipulation procedures. The commands in character command mode call procedures, available in extended command mode, to display and move around in the evaluation tree of the expression. The commands are listed and explained in the 6.001 TOPS-20 Manual. The function TOGGLE (or the command M) can be used to change from one mode to the other. End-Entry: DEBUG Begin-Entry: WHERE Syntax: (WHERE [environment-specifier]) Args: 0 or 1 args Description: The function WHERE gets the user into the environment examination system of the debugger. This allows the user to examine variable bindings in an environment, or any of its parent frames and to change these bindings by entering a read-eval-print loop in the appropriate environment. WHERE enters a read-execute-print loop which accepts one letter commands. The commands are listed and explained in the TOPS-20 Manual. WHERE can also be called from the history examination system. WHERE takes one optional argument, the environment-specifier. If it is left out, the environment examined is the read-eval-print environment from which WHERE was called (or an error or breakpoint environment if called from the debugger). If a compound procedure is supplied, WHERE lets the user examine the environment of definition of the procedure. This is useful for debugging procedure arguments and values. End-Entry: WHERE End-Family: Debugging Features Chapter: Reading and Printing Begin-Family: Essential Knowledge Begin-Entry: READ Syntax: (READ) Args: 1 arg Type: Procedure Description: Reads one expression from the terminal and returns it as a value. End-Entry: READ Begin-Entry: PRINT Syntax: (PRINT value) Args: 1 arg Type: Procedure Description: This is the normal LISP printer. It puts out a carriage-return, then prints out value, then puts out a space: (DEFINE (PRINT X) (NEWLINE) (PRINC X) (PRINC " ")) End-Entry: PRINT Begin-Entry: NEWLINE Syntax: (NEWLINE) Args: No args Type: Procedure Description: Types a carriage return on the console. End-Entry: NEWLINE Begin-Entry: PRINC Syntax: (PRINC value) Args: 1 arg Type: Procedure Description: Prints value on the console. End-Entry: PRINC Begin-Entry: %IN Syntax: (%IN) Args: 0 args Type: Procedure Description: Returns the most recently read in expression. Example: (+ 2 5) => 7 Example: (%IN) => (+ 2 5) End-Entry: %IN Begin-Entry: %OUT Syntax: (%OUT) Args: 0 args Type: Procedure Description: Returns the most recently printed expression. Example: (+ 2 5) => 7 Example: (%OUT) => 7 End-Entry: %OUT End-Family: Essential Knowledge Page-Break: Begin-Family: Advanced Knowledge Begin-Entry: TYI Syntax: (TYI) Args: 1 arg Type: Procedure Description: Reads a character from the current input source and returns the character's ASCII code, an integer. End-Entry: TYI Begin-Entry: TYO Syntax: (TYO n) Args: 1 arg Type: Procedure Description: Types the character whose ascii value is n on the console. End-Entry: TYO Begin-Entry: READCH Syntax: (READCH) Args: 1 arg Type: Procedure Description: Reads a character from the terminal and returns it as a symbol. End-Entry: READCH Begin-Entry: PEEKCH Syntax: (PEEKCH) Args: No args Type: Procedure Description: Peeks at a character from the terminal, without actually reading it, and returns it as a symbol. End-Entry: PEEKCH Begin-Entry: TYIPEEK Syntax: (TYIPEEK) Args: No args Type: Procedure Description: Peeks at a character from the current input source without actually reading it. Returns the character's ASCII code, an integer. End-Entry: TYIPEEK Begin-Entry: CHAR Syntax: (CHAR n) Args: 1 arg Type: Procedure Description: Returns the ascii character (symbol) whose ASCII code is n. Example: (CHAR 65) => A End-Entry: CHAR Begin-Entry: ASCII Syntax: (ASCII sym) Args: 1 arg Description: Returns the ASCII code of the character (symbol) sym. Example: (ASCII 'A) => 65 End-Entry: ASCII End-Family: Advanced Knowledge Begin-Family: Printer Control Description: The printer has two adjustable parameters: the value of the global variable *PRINT-DEPTH* is the maximum depth to which lists are printed; lists nested deeper than *PRINT-DEPTH* levels will be abbreviated when printed. The value of *PRINT-BREADTH* is the maximum number of elements of a list which will be printed; lists longer than *PRINT-BREADTH* will be abbreviated when printed. Initially, these variables have very tolerant values. You may assign their values as desired, but they must be integers (or NIL, which puts no restriction on the printer). End-Family: Printer Control Chapter: Advanced Evaluator Features Begin-Family: Evaluation and Application Begin-Entry: EVAL Syntax: (EVAL exp env) Args: 2 args Type: Procedure Description: EVALuates exp in the environment env. End-Entry: EVAL Begin-Entry: APPLY Syntax: (APPLY fn arglist) Type: Procedure Description: Applies fn to arglist, the list of arguments, returning the resulting value. The variable "fn" must be an applicable object such as a procedure. Example: (APPLY CAR '((A B))) => A Example: (APPLY (LAMBDA (X Y) (+ X Y 1)) '(3 4)) => 8 End-Entry: APPLY End-Family: Evaluation and Application Begin-Family: Environments Begin-Entry: MAKE-ENVIRONMENT SpecialForm: (MAKE-ENVIRONMENT exp1 exp2 ...) Description: MAKE-ENVIRONMENT produces a new environment which is contained statically in the environment in which MAKE-ENVIRONMENT is called. The new environment contains any variables DEFINEd by the expressions exp1, exp2 ... End-Entry: MAKE-ENVIRONMENT Page-Break: Begin-Entry: ACCESS SpecialForm: (ACCESS sym env) Description: ACCESS retrieves the value of sym in the environment env. Demo: ==> (DEFINE RECT-PACKAGE (MAKE-ENVIRONMENT (DEFINE (MAKE-COMPLEX REAL IMAG) (LIST REAL IMAG)) (DEFINE (REAL-PART Z) (CAR Z)) (DEFINE (IMAG-PART Z) (CADR Z)) ...)) RECT-PACKAGE ==> (DEFINE Z ((ACCESS MAKE-COMPLEX-RECTANGULAR RECT-PACKAGE) 3 4)) Z ==> ((ACCESS IMAG-PART RECT-PACKAGE) Z) 4 End-Entry: ACCESS Begin-Entry: FRAME-PROCEDURE Syntax: (FRAME-PROCEDURE env) Args: 1 arg Type: Procedure Description: FRAME-PROCEDURE returns the procedure object which was applied to produce the environment env. End-Entry: FRAME-PROCEDURE Begin-Entry: FRAME-BINDINGS Syntax: (FRAME-BINDINGS env) Args: 1 arg Type: Procedure Description: FRAME-BINDINGS returns the association list representing the bindings of the variables to their values in the environment env. End-Entry: FRAME-BINDINGS Begin-Entry: FRAME-PARENT Syntax: (FRAME-PARENT env) Args: 1 arg Type: Procedure Description: FRAME-PARENT returns the environment in which the environment env was created. End-Entry: FRAME-PARENT End-Family: Environments Page-Break: Begin-Family: Delayed Evaluation Begin-Entry: DELAY SpecialForm: (DELAY exp) Description: Produces an object, which if FORCEed, produces the value of the expression exp. This object is a "promise" to compute the value of exp, if and when it is needed. End-entry: DELAY Begin-Entry: FORCE Syntax: (FORCE delayed-expression) Args: 1 Type: Procedure Description: Forces evaluation of delayed-expression. If that expression has been previously forced, the old result is used; if not, the expression is evaluated and the result is memoized and returned. End-Entry: FORCE Begin-Entry: CONS-STREAM SpecialForm: (CONS-STREAM head tail) Description: Produces a stream object whose head and tail are given. Essentially this is (CONS head (DELAY tail)). End-Entry: CONS-STREAM Begin-Entry: HEAD Syntax: (HEAD stream) Args: 1 Type: Procedure Description: Produces the HEAD that was CONS-STREAMed to make this stream. End-Entry: HEAD Begin-Entry: TAIL Syntax: (TAIL stream) Args: 1 Type: Procedure Description: Produces the TAIL that was CONS-STREAMed to make this stream. This may FORCE the delayed expression for the TAIL to be evaluated. End-Entry: TAIL End-Family: Delayed Evaluation Index: Eof: