Wraith Scheme Dictionary

Operation:

Boolean and.

Arguments:

Zero or more Scheme objects of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, all the arguments are true. (Recall that the only Scheme object that is false is #f.) With no arguments, returns #t. Otherwise, returns #f.

This macro operates by evaluating its arguments one at a time, from left to right. When and if any argument evaluates to false, "and" returns false immediately, without evaluating any more arguments.

For Example:

(and)        ;; ==> #t
(and #t)     ;; ==> #t
(and #f)     ;; ==> #f
(and #t #t)  ;; ==> #t
(and #f #t)  ;; ==> #f

(define (foo) (begin (display "foo ") #f))  ;; ==> foo
(define (bar) (begin (display "bar ") #t))  ;; ==> bar

(and (foo) (bar))                           ;; ==> foo #f
                                            ;;  It didn't print "bar".

angle

Type:

Procedure.

Operation:

Obtain the angle of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The angle of the number.

For Example:

(angle 1)   ;; ==> 0
(angle -1)  ;; ==> 3.1415926535897931
(angle +i)  ;; ==> 1.5707963267948966
(angle -i)  ;; ==> -1.5707963267948966

append

Type:

Procedure.

Operation:

Appends lists; that is, glues them together, head-to-tail. The last object "glued" need not be a list.

Arguments:

One or more arguments: All but the last of these must be proper lists. (A proper list is one that has finite length and is terminated by the empty list.) The last argument may be any Scheme object.

Side Effects:

None.

Returned Value:

Any Scheme object: With one argument, returns the argument. With more than one argument, builds a list from all but the last argument, by making copies of all of these lists and joining them in order, then makes the last argument be the cdr of the list so constructed, and returns that list.

For Example:

(append 1)                      ;; ==> 1
(append (list 1 2) (list 3 4))  ;; ==> (1 2 3 4)
(append (list 1 2) 3)           ;; ==> (1 2 . 3)

(define a (list 1 2 3))         ;; ==> a
(define b (list 4 5 6))         ;; ==> b
(define ab (append a b))        ;; ==> ab
a                               ;; ==> (1 2 3)
                                ;;  Not (1 2 3 4 5 6)
b                               ;; ==> (4 5 6)
ab                              ;; ==> (1 2 3 4 5 6)

;; But:

(set-cdr! (cddr b) 7)           ;; ==> #t
b                               ;; ==> (4 5 6 . 7)
ab                              ;; ==> (1 2 3 4 5 6 . 7)

(define c (list 1))             ;; ==> c
(set-cdr! c c)                  ;; ==> #t
c                               ;; ==> (1 1 1 1 1 1 1 1 1 1 1 ... ) 

(append c ab)                   ;; ==> <error>
                                ;; c is not a proper list.

apply

Type:

Procedure.

Operation:

Calls a procedure with a list of arguments.

Arguments:

Two or more arguments: The first must be a procedure, the last must be a proper list, and each of the others, if any, may be any Scheme object.

Side Effects:

None by itself, though the procedure applied may cause side effects of its own.

Returned Value:

Any Scheme object: Calls the given procedure -- the first argument -- with a list of arguments built as follows:

With two arguments, as in (apply proc args), where args is a list, "proc" is called with "args" as its arguments.

With more than two arguments, as in (apply proc arg1 arg2 ... argn args), "proc" is called with the argument list (append (list arg1 arg2 ... argn) args).

For Example:

(apply + (list 1 2))      ;; ==> 3   ;; Equivalent to (+ 1 2)
(apply + 1 2 (list 3 4))  ;; ==> 10  ;; Equivalent to 
                          ;;   (+ 1 2 3 4), and to
                          ;;   (apply + (list 1 2 3 4)

asin

Type:

Procedure.

Operation:

Mathematical inverse sine, or arc-sine, function.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A number: A number: A complex number whose sine is the argument. For a real argument, the returned value will be in the range [-pi/2, pi/2].

For Example:

(asin 1)   ;; ==> 1.5707963267948966
(asin 0)   ;; ==> 0
(asin -1)  ;; ==> -1.5707963267948966
(asin +i)  ;; ==> 0.8813735870195428i

assoc

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "equal?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "equal?" to the first argument, or returns #f if there is no such pair.

For Example:

(assoc 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assoc 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assoc 42 '((1 2) (3 4)))  ;; ==> #f

assq

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "eq?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "eq?" to the first argument, or returns #f if there is no such pair.

For Example:

(assq 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assq 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assq 42 '((1 2) (3 4)))  ;; ==> #f

(assq (list 1 2) '(((1 2) 'foo) ((3 4) 'bar))) ;; ==> #f

(define a (list 1 2))     ;; ==> a
(define pair-list (list (list a 'foo) (list (list 3 4) 'bar)))
                          ;; ==> pair-list

pair-list                 ;; ==> (((1 2) foo) ((3 4) bar))

(assq a pair-list)        ;; ==> ((1 2) foo) ;; The two "(1 2)"s refer
                          ;;      to the same object.

assv

Type:

Procedure.

Operation:

Look up a key-value pair in a list thereof, using "eqv?" as the predicate for testing for the presence of the key.

Arguments:

Two arguments: The first may be any Scheme object; the second must be a proper list of pairs.

Side Effects:

None.

Returned Value:

A pair: Returns the first pair in the second argument whose car is "eqv?" to the first argument, or returns #f if there is no such pair.

For Example:

(assv 1 '((1 2) (3 4)))   ;; ==> (1 2)
(assv 3 '((1 2) (3 4)))   ;; ==> (3 4)
(assv 42 '((1 2) (3 4)))  ;; ==> #f
(assv (list 1 2) '(((1 2) 'foo) ((3 4) 'bar)))  ;; ==> #f

(define a (list 1 2))     ;; ==> a
(define pair-list (list (list a 'foo) (list (list 3 4) 'bar)))
                          ;; ==> pair-list

pair-list                 ;; ==> (((1 2) foo) ((3 4) bar))
(assv a pair-list)        ;; ==> ((1 2) foo)

atan

Type:

Procedure.

Operation:

Mathematical inverse tangent, or arc-tangent, with one or two arguments. The two-argument version is called "atan2" by some.

Arguments:

One number or two real numbers.

Side Effects:

None.

Returned Value:

With one argument, the returned value is a complex number whose tangent is the argument.

If that argument is real, returns a number in the range [-pi/2, pi/2].

With two real arguments, takes the arguments to be the coordinates of a point in the x/y plane, with the first argument being y and the second argument being x, and returns a number in the range (-pi, pi] which is the angle between the positive x-axis and the radius vector to that point. (The angle returned is negative if, and only if, y is negative.)

Note that (atan 0 0) returns 0. (The "R5" Scheme report appears to indicate that (atan 0 0) should return a value, but does not indicate what it should be.)

For Example:

(atan 1000)   ;; ==> 1.5697963271282296
(atan -1000)  ;; ==> -1.5697963271282296
(atan -1 0)   ;; ==> -1.5707963267948966
(atan 0 -1)   ;; ==> 3.1415926535897931
(atan +2i)    ;; ==> 1.5707963267948966+0.5493061443340549i

(atan -0.0000000001 -1000000000) ;; ==> -3.1415926535897931

(atan 0 0)    ;; ==> 0

begin

Type:

Operation:

Evaluate a sequence of Scheme expressions in the order given.

Arguments:

One or more Scheme expressions of any kind.

Side Effects:

None.

Returned Value:

Any Scheme object: Causes the evaluation each of its arguments in turn, and returns whatever resulted from the evaluation of the last argument.

Note that "begin" does not create a new environment: Each evaluation that "begin" causes takes place in the environment where the "begin" was encountered.

For Example:

(begin 1 2 3 4)                                 ;; ==> 4
(begin (display "first ") (display "second "))  ;; ==> first second #t

;; In the top-level loop ...

(begin (define a 42) (define b 137))  ;; ==> b
a                                     ;; ==> 42
b                                     ;; ==> 137

boolean?

Type:

Procedure.

Operation:

Test whether its argument is a boolean.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is either #t or #f. Returns #f otherwise.

For Example:

(boolean? #t)        ;; ==> #t
(boolean? #f)        ;; ==> #t
(boolean? 'whatever) ;; ==> #f

call-with-current-continuation

Type:

Procedure.

Note that call/cc is a synonym for this procedure.

Operation:

Creates an unnamed procedure of one argument, which encapsulates the current continuation in such a way that when that unnamed procedure is subsequently called, it will change the continuation that was present when the unnamed procedure was called to the continuation which is encapsulated. The unnamed procedure is passed as an argument to the procedure which is the argument to "call-with-current-continuation".

A continuation is in essence the entire internal state of the Scheme system. Thus when the unnamed procedure is called, it restores that state to whatever the state was when the unnamed procedure was created. If "call-with-current-continuation" was called during the middle of the execution of a particular Scheme procedure -- let's suppose that its name is "foo" -- then when the unnamed procedure thereby created is called, it will be as if "foo" was still running; "foo" will pick up right where "call-with-current-continuation" was called.

Recall that the unnamed procedure takes one argument. When it is called, whatever argument it was given appears in the restored continuation as if it had been returned from "call-with-current-continuation".

See the examples below for more details.

There is one rather technical caveat about the operation of "call-with-current-continuation": When the environment -- a complicated table of variable identifiers and their values -- is encapsulated into the current continuation, it is not copied; what is placed in the continuation is a reference, a pointer to the real environment. It is entirely possible that other Scheme procedures, such as "set!", will modify the real environment before the unnamed function created by "call-with-current-continuation" is called. Since the environment may have been modified, it is not correct to say that calling the unnamed function is guaranteed to restore the internal state of Scheme to what it was when the unnamed function was created.

The reason why the environment is not copied is that environments may be very large objects: They include everything in Scheme's memory that is not garbage. Thus there will often not be enough memory available to make a copy.

Arguments:

One argument, which must be a procedure that itself takes one argument.

Side Effects:

Saves the current state of Scheme in such a way that it can subsequently be restored at will.

Returned Value: Any Scheme object, or may never return:

The value returned will be either what the argument to "call-with-current-continuation" returns, or will be whatever value was passed to the unnamed procedure when -- and if -- that unnamed procedure was itself called.

For Example:

This first example is rather trivial. In it, the unnamed procedure prepared by "call-with-current-continuation" is passed as an argument to the predicate "procedure?", which does not call it -- "procedure?" simply affirms that that unnamed procedure is in fact a procedure, by returning #t.

(call-with-current-continuation procedure?)  ;; ==> #t

The second example is from the "R5" report. Let's discuss it in detail.

(call-with-current-continuation
  (lambda (exit) 
    (for-each (lambda (x)
                (if (negative? x)
                  (exit x)))
     '(54 0 37 -3 245 19))
  #t))

  ;; ==> -3

The procedure which is the argument to "call-with-current-continuation" begins on the second line of the example; it is the lambda expression that starts with "(lambda (exit) ...". The unnamed procedure created by "call-with-current-continuation" is passed to that lambda expression as an argument, and the lambda gives the unnamed procedure a name -- "exit".

The lambda expression itself uses the "for-each" procedure with another, shorter lambda expression, to test each number in the list of six numbers in the sixth line, to see whether it is negative. If the number is not negative, nothing happens -- the lambda expression goes on to the next number. If no number were negative, the "for-each" procedure that is running the test would end, and the outer lambda expression would returns #t, from the seventh line, so that "call-with-current-continuation" would thereby returns #t.

However, one of the numbers -- the fourth one -- is in fact negative; it's -3. When the test encounters it, the "if" will call "exit" with a value of -3. Since "exit" has as value the unnamed procedure originally created by "call-with-current-continuation", "exit" will immediately restore the continuation where it was created, and in effect, "call-with-current-continuation" will returns immediately, with a value of -3.

There are perhaps easier ways to find the first negative number in a list. Notwithstanding, this example illustrates how "call-with-current-continuation" can be used to returns a meaningful value from deep within a function, without somehow going back through all the intervening code. This facility is useful, for example, in reporting errors in a complicated process.

Continuations are complicated and confusing. It is unlikely that any introduction to them that is as short as this one can succeed in describing continuations adequately to a person who is not already familiar with them.

call-with-input-file

Type:

Procedure.

Operation:

Open a port to an input file and call a procedure with that port as argument.

Arguments:

One or two arguments. The last should be a procedure that takes one argument. The first, if present, should be a string naming a file. If there is only one argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain the name of the file.

Side Effects:

None.

Returned Value:

Any Scheme object, or may not return: The called procedure need not return, but if it does, "call-with-input-file" will returns whatever the procedure returns.

For Example:

(call-with-input-file "foo" read-char)
     ;; ==> Read and returns one character from "foo".
(call-with-input-file (lamdba(port) (read-char port)))
     ;; ==> Read and return one character from a file
         pathname obtained from the user via the
         Wraith Scheme Dialog Panel

call-with-output-file

Type:

Procedure.

Operation:

Open a port to an output file and call a procedure with that port as argument.

Arguments:

Side Effects:

None.

Returned Value:

Any Scheme object, or may not return: The called procedure need not return, but if it does, "call-with-output-file" will return whatever the procedure returns.

For Example:

(call-with-output-file "foo" (lambda(port) (write 1 port))
     ;; ==> Write "1" to "foo" and return #t.
(call-with-output-file (lambda(port) (write 1 port))
     ;; ==> Write "1" to a file whose pathname will
         be obtained from the user via the Wraith
         Scheme Dialog Panel

call-with-values

Type:

Procedure.

Operation:

Allow a procedure which returns multiple values to pass them as arguments to another procedure.

Arguments:

Two procedures. The first may return multiple values, via the "values" procedure. The second is the procedure to which the multiple values are intended to be passed; it will receive them as if they had been entered as individual arguments with the usual procedure-call syntax.

Side Effects:

None.

Returned Value:

Any Scheme object, or may not return: "call-with-values" in effect passes control to its second argument, and returns if and only if that procedure does, returning whatever that procedure returns.

For Example:

;; Here is a fancy way to add up the integers
;; from one through ten:  This example passes
;; the list returned by "values" to "+", just
;; as if you had entered
;;
;; (+ 1 2 3 4 5 6 7 8 9 10)

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  +)  ;; ==> 55

;; We could equally well just list the numbers:

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  list)

  ;; ==> (1 2 3 4 5 6 7 8 9 10)

;; This rather cute example is from the R5 report:
;; Remember that the procedure call "(*)" returns "1".

(call-with-values * +)  ;; ==> 1

call/cc

Type:

Procedure.

This procedure is a synonym for call-with-current-continuation, which see.

car

Type:

Procedure.

Operation:

Obtain the car of a pair.

Arguments:

One pair.

Side Effects:

None.

Returned Value:

Any Scheme object: The car of the argument.

For Example:

(car '(1 2))              ;; ==> 1
(car '(1 . 2))            ;; ==> 1
(car '(1))                ;; ==> 1
(car (list 1 2 3 4 5 6))  ;; ==> 1

cdr

Type:

Procedure.

Operation:

Obtain the cdr of a pair.

Arguments:

One pair.

Side Effects:

None.

Returned Value: Any Scheme object:

The cdr of the argument.

For Example:

(cdr '(1 2))              ;; ==> (2)
(cdr '(1 . 2))            ;; ==> 2
(cdr '(1))                ;; ==> ()
(cdr (list 1 2 3 4 5 6))  ;; ==> (2 3 4 5 6)

caar         cadr         cdar         cddr
caaar       caadr       cadar       caddr
cdaar       cdadr       cddar       cdddr
caaaar     caaadr     caadar     caaddr
cadaar     cadadr     caddar     cadddr
cdaaar     cdaadr     cdadar     cdaddr
cddaar     cddadr     cdddar     cddddr

Type:

Procedures.

Operation:

Convenience procedures for accessing components of nested pairs.

Arguments:

One argument, which must be a pair, and whose car and cdr may also have specific type requirements, depending on the procedure.

Side Effects:

None.

Returned Value:

Any Scheme object:

Each of these procedures is a combination (technically, a composition) of from two to four applications of either "car" or "cdr". Two easy ways of figuring out which combination is intended are as follows:

Split the procedure name into individual letters, drop the initial "c" and the final "r", change each "a" into "the car of" and change each "d" into "the cdr of". Thus for example

cadar

becomes

c a d a r

which becomes

a d a

which becomes

the car of the cdr of the car of

And "(cadar x)" does indeed return the car of the cdr of the car of x.

Alternatively, in a particular procedure call, split the procedure name into individual letters, drop the initial "c" and the final "r", change each "a" into "car" and change each "d" into "cdr", and add enough parentheses to make sense. Thus for example:

(cadar x)

becomes

(c a d a r x)

which becomes

(a d a x)

which becomes

(car cdr car x)

which becomes

(car (cdr (car x)))

And "(cadar x)" does indeed return what "(car (cdr (car x)))" would.

Each of these procedures will report an error if its argument does not possess the correct pair structure to have the element that the procedure is intended to retrieve. Thus "(caddr (list 1 2))" will report an error, because "(list 1 2)" does not have a caddr.

For Example:

(define a (list 1 2 3 4 5 6))  ;; ==> a
(cadr a)                       ;; ==> 2
(cddr a)                       ;; ==> (3 4 5 6)
(cdar a)                       ;; ==> <error>
(caar a)                       ;; ==> <error>
(cdddr a)                      ;; ==> (4 5 6)
(cddddr a)                     ;; ==> (5 6)
(cadddr a)                     ;; ==> 4

(define b (list (list (list (list 'a))) 2 3 4))
                               ;; ==> b
b                              ;; ==> ((((a))) 2 3 4)
(car b)                        ;; ==> (((a)))
(caar b)                       ;; ==> ((a))
(caaar b)                      ;; ==> (a)
(caaaar b)                     ;; ==> a

;; et cetera ad nauseam

case

Type:

Operation:

Evaluates an expression -- the "key" -- and compares the result (using "eqv?") to each element in the car of each of a series of lists -- the case clauses -- in turn. If a match is found, evaluates each element of the cdr of that case clause in left-to-right order, and returns whatever results from the evaluation of the last element.

If there is no match, there may be an "else" clause -- whose car is just "else" -- as the last clause of the case. If there is an "else" clause, evaluates each element of the cdr of the else clause in left-to-right order, and returns whatever results from the evaluation of the last element. If there is no match, and no else clause, returns #t.

Arguments:

One Scheme expression, followed by one or more proper lists, each of which has as its car either a proper list, or the symbol "else". The symbol "else" may only appear as the car of the last proper list of the "case" expression, and that last proper list need not necessarily begin with "else".

Side Effects:

None in its own right, but the evaluation of items in the clauses may cause arbitrary side effects.

Returned Value:

Arbitrary, depending on the clauses; may not return at all, depending on the clauses.

For Example:

(case (+ 1 0)
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> first
(case 2
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> second
(case 3
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> first
(case 4
  ((1 3) 'first)
  ((2 3) 'second)
  (else 'third)
  )  ;; ==> third
(case 4
  ((1 3) 'first)
  ((2 3) 'second)
  )  ;; ==> #t

ceiling

Type:

Procedure.

Operation:

Arithmetic round up.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The smallest integer not smaller than the argument.

For Example:

(ceiling -6.5)  ;; ==> -6.
(ceiling 4)     ;; ==> 4

char->integer

Type:

Procedure.

Operation:

Convert a character to the integer that represents it; Wraith Scheme uses the ASCII standard for representing characters by integers.

Arguments:

One character.

Side Effects:

None.

Returned Value:

An integer: The integer whose ASCII character is the argument.

For Example:

(char->integer #\C)        ;; ==> 67
(char->integer #\newline)  ;; ==> 10

char-alphabetic?

Type:

Procedure.

Operation:

Test whether the argument is a letter of the alphabet.

Arguments:

One character/

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a letter of the alphabet, in either upper case or lower case. Otherwise, returns false.

For Example:

(char-alphabetic? #\a)  ;; ==> #t
(char-alphabetic? #\!)  ;; ==> #f

char-ci<=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is less than or equal to the integer representation of the second. Wraith Scheme implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is less than or equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci<=? #\a #\A)  ;; ==> #t
(char-ci<=? #\A #\b)  ;; ==> #t
(char-ci<=? #\a #\B)  ;; ==> #t
(char-ci<=? #\B #\a)  ;; ==> #f
(char-ci<=? #\b #\A)  ;; ==> #f
(char-ci<=? #\a #\[)  ;; ==> #f
(char-ci<=? #\A #\[)  ;; ==> #f

char-ci<?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is less than the integer representation of the second. Wraith Scheme implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is less than the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci<? #\a #\A)  ;; ==> #f
(char-ci<? #\A #\b)  ;; ==> #t
(char-ci<? #\a #\B)  ;; ==> #t
(char-ci<? #\B #\a)  ;; ==> #f
(char-ci<? #\b #\A)  ;; ==> #f
(char-ci<? #\a #\[)  ;; ==> #f
(char-ci<? #\A #\[)  ;; ==> #f

char-ci=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is equal to the integer representation of the second. Wraith Scheme implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci=? #\a #\A)  ;; ==> #t
(char-ci=? #\A #\b)  ;; ==> #f
(char-ci=? #\a #\B)  ;; ==> #f
(char-ci=? #\B #\a)  ;; ==> #f
(char-ci=? #\b #\A)  ;; ==> #f
(char-ci=? #\a #\[)  ;; ==> #f
(char-ci=? #\A #\[)  ;; ==> #f

char-ci>=?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is greater than or equal to the integer representation of the second. Wraith Scheme implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is greater than or equal to the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci>=? #\a #\A)  ;; ==> #t
(char-ci>=? #\A #\b)  ;; ==> #f
(char-ci>=? #\a #\B)  ;; ==> #f
(char-ci>=? #\B #\a)  ;; ==> #t
(char-ci>=? #\b #\A)  ;; ==> #t
(char-ci>=? #\a #\[)  ;; ==> #t
(char-ci>=? #\A #\[)  ;; ==> #t

char-ci>?

Type:

Procedure.

Operation:

Case-independently test the whether the integer representation of the first argument is greater than the integer representation of the second. Wraith Scheme implements case-independence by converting any argument that is an upper-case letter to lower case before proceeding with the comparison.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Converts any argument that is an upper-case letter to lower case, and returns #t if, and only if, the integer whose ASCII character then represents the first argument is greater than the integer whose ASCII character then represents the second argument. Otherwise, returns #f.

For Example:

(char-ci>? #\a #\A)  ;; ==> #f
(char-ci>? #\A #\b)  ;; ==> #f
(char-ci>? #\a #\B)  ;; ==> #f
(char-ci>? #\B #\a)  ;; ==> #t
(char-ci>? #\b #\A)  ;; ==> #t
(char-ci>? #\a #\[)  ;; ==> #t
(char-ci>? #\A #\[)  ;; ==> #t

char-downcase

Type:

Procedure.

Operation:

Convert a character to lower case.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A character: If the argument is an upper case letter, returns it in lower case, otherwise returns it unchanged.

For Example:

(char-downcase #\A)  ;; ==> #\a
(char-downcase #\a)  ;; ==> #\a
(char-downcase #\!)  ;; ==> #\!

char-lower-case?

Type:

Procedure.

Operation:

Test whether an alphabetic character is in lower case.

Arguments:

One alphabetic character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is in lower case. Otherwise, returns #f.

For Example:

(char-lower-case? #\a)  ;; ==> #t
(char-lower-case? #\A)  ;; ==> #f
(char-lower-case? #\!)  ;; ==> <error>

char-numeric?

Type:

Procedure.

Operation:

Test whether a character is a decimal digit.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a decimal digit. Otherwise, returns #f.

For Example:

(char-numeric? #\3)  ;; ==> #t
(char-numeric? #\a)  ;; ==> #f

char-ready?

Type:

Procedure.

Operation:

Test whether there is a character or an eof-object ready to read on a port.

Arguments:

Either none, or one port.

Side Effects:

None.

Returned Value:

A boolean: The procedure performs a test for whether or not there is a character to be read from a port. If there is an argument, it is taken to be the port to be tested. If not, the port tested is whatever is returned by the procedure "current-input-port".

Returns #t if, and only if, there is either a character to be read from the port, or the port will return an end-of-file object. Otherwise, returns #f.

Interactive ports, such as the console (keyboard) will never return an end-of-file object.

For Example:

;; From the console, at top-level:

(char-ready?) ;; ==> #t  ;; The character is the "return"
                         ;;   that sent the text
                         ;;   "(char-ready?)"
                         ;;   to Wraith Scheme.

(define (foo) (read-char) (char-ready?)) ;; ==> foo
(foo) ;; ==> #f   ;; "read-char" read past the "return".

;; Suppose "port" is an input port to a file containing
;; just the text "abc".

(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\a
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\b
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #\c
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>  ;; How Wraith Scheme
                                            ;; displays an 
                                            ;; end-of-file object.
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>
(char-ready? port)  ;; ==> #t
(read-char port)    ;; ==> #<End of File>

;; To infinity, and beyond ...

char-upcase

Type:

Procedure.

Operation:

Convert a character to upper case.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A character: If the argument is a lower case letter, returns it in upper case, otherwise returns it unchanged.

For Example:

(char-upcase #\A)  ;; ==> #\A
(char-upcase #\a)  ;; ==> #\A
(char-upcase #\!)  ;; ==> #\!

char-upper-case?

Type:

Procedure.

Operation:

Test whether an alphabetic character is in upper case.

Arguments:

One alphabetic character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is in upper case. Otherwise, returns #f.

For Example:

(char-upper-case? #\a)  ;; ==> #f
(char-upper-case? #\A)  ;; ==> #t
(char-upper-case? #\!)  ;; ==> <error>

char-whitespace?

Type:

Procedure.

Operation:

Test whether a character is white space; that is, whether it is a space, tab, line feed, form feed, or carriage-return.

Arguments:

One character.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is white space. Otherwise, returns #t

For Example:

(char-whitespace? #\a)      ;; ==> #f
(char-whitespace? #\space)  ;; ==> #t

char<=?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is less than or equal to the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is less than or equal to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char<=? #\a #\A)  ;; ==> #f
(char<=? #\A #\b)  ;; ==> #t
(char<=? #\a #\B)  ;; ==> #f
(char<=? #\B #\a)  ;; ==> #t
(char<=? #\b #\A)  ;; ==> #f
(char<=? #\a #\[)  ;; ==> #f
(char<=? #\A #\[)  ;; ==> #t

char<?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is less than the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is less than to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char<? #\a #\A)  ;; ==> #f
(char<? #\A #\b)  ;; ==> #t
(char<? #\a #\B)  ;; ==> #f
(char<? #\B #\a)  ;; ==> #t
(char<? #\b #\A)  ;; ==> #f
(char<? #\a #\[)  ;; ==> #f
(char<? #\A #\[)  ;; ==> #t

char=?

Type:

Procedure.

Operation:

Test whether the first argument is equal to the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first argument is equal to the second. Otherwise, returns #f.

For Example:

(char=? #\a #\A)  ;; ==> #f
(char=? #\A #\b)  ;; ==> #f
(char=? #\a #\B)  ;; ==> #f
(char=? #\B #\a)  ;; ==> #f
(char=? #\b #\A)  ;; ==> #f
(char=? #\a #\[)  ;; ==> #f
(char=? #\A #\[)  ;; ==> #f

char>=?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is greater than or equal to the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is greater than or equal to the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char>=? #\a #\A)  ;; ==> #t
(char>=? #\A #\b)  ;; ==> #f
(char>=? #\a #\B)  ;; ==> #t
(char>=? #\B #\a)  ;; ==> #f
(char>=? #\b #\A)  ;; ==> #t
(char>=? #\a #\[)  ;; ==> #t
(char>=? #\A #\[)  ;; ==> #f

char>?

Type:

Procedure.

Operation:

Test whether the integer representation of the first argument is greater than the integer representation of the second.

Arguments:

Two characters.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the integer whose ASCII character represents the first argument is greater than the integer whose ASCII character represents the second argument. Otherwise, returns #f.

For Example:

(char>=? #\a #\A)  ;; ==> #t
(char>=? #\A #\b)  ;; ==> #f
(char>=? #\a #\B)  ;; ==> #t
(char>=? #\B #\a)  ;; ==> #f
(char>=? #\b #\A)  ;; ==> #t
(char>=? #\a #\[)  ;; ==> #t
(char>=? #\A #\[)  ;; ==> #f

char?

Type:

Procedure.

Operation:

Test whether the argument is a character.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a character. Otherwise, returns #f.

For Example:

(char? #\a)  ;; ==> #t
(char? #\!)  ;; ==> #t
(char? 42)   ;; ==> #f

close-input-port

Type:

Procedure.

Operation:

Close an input port.

Arguments:

One input port.

Side Effects:

If the argument is an open port, closes it.

Returned Value:

For Example:

;; Suppose "foo" is the path to a readable file

(define foo-port (open-input-file "foo"))  ;; ==> foo-port
(close-input-port foo-port)                ;; ==> #t

close-output-port

Type:

Procedure.

Operation:

Close an output port.

Arguments:

One output port.

Side Effects:

If the argument is an open port, closes it.

Returned Value:

For Example:

(define foo-port (open-output-file "foo"))  ;; ==> foo-port
(close-output-port foo-port)                ;; ==> #t

complex?

Type:

Procedure.

Operation:

Test whether the argument is a complex number.

Arguments:

One scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a complex number. Otherwise, returns #f. Informally, "complex?" returns #t for every number except nans and infs, because every such number lies somewhere in the complex plane. Many of Wraith Scheme's numbers lie on the real axis, but they are nonetheless in the complex plane.

For Example:

(complex? 0)                  ;; ==> #t
(complex? (expt 10 1000000))  ;; ==> #f   ;; It's an inf.
(complex? #t)                 ;; ==> #f

cond

Type:

Operation:

Examines a series of given clauses, each of which must be a proper list. For each clause in turn, evaluates the car of the list: If that car is true, the evaluates all the rest of the items in the list in turn, and returns whatever the last item evaluates to. If the car is false, goes on to the next given clause. If no given clause has a car that evaluates to true, returns #t. The last of the given clauses may start with the symbol "else", which is treated as if it were #t.

Arguments:

One or more proper lists, the last of which may have "else" as car.

Side Effects:

None in its own right, but the evaluation of items in the clauses may cause arbitrary side effects.

Returned Value:

Arbitrary, depending on the clauses; may not return at all, depending on the clauses.

For Example:

(cond (#f 1) (#f 2) (#f 3))            ;; ==> #t
(cond (#f 1) (#f 2) (#t 3))            ;; ==> 3
(cond (#f 1) (#f 2) (#t 3 4 (+ 5 6)))  ;; ==> 11
(cond (#f 1) (#f 2) (else 3))          ;; ==> 3
(cond 
  ((= (* 6 9) 42) 'peculiar)
  ((= (* 6 9) 54) 'mundane)
  )                                    ;; ==> mundane

cons

Type:

Procedure.

Operation:

Allocate storage for a newly-formed pair.

Arguments:

Two Scheme objects.

Side Effects:

Allocates main memory.

Returned Value:

A pair whose car is the first argument and whose cdr is the second argument. If the first argument is an item represented by a pointer to Scheme memory, then the car of the returned pair is "eq?" to the second argument. If the second argument is an item represented by a pointer to Scheme memory, then the cdr of the returned pair is "eq?" to the second argument.

For Example:

(cons 1 2)               ;; ==> (1 . 2)
(cons 'a '())            ;; ==> (a)
(cons 1 (list 2 3 4 5))  ;; ==> (1 2 3 4 5)

(cons (list 1 2 3) (list 4 5 6))
                         ;; ==> ((1 2 3) 4 5 6)

cos

Type:

Procedure.

Operation:

Mathematical cosine.

Arguments:

One number. Real numbers are taken to be angles in radians.

Side Effects:

None.

Returned Value:

A number: The cosine of the argument.

For Example:

(cos 0)  ;; ==> 1
(cos 1.5707963267948966)
         ;; ==> 6.123031769111886e-17  ;;  Very nearly zero.
(cos 0.7853981633974483)
         ;; ==> 0.7071067811865476
(cos +i) ;; ==> 1.5430806348152437

current-input-port

Type:

Procedure.

Operation:

Returns the port from which input is presently being taken.

Arguments:

None.

Side Effects:

None.

Returned Value:

A port: The port from which input is presently being taken.

For Example:

;; When input is being taken from the keyboard:

(current-input-port)  ;; ==> #<Console Input Port>

current-output-port

Type:

Procedure.

Operation:

Returns the port to which output is presently being sent.

Arguments:

None.

Side Effects:

None.

Returned Value:

A port: The port to which output is presently being sent.

For Example:

;; When output is being sent to the Wraith Scheme window:

(current-output-port)  ;; ==> #<Console Output Port>

define

Type:

Operation:

Sets or binds an identifier to a value in the top-level environment, or, as an internal definition, in an environment associated with a procedure or special form.

Arguments:

There are three syntaxes:

First syntax: Two arguments, the first an identifier and the second any Scheme object.

Second syntax: Two or more arguments, the first a proper list of one or more identifiers, and the rest any Scheme objects.

Third syntax: Two or more arguments, the first a list of identifiers to which is appended a final identifier; that is, a list of the form (identifier1 identifier2 ... identifierN-1 . identifierN), the noteworthy feature being the dot before the final identifier, and the rest any Scheme objects.

Side Effects:

First Syntax: If the first argument has never had a value or binding in the relevant environment, gives it one. If a previous binding or value of the first argument does exist in the relevant environment, modifies it. In either case, the first argument ends up with the second argument as its value or binding, (depending on whether the second argument is of a kind that requires a binding).

In the case of internal definitions, the argument cannot have a previous binding, since the syntax restricts such definitions to the beginning of the lexical scope for the environment in question.

Second Syntax: The second syntax is shorthand, or "syntactic sugar" for binding an identifier to a lambda expression. The first element of the first argument is taken to be the identifier. The remaining elements of the first argument are taken to be the formal arguments to the lambda expression. The remaining arguments are taken to be the contents of the body of the lambda expression. Thus

(define (name var1 var2 ... varN)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda (var1 var2 ... varN)
    expression1
    expression2
      ...
    expressionN
    )
  )

Third Syntax: The third syntax is shorthand, or "syntactic sugar" for binding an identifier to a lambda expression. The first element of the first argument is taken to be the identifier. The remaining elements, of the first argument, except the one after the dot, are taken to be formal arguments to the lambda expression, and the identifier after the dot has bound to it a list of any remaining actual arguments to the lambda expression when it is called. The remaining arguments to "define" are taken to be the contents of the body of the lambda expression. Thus

(define (name var1 var2 ... varN-1 . varN)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda (var1 var2 ... varN-1 . varN)
    expression1
    expression2
      ...
    expressionN
    )
  )

and

(define (name . var)
  expression1
  expression2
    ...
  expressionN
  )

is equivalent to

(define name
  (lambda var
    expression1
    expression2
      ...
    expressionN
    )
  )

Returned Value:

First syntax: the first argument.

Second and third syntaxes: the first element of the first argument.

For Example:

(define a 42)      ;; ==> a
a                  ;; ==> 42

(define a 'foo)    ;; ==> a
a                  ;; ==> foo

(define (hypotenuse x y)
  (sqrt (+ (* x x) (* y y))))
                   ;; ==> hypotenuse
(hypotenuse 5 12)  ;; ==> 13

(define (foo . a) (display a))  ;; ==> foo
(foo 1 2 3 4 5)                 ;; ==> (1 2 3 4 5)#t

(define (foo b . c)
  (display b)
  (display c))     ;; ==> foo
(foo 1 2 3 4 5)    ;; ==> 1(2 3 4 5)#t

define-syntax

Type:

Operation:

Define an hygienic macro at top-level.

Arguments:

One symbol and one <transformer spec>, the latter according to the grammar of "R5" report section 4.3.2.

Side Effects:

If the first argument has never had a value or binding in the top-level environment, gives it one. If a previous binding or value of the first argument does exist in the top-level environment, modifies it. In either case, the first argument ends up with the macro transformer corresponding to the second argument, as its a binding.

Returned Value:

The first argument.

For Example:

(define-syntax
   when
   (syntax-rules ()
     ((when test stmt) (if test stmt))
     ((when test stmt ...) (if test (begin stmt ...))
     )))
  ;; ==> when

(when #t 3)  ;; ==> 3
(when #f 3)  ;; ==> #f

(when #t (display "foo\n") (display "bar\n") 42)  ;; ==>
foo
bar
42

delay

Type:

Operation:

Encapsulate a Scheme expression in such a way that it can be evaluated subsequently, by the "force" procedure, and its value then returned.

Arguments:

One Scheme object of any kind.

Side Effects:

None in its own right; side effects due to the eventual evaluation of the argument may occur, depending on the argument.

Returned Value:

A promise.

For Example:

;; Note how Wraith Scheme displays a promise:

(delay (display "Carpe diem\n"))  ;; ==> #<Promise>

(define foo (delay (begin (display "Carpe diem\n") 123)))
                   ;; ==> foo
foo                ;; ==> #<Promise>
(force foo)        ;; ==>
Carpe diem         ;;  Side effect of evaluation.
123                ;;  The returned value.
(force foo)        ;; ==>
123                ;;  Evaluation happens only once --
                   ;;    the returned value is saved so
                   ;;    it may be returned repeatedly.
(force foo)        ;; ==> 123
foo                ;; ==> #<Promise>

denominator

Type:

Procedure.

Operation:

Obtain the denominator of a rational number, having first expressed the number as a fraction in lowest terms, with a positive denominator.

Arguments:

One rational number.

Side Effects:

None.

Returned Value:

The denominator of the argument, which is taken to be a fraction expressed in lowest terms, with a positive denominator. The denominator of zero is taken to be one.

For Example:

(denominator 2/3)     ;; ==> 3
(denominator -4/6)    ;; ==> 3
(denominator 0)       ;; ==> 1
(denominator 0.1)     ;; ==> 36028797018963968.

display

Type:

Procedure.

Operation:

Output an external representation of a Scheme object in a form intended easily to be read by sentient beings. Contrast with "write", whose output is intended easily to be read by computers and programmers ...

Arguments:

One or two arguments. The first may be any Scheme object. The second, if present, must be an open output port.

Side Effects:

Writes output -- if there is a second argument, to that port, otherwise, to the current output port.

Returned Value:

For Example:

(display "This string\nhas three\nembedded newlines.\n")  ;; ==>
This string
has three
embedded newlines.
#t
(display 5/7)  ;; ==> 5/7

(let ((my-port (open-output-file "Foo")))
  (display 5/7 my-port)
  (close-output-port my-port))  ;; ==> #t  ;;  And writes to "Foo".

do

Type:

Operation:

Perform iteration, testing a termination condition before each iteration; optionally, create an environment, with local variables, in which the iterations are to be performed, and with means of initializing those values and bindings, and of changing them during successive iterations.

CAUTION: Wraith Scheme's implementation of "do" is slow, and uses lots of memory.

Technical Note: Wraith Scheme needs "do" because the R5 standard requires it. The present release provides a version that works, but I suggest that you avoid it when you can. I may get around to writing a better implementation some day, but that is a low-priority task: I don't use "do" much myself.

Arguments:

At least two:

The first argument is a proper list, each of whose arguments is a list of two or three elements. The first is an identifier, the second an initial value or binding for the identifier, and the third, if present, an expression to be evaluated after each iteration, whose evaluation provides the value or binding for the identifier for the next iteration.

The second argument is a proper list of two or more arguments. The first is a test to be evaluated before each iteration; if it evaluates to true, no further iterations are performed, the remaining elements of the second argument are evaluated in sequence, and the "do" returns the result of the last such evaluation. If the test evaluates to false, the next iteration is performed.

The remaining arguments are evaluated in sequence during each iteration.

Side Effects:

None in its own right, but possibly many in consequence of the nature of the arguments.

Note that Wraith Scheme's present implementation of "do" is very slow and uses lots of memory.

Returned Value:

Any Scheme object, depending on the arguments; or the do may never return.

For Example:

(do ((vec (make-vector 3))
     (k 0 (+ k 1)))
    ((= k 3) vec)
  (vector-set! vec k (* k k)))  ;; ==> #(0 1 4)

(do

    ;; List of initialization-and-update clauses:
    ;; Each specifies a variable name, its initial
    ;;   value, and any automatic update to it, that
    ;;   takes place after each pass through the loop.

    ((vec (make-vector 3))  ;; No automatic change to vec.
     (k   0 (+ k 1)))       ;; Change k to (+ k 1) after each loop.

  ;; Loop test and body follow ...

  (if (= k 3)
    then-return vec)        ;; ((= k 3)) would stop the do but
                            ;;   return an undefined value.
  else
    (vector-set! vec k (* k k))

  ;; Update variables as specified in the clauses for
  ;;   initialization-and-update -- e.g., replace k by
  ;;   (+ k 1) -- and then go back for another pass
  ;;   through the loop test and body.

  )

  ;; ==> #(0 1 4)

dynamic-wind

Type:

Procedure.

Operation:

Force two given procedures to be called when execution respectively enters and leaves the dynamic extent of another given procedure. The first argument is to be called on entry to the dynamic extent of the second, and the third on exit from the dynamic extent of the second.

Arguments:

Three procedures, each of which must accept no arguments.

Side Effects:

None in its own right, but the given procedures may have side effects of their own.

Returned Value:

Whatever the second argument returns, if it returns at all.

For Example:

(define (foo) (display "Entering -  "))   ;; ==> foo
(define (bar) (display "\"bar\""))        ;; ==> bar
(define (baz) (display " - leaving\n"))   ;; ==> baz
(bar)                                     ;; ==> "bar"
(dynamic-wind foo bar baz)                ;; ==> Entering - "bar" - leaving

(let ((path '())
      (c #f))
  (let ((add (lambda (s) (set! path (cons s path)))))
    (dynamic-wind
      (lambda () (add 'connect))
      (lambda ()
        (add 
          (call-with-current-continuation
            (lambda (c0)
              (set! c c0)
              'talk1))))
      (lambda () (add 'disconnect)))
  (if (< (length path) 4)
    (c 'talk2)
    (reverse path))))

  ;; ==> (connect talk1 disconnect connect talk2 disconnect)

else

Type:

Reserved identifier, for use in "cond", which see.

Operation:

None.

Arguments:

Does not apply.

Side Effects:

Does not apply.

Returned Value:

Does not apply.

For Example:

See "cond".

eof-object?

Type:

Procedure.

Operation:

Test whether the argument is an end-of-file object.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean. Returns #t if, and only if, the argument is an end-of-file object. Otherwise, returns #f.

For Example:

;; Suppose foo is an input port to a file containing
;; three characters, and that Wraith Scheme has already
;; read those characters.

(eof-object? (read-char foo))  ;; ==> #t
(eof-object? 42)               ;; ==> #f

eq?

Type:

Procedure.

Operation:

Test whether two Scheme objects are the same in the sense that either

(1) the objects are of the same kind, and the same region of Scheme main memory is used to store both, so that any alteration of one object necessarily alters the other (this form of identity is sometimes called "pointer equality"), or

(2) the objects are of the same kind, and each can be represented entirely within the 64-bit pointer field of a Scheme tagged pointer, and the necessary 64-bit representations are identical.

Technical Note: The behavior of "eq?" is allowed to be implementation-dependent; what Wraith Scheme does is first make sure that the objects are the same kind, and if so, return #t if, and only if, their pointer fields are identical, or if they are certain objects such as #t, #f and '(), which do not require the pointer field at all.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if the two arguments are identical in the sense described in the "Operation" section above.. Otherwise, returns #f.

For Example:

(eq? 1 1)      ;; ==> #t
(eq? 1 2)      ;; ==> #f
(eq? #\a #\a)  ;; ==> #t
(eq? #\a #\b)  ;; ==> #f
(eq? #t #t)    ;; ==> #t
(eq? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(eq? a (car b))          ;; ==> #t

(define c (list 1 2))        ;; ==> c
(eq? a c)                    ;; ==> #f  
                             ;; Two different lists.

(eq? (list 1 2) (list 1 2))  ;; ==> #f  ;; Ditto.

equal?

Type:

Procedure.

Operation:

Test for equality of Scheme objects by recursively descending through pairs, lists, vectors, and strings, and applying "eqv?" to compare their contents where further recursive descent does not occur.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the arguments are equal in the sense described in the "Operation" section above. Otherwise, returns #f. May not return, if the data structures being compared are circular.

For Example:

(equal? 1 1)      ;; ==> #t
(equal? 1 2)      ;; ==> #f
(equal? #\a #\a)  ;; ==> #t
(equal? #\a #\b)  ;; ==> #f
(equal? #t #t)    ;; ==> #t
(equal? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(equal? a (car b))       ;; ==> #t

(define c (list 1 2))
(equal? a c)             ;; ==> #t
                         ;; Different lists notwithstanding.

(equal? (list 1 2) (list 1 2))  ;; ==> #t  ;; Ditto.

eqv?

Type:

Procedure.

Operation:

Test whether two Scheme objects should "normally be regarded as the same object" (according to the R5 report). What Wraith Scheme does is return #t if the objects are "eq?", or if they are both numbers, both have the same value, and are either both exact or both inexact.

Technical Note: Much of the vagueness in the R5 definition of "eqv?" stems from the prospect that some Scheme implementations may upon occasion be able to prove that functions that do not have identical source code always return the same value when given the same arguments. Wraith Scheme makes no pretensions of ever being able to do any such thing; it returns #t from an "eqv?" test on functions only in case of pointer identity.

Arguments:

Two Scheme objects.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if the arguments are "eq?". If not, returns #t if the arguments are both numbers, and have the same numeric value, and are either both exact or both inexact. Otherwise, returns #f.

For Example:

(eqv? 1 1)      ;; ==> #t
(eqv? 1 2)      ;; ==> #f
(eqv? #\a #\a)  ;; ==> #t
(eqv? #\a #\b)  ;; ==> #f
(eqv? #t #t)    ;; ==> #t
(eqv? #t #f)    ;; ==> #f

(define a (list 1 2))    ;; ==> a
(define b (cons a '()))  ;; ==> b
(eqv? a (car b))         ;; ==> #t

(define c (list 1 2))
(eqv? a c)                    ;; ==> #f
                              ;; Two different lists.

(eqv? (list 1 2) (list 1 2))  ;; ==> #f  ;; Ditto.

(eqv? 1 #e1.0)  ;; ==> #t
(eqv? 1 #i1.0)  ;; ==> #f

eval

Type:

Procedure.

Operation:

Evaluate an expression in a specified environment.

Arguments:

One Scheme object, and one instance of what is returned by one of the procedures "interaction-environment", "null-environment", or "scheme-report-environment".

Side Effects:

None in its own right, but the side effects of evaluating an expression may be substantial.

Returned Value:

The result of the evaluation.

For Example:

(eval '(+ 2 2) (interaction-environment))
;; ==> 4
(eval '(+ 2 2) (scheme-report-environment 5))
;; ==> 4
(eval '(+ 2 2) (null-environment 5))
;; ==> <error>  ;; "+" is not defined in the null environment.
(eval '(if #t 2 3) (null-environment 5))
;; ==> 2
(define a 42)
;; ==> a
a
;; ==> 42
(let ((a 3)) a)
;; ==> 3
(let ((a 3)) (eval 'a (interaction-environment)))
;; ==> 42

even?

Type:

Procedure.

Operation:

Test whether an integer is even.

Arguments:

One integer.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an even number. Otherwise, returns #f.

For Example:

(even? 42)   ;; ==> #t
(even? 137)  ;; ==> #f

exact->inexact

Type:

Procedure.

Operation:

Create an inexact representation of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

An inexact number whose value is the same as the argument.

For Example:

(exact->inexact 1)    ;; ==> 1.
(exact->inexact #i1)  ;; ==> 1.
(exact->inexact +i)   ;; ==> 1.i

exact?

Type:

Procedure.

Operation:

Test whether a number is exact.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is exact. Otherwise, returns #f.

For Example:

(exact? 1)   ;; ==> #t
(exact? 1.)  ;; ==> #f

exp

Type:

Procedure.

Operation:

Mathematical exponentiation.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A number: Returns the base of the natural logarithms raised to the argument.

For Example:

(exp 0)                    ;; ==> 1
(exp 1)                    ;; ==> 2.7182818284590451
(exp -2.5)                 ;; ==> 0.0820849986238988
(exp 3.1415926535897931i)  ;; ==> -1.+1.2246467991473532e-16i

expt

Type:

Procedure.

Operation:

Raise a number to a power.

Arguments:

Two numbers.

Side Effects:

None.

Returned Value:

The first argument raised to the second argument.

For Example:

(expt 2 3)                          ;; ==> 8
(expt 3 2)                          ;; ==> 9
(expt 2 0.5)                        ;; ==> 1.4142135623730951
(expt 1.4142135623730951 0.5)       ;; ==> 1.189207115002721
(expt -1 0.5)                       ;; ==> 6.123233995736766e-17+1.i
(expt (exp 1) 3.1415926535897931i)  ;; ==> -1.+1.2246467991473532e-16i

floor

Type:

Procedure.

Operation:

Arithmetic round down.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The greatest integer not greater than the argument.

For Example:

(floor -6.5)  ;; ==> -7.
(floor 4)     ;; ==> 4

for-each

Type:

Procedure.

Operation:

Call a procedure many times, with different arguments, in a specified order.

Arguments:

Two or more. The first argument is the procedure to call. The rest must all be proper lists of the same length, and the number of arguments beyond the first must equal the number of arguments with which the procedure is to be called. On the first call, the arguments passed to the procedure are the first elements of each list, in the same order as the lists. On the second call, the passed arguments are the second elements of the lists, and so on.

Side Effects:

None in its own right, but the intended purpose of "for-each" is to call a procedure repeatedly, for side effects, so there will likely be side effects, depending on the arguments.

Returned Value:

For Example:

(define (make-sandwich first second bread)
  (display first)
  (display " and ")
  (display second)
  (display " on ")
  (display bread)
  (newline)
  'yum)  ;; ==> make-sandwich
(for-each
  make-sandwich
  (list "ham" "tuna" "tofu" "peanut butter")
  (list "cheese" "tomato" "sprouts" "asparagus")
  (list "rye" "whole wheat" "seven-grain" "banana bread")
  )  ;; ==>
ham and cheese on rye
tuna and tomato on whole wheat
tofu and sprouts on seven-grain
peanut butter and asparagus on banana bread
#t

force

Type:

Procedure.

Operation:

Cause the evaluation of a Scheme expression previously encapsulated as a promise, for lazy evaluation, by the "delay" procedure; or if that promise has already been forced, return whatever value it returned at that time.

Arguments:

One promise.

Side Effects:

None in its own right, though the evaluation of the promise may cause side effects, depending on the nature of the promise.

Returned Value:

As promised.

For Example:

;; Note how Wraith Scheme displays a promise:

(delay (display "Carpe diem\n"))  ;; ==> #<Promise>

(define foo (delay (begin (display "Carpe diem\n") 123)))
    ;; ==> foo

(force foo)        ;; ==>
Carpe diem         ;; Side effect of evaluation.
123                ;; The returned value.
(force foo)        ;; ==>
123                ;; Evaluation happens only once --
                   ;;   the returned value is saved so
                   ;;   it may be returned repeatedly.
(force foo)        ;; ==>
123

gcd

Type:

Procedure.

Operation:

Mathematical greatest common divisor.

Arguments:

One or more integers.

Side Effects:

None.

Returned Value:

An integer: Returns the greatest common divisor of the arguments.

For Example:

(gcd 28 98)                ;; ==> 14
(gcd 999999999999 209457)  ;; ==> 333
(gcd 34 85 68)             ;; ==> 17

if

Type:

Operation:

Conditional evaluation, based on a test.

Arguments:

Two or three Scheme objects.

Side Effects:

None in its own right, others depending on the arguments.

Returned Value:

Evaluates the first argument: If the result is true, evaluates the second argument and returns the result of so doing. If the first argument evaluates to false, and there is a third argument, returns the result of evaluating the third argument. If the first argument evaluates to false, and there is no third argument, returns #f.

For Example:

(if #t (+ 1 2) (+ 3 4))  ;; ==> 3
(if #f (+ 1 2) (+ 3 4))  ;; ==> 7
(if #f (+ 1 2))          ;; ==> #f

imag-part

Type:

Procedure.

Operation:

Obtain the imaginary part of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The imaginary part of the number.

For Example:

(imag-part 1)     ;; ==> 0
(imag-part +i)    ;; ==> 1
(imag-part 1.+i)  ;; ==> 1.

inexact->exact

Type:

Procedure.

Operation:

Create an exact representation of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

An exact number whose value is the same as the argument.

For Example:

(inexact->exact 1)    ;; ==> 1
(inexact->exact #i1)  ;; ==> 1
(inexact->exact 1.i)  ;; ==> +i

inexact?

Type:

Procedure.

Operation:

Test whether a number is inexact.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is inexact. Otherwise, returns #f.

For Example:

(inexact? 1)   ;; ==> #f
(inexact? 1.)  ;; ==> #t

input-port?

Type:

Procedure.

Operation:

Test whether the argument is an input port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an input port. Otherwise, returns #f. Note that once an input port has been closed, it is no longer a port in the sense of the R5 report, because it cannot deliver characters on demand.

For Example:

(define foo (open-input-file "This.file.must.exist"))  ;; ==> foo
(input-port? foo)       ;; ==> #t
(close-input-port foo)  ;; ==> #t
(input-port? foo)       ;; ==> #f
(input-port? 42)        ;; ==> #f

integer->char

Type:

Procedure.

Operation:

Determine the ASCII character represented by the argument.

Arguments:

One integer in the range [0..127]

Side Effects:

None.

Returned Value:

A character: Returns the ASCII character represented by the argument.

For Example:

(integer->char 65)   ;; ==> #\A
(integer->char 128)  ;; ==> <error>

integer?

Type:

Procedure.

Operation:

Test whether the argument is an integer.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an integer. Otherwise, returns #f.

For Example:

(integer? 3)    ;; ==> #t
(integer? 3.1)  ;; ==> #f

;; Technically, an integer is a real number with no fractional
;; part.  The floating-point representations used by Wraith
;; Scheme do not contain enough bits to represent the
;; fractional parts of numbers of large absolute value, hence
;; such numbers are necessarily reported as integers.  Thus:

(integer? (/ 1.e100 3))  ;; ==> #t

;; Note that in Wraith Scheme

(/ 1.e100 3)  ;; ==> 3.3333333333333332e99

;; which is 33333333333333332 followed by lots of zeros --
;; unarguably the external representation of an integer.

interaction-environment

Type:

Procedure.

Operation:

Return the Scheme environment in which expressions typed in the top-level read-eval-print loop are evaluated.

Arguments:

None.

Side Effects:

None.

Returned Value:

The top-level environment of Wraith Scheme.

For Example:

(eval '(+ 2 2) (interaction-environment))
4

lambda

Type:

Operation:

Create an unnamed procedure

Arguments:

Two or more. There are three syntaxes:

First syntax: Two or more arguments, the first a proper list of one or more identifiers, and the rest any Scheme objects.

Second syntax: Two or more arguments, the first a list of identifiers to which is appended a final identifier; that is, a list of the form (identifier1 identifier2 ... identifierN-1 . identifierN), the noteworthy feature being the dot before the final identifier, and the rest any Scheme objects.

Third syntax: Two or more arguments, the first an identifier and the rest any Scheme objects.

Side Effects:

None.

Returned Value:

A lambda expression. The arguments after the first are the body of the lambda expression. The meaning of the first argument varies:

First syntax: The first argument is a list of the formal arguments of the lambda expression.

Second syntax: All elements of the first argument before the dot are taken to be formal arguments to the lambda expression, and the identifier after the dot will have a list of any remaining actual arguments to the lambda expression bound to it when the lambda expression is called.

Third syntax: The first argument will have a list of all actual arguments to the lambda expression bound to it when the lambda expression is called.

For Example:

(define hypotenuse
  (lambda (x y)
    (sqrt (+ (* x x) (* y y)))))
                  ;; ==> hypotenuse
(hypotenuse 5 12) ;; ==> 13

(define foo
  (lambda a (display a)))  ;; ==> foo
(foo 1 2 3 4 5)            ;; ==> (1 2 3 4 5)#t

(define foo
  (lambda (b . c)
    (display b)
    (display c)))  ;; ==> foo
(foo 1 2 3 4 5)    ;; ==> 1(2 3 4 5)#t

lcm

Type:

Procedure.

Operation:

Mathematical least common multiple.

Arguments:

One or more integers.

Side Effects:

None.

Returned Value:

An integer: Returns the least common multiple of the arguments.

For Example:

(lcm 24 60)  ;; ==> 120
(lcm 99 88)  ;; ==> 792
(lcm 4 5 6)  ;; ==> 60

length

Type:

Procedure.

Operation:

Find the length of a proper list.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

An integer: Returns the length of the list.

For Example:

(length (list 'a 'b 'c))  ;; ==> 3
(length '())              ;; ==> 0
(length '(1 2 . 3))       ;; ==> <error>

let

Type:

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. The local variables created may not access each other in establishing their initial values. Contrast with "let*".

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second, when evaluated, being the initial value or binding for that identifier. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(define a 'aa)  ;; ==> a
(define b 'bb)  ;; ==> b
(define c 'cc)  ;; ==> c
(let
  ((a c)   ;; Local a gets the top-level value of c, which is 'cc
   (b a)   ;; Local b gets the top-level value of a, which is 'aa
   (c b))  ;; Local c gets the top-level value of b, which is 'bb
  (list a b c))  ;; ==> (cc aa bb)  ;; The values local to the let.

let-syntax

Type:

Operation:

Creates an environment with local variables whose bindings are the transformers of hygienic macros (according to the "R5" description thereof), and evaluates expressions therein. The local variables created may not access each other in establishing their initial values. Contrast with "letrec-syntax".

Arguments:

Two or more. The first is a list of two-element sublists, the first element in each sublist being an identifier and the second a <transformer spec>, according to the grammar of "R5" report section 4.3.2. All remaining arguments are the expressions to be evaluated, in the order given, in the environment so created.

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(let ((x 'outer))
    (let-syntax ((m (syntax-rules () ((m) x))))
      (let ((x 'inner))
        (m))))

  ;; ==> outer

let*

Type:

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. Each local variable created may access the local variables created before it when establishing its initial value. Contrast with "let".

Arguments:

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(define a 'a)    ;; ==> aa
(define b 'b)    ;; ==> bb
(define c 'c)    ;; ==> cc
(let*
  ((a c)   ;; Local a gets the top-level value of c, which is cc
   (b a)   ;; Local b gets the local value of a, which is cc
   (c b))  ;; Local c gets the local value of b, which is cc
  (list a b c))  ;; ==> (cc cc cc)  ;; The values local to the let.

letrec

Type:

Operation:

Creates an environment with local variables which have initial values or bindings, and evaluates expressions therein. Each local variable created may access all local variables created by the letrec when establishing its initial value, which typically makes the most sense when what the variables are bound functions that reference one another.. Contrast with "let" and "let*".

Wraith Scheme does NOT report an error if the local variables of a letrec are used in such a way that the initialization expressions are undefined or unbound: The R5 report merely states that such pre-initialization values are undefined. That may be confusing at times. Thus the example used for let and let* gives the following result for letrec:

(define a 'aa)   ;; ==> a
(define b 'bb)   ;; ==> b
(define c 'cc)   ;; ==> c
(letrec
  ((a c)   ;; Local a wants to get the local value of c, which has no local binding.
   (b a)   ;; Local b wants to get the local value of a, which has no local binding.
   (c b))  ;; Local c wants to get the local value of b, which has no local binding.
  (list a b c))  ;; ==> (c c c)  ;; The "undefined" values turn out to be the symbols provided.

That latter result, however, need not obtain with other Scheme implementations.

Arguments:

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(letrec
  ((my-even? (lambda (n)
               (if (zero? n)
                 #t
                 (my-odd? (- n 1)))))
   (my-odd? (lambda (n)
              (if (zero? n)
                #f
                (my-even? (- n 1))))))
  (my-even? 42))  ;; ==> #t

letrec-syntax

Type:

Operation:

Creates an environment with local variables which have initial bindings to transformers of hygienic macros, according to the "R5" description thereof. Evaluates expressions therein. Each local variable created may access all local variables created by the letrec-syntax when establishing its initial value, which typically makes the most sense when what the variables are macros that reference one another.. Contrast with "let-syntax".

Wraith Scheme does NOT report an error if the local variables of a letrec-syntax are used in such a way that the initialization expressions are undefined: Wraith Scheme handles "letrec-syntax" by creating a local environment in which the local variables all have values of '().

Arguments:

Side Effects:

Creates a local environment. Other side effects possible, depending on the arguments.

Returned Value:

Whatever results from the evaluation of the last argument.

For Example:

(letrec-syntax
  ((my-or (syntax-rules ()
            ((my-or) #f)
            ((my-or e) e)
            ((my-or e1 e2 ...)
             (let ((temp e1))
               (if temp
                   temp
                   (my-or e2 ...)))))))
  (display (my-or #f #f #t))
  (newline)
  (my-or))

  ;; ==> #t
  ;;     #f

list

Type:

Procedure.

Operation:

Make a list.

Arguments:

Zero or more Scheme objects.

Side Effects:

None.

Returned Value:

A list of the arguments, in order.

For Example:

(list)        ;; ==> ()
(list 1 2 3)  ;; ==> (1 2 3)

list->string

Type:

Procedure.

Operation:

Convert a list of characters to a string containing them in the given order.

Arguments:

One list of zero or more characters.

Side Effects:

None.

Returned Value:

A string whose characters are those in the list, in order.

For Example:

(list->string '())             ;; ==> ""
(list->string '(#\C #\a #\t))  ;; ==> "Cat"

list->vector

Type:

Procedure.

Operation:

Convert a list of Scheme objects to a vector containing them in the given order.

Arguments:

One list of zero or more Scheme objects.

Side Effects:

None.

Returned Value:

A vector whose elements are the elements of the list, in order.

For Example:

(list->vector '())  ;; ==> #()
(list->vector (list 1 (list 2 3 4) (* 6 7) "Foo"))
                    ;; ==> #(1 (2 3 4) 42 "Foo")

list-ref

Type:

Procedure.

Operation:

Obtain an element of a proper list, based on its position.

Arguments:

One proper list and one non-negative integer.

Side Effects:

None.

Returned Value:

A Scheme object: Returns the (zero-based) nth element of the first argument, where n is the second argument.

For Example:

(list-ref '(1 2 3) 0)  ;; ==> 1
(list-ref '(1 2 3) 1)  ;; ==> 2
(list-ref '(1 2 3) 2)  ;; ==> 3

list-tail

Type:

Procedure.

Operation:

Identify a sublist of a given list made by removing elements from the front of the given list.

Arguments:

One proper list and one non-negative integer.

Side Effects:

None.

Returned Value:

A list: Returns the list obtained from the first argument by removing its first n elements, where n is the second argument. The result shares structure with the first argument: Modifying the result, for example by set-car! or set-cdr!, will modify the first argument.

For Example:

(list-tail '(1 2 3) 0)  ;; ==> (1 2 3)
(list-tail '(1 2 3) 1)  ;; ==> (2 3)
(list-tail '(1 2 3) 2)  ;; ==> (3)
(list-tail '(1 2 3) 3)  ;; ==> ()

list?

Type:

Procedure.

Operation:

Test whether a Scheme object is a proper list.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a proper list. Otherwise, returns #f.

For Example:

(list '())             ;; ==> #t
(list '(1 2 3 4 5))    ;; ==> #f
(list '(1 2 3 4 . 5))  ;; ==> #f

(define a (list 1))    ;; ==> a
(set-cdr! a a)         ;; ==> #t
(list? a)              ;; ==> #f    ;; circular list

load

Type:

Procedure.

Operation:

Load a file, and process its contents as if they had been entered at the keyboard. Wraith Scheme prints the results of any such evaluation, but not the literal text of the file itself.

The operation of load is weird, almost by definition: The R5 report states that this procedure "reads expressions and definitions from the file and evaluates them sequentially", but it does not specify what environment they are to be evaluated in. It would be most natural and most straightforward to implement, if "load" evaluated what it read in the same environment in which the load procedure itself was called, which may be within a procedure. Unfortunately, the idea of loading code into the temporary environment for a particular procedure call is very odd; it amounts more or less to changing the source code of the procedure for just that one call.

Having that evaluation take place in the interaction environment is probably a great deal more useful; for then one may more easily use procedures for such purposes as building up the path to the file to be loaded. Such an interpretation does not quite fly in the face of lexical scoping, for there is already one Scheme function -- eval -- that is prepared to evaluate things in a different environment from the one in which it was called.

Wraith Scheme presently loads into the interaction environment.

Arguments:

At most one: If an argument is present, it must be a string containing a Unix-style path to the file to be loaded. If no argument is present, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain such a path from the user.

Side Effects:

Depends on the arguments.

Returned Value:

For Example:

(load "/Users/MyName/MyFavoriteSchemeCode.s")  ;; loads file
    ;; ==> #t
(load)  ;; Wraith Scheme Dialog Panel prompts for pathname.

log

Type:

Procedure.

Operation:

Mathematical natural logarithm.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A number: Returns the natural logarithm of the argument.

For Example:

(log 1)                       ;; ==> 0
(log 2.7182818284590451)      ;; ==> 1.
(log (/ 2.7182818284590451))  ;; ==> -1.
(log -1)                      ;; ==> 3.1415926535897931i

magnitude

Type:

Procedure.

Operation:

Obtain the magnitude of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The magnitude of the number.

For Example:

(magnitude 1)     ;; ==> 1
(magnitude -1)    ;; ==> 1
(magnitude +i)    ;; ==> 1
(magnitude 1.+i)  ;; ==> 1.4142135623730951

make-polar

Type:

Procedure.

Operation:

Create a complex number from its magnitude and angle.

Arguments:

Two reals, the first the magnitude of the desired complex number, the second its angle. Note that R5 allows the magnitude to be negative.

Side Effects:

None.

Returned Value:

A number: The complex number constructed from the given magnitude and angle.

For Example:

(make-polar 1 0)                   ;; ==> 1
(make-polar -1 0)                  ;; ==> -1
(make-polar 1 1.5707963267948966)  ;; ==> 6.123233995736766e-17+1.i

make-rectangular

Type:

Procedure.

Operation:

Create a complex number from its real and imaginary parts.

Arguments:

Two reals, the first the real part of the desired complex number, the second the imaginary part.

Side Effects:

None.

Returned Value:

A number: The complex number constructed from the given real and imaginary part.

For Example:

(make-rectangular 1 1)  ;; ==> 1+i
(make-rectangular 0 1)  ;; ==> +i
(make-rectangular 1 0)  ;; ==> 1

make-string

Type:

Procedure.

Operation:

Create a string, and optionally fill it with a specific character.

Arguments:

Zero, one or two: The first a nonnegative integer, the second, if present, a character.

Side Effects:

None.

Returned Value:

A string: Returns a string whose length is the first argument. If the second argument is present, every character in the new string will be the same as the second argument. If there is no second argument, the string will be filled with blanks.

With no arguments, prompts the user to type a string in the Wraith Scheme Dialog Panel. Enclosing double-quotes are not required in this case.

For Example:

(make-string 0)      ;; ==> ""
(make-string 3)      ;; ==> "   "
(make-string 3 #\q)  ;; ==> "qqq"
(make-string)        ;; Wraith Scheme prompts the user to
                     ;;   type in a string.

make-vector

Type:

Procedure.

Operation:

Create a vector, and optionally fill it with a specific Scheme object.

Arguments:

One or two: The first a nonnegative integer, the second, if present, any Scheme object.

Side Effects:

None.

Returned Value:

A vector: Returns a vector whose length is the first argument. If the second argument is present, every character in the new vector will be the same as the second argument. If there is no second argument, the vector will be filled with the empty list.

For Example:

(make-vector 0)  ;; ==> #()
(make-vector 3)  ;; ==> #(() () ())
(make-vector 3 (list 1 2))
                 ;; ==> #((1 2) (1 2) (1 2))

map

Type:

Procedure.

Operation:

Call a procedure many times, with different arguments, in an unspecified order, and return a list of the results.

Arguments:

Two or more. The first argument is the procedure to call. The rest must all be proper lists of the same length, and the number of arguments beyond the first must equal the number of arguments with which the procedure is to be called. There will be as many calls of the procedure as there are elements in each list. There is no guarantee that the calls will be in any specified order, but for purposes of explanation, let us number them from one to N, N being the number of elements in each list.

On call number 1, the arguments passed to the procedure are the first elements of each list, in the same order as the lists. On call number 2, the passed arguments are the second elements of the lists, and so on.

Side Effects:

None in its own right, but there may be side effects of the procedure calls, depending on the arguments.

Returned Value:

A list of results of the call, in order from 1 to N, as outlined in the "Operation" section above.

For Example:

(define (make-sandwich first second bread)
  (display first)
  (display " and ")
  (display second)
  (display " on ")
  (display bread)
  (newline)
  (if (equal? bread "banana bread")
    'yech
    'yum))  ;; ==> make-sandwich
(map
  make-sandwich
  (list "ham" "tuna" "tofu" "peanut butter")
  (list "cheese" "tomato" "sprouts" "asparagus")
  (list "rye" "whole wheat" "seven-grain" "banana bread")
  )  ;; ==> ham and cheese on rye
     ;;     tuna and tomato on whole wheat
     ;;     tofu and sprouts on seven-grain
     ;;     peanut butter and asparagus on banana bread
     ;;     (yum yum yum yech)

max

Type:

Procedure.

Operation:

Arithmetic maximum.

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A number: Returns the maximum of the arguments.

For Example:

(max -17 23 -102.5 9)  ;; ==> 23

member

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "equal?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "equal?" to the first argument. If no such sublist exists, returns #f.

For Example:

(member 2 (list 1 2 3))        ;; ==> (2 3)
(member 'b '(a b c))           ;; ==> (b c)
(member (list 'a) '(b (a) c))  ;; ==> ((a) c)

memq

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "eq?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "eq?" to the first argument. If no such sublist exists, returns #f.

For Example:

(memq 2 (list 1 2 3))        ;; ==> (2 3)
(memq 'b '(a b c))           ;; ==> (b c)
(memq (list 'a) '(b (a) c))  ;; ==> #f

memv

Type:

Procedure.

Operation:

Identify the first sublist of a list whose car is "eqv?" to a given object.

Arguments:

Two: The first is any Scheme object, the second a proper list.

Side Effects:

None.

Returned Value:

Returns the first (longest) sublist of the second argument whose car is "eqv?" to the first argument. If no such sublist exists, returns #f.

For Example:

(memv 2 (list 1 2 3))        ;; ==> (2 3)
(memv 'b '(a b c))           ;; ==> (b c)
(memv (list 'a) '(b (a) c))  ;; ==> #f

min

Type:

Procedure.

Operation:

Arithmetic minimum

Arguments:

Two or more real numbers.

Side Effects:

None.

Returned Value:

A number: Returns the minimum of the arguments.

For Example:

(min -17 23 -102.5 9)  ;; ==> -102.5

modulo

Type:

Procedure.

Operation:

Mathematical modulus.

Arguments:

Two integers.

Side Effects:

None. o

Returned Value:

An integer: Returns the first argument modulo the second.

For Example:

(modulo 13 4)    ;; ==> 1
(modulo -13 4)   ;; ==> 3
(modulo 13 -4)   ;; ==> -3
(modulo -13 -4)  ;; ==> -1

negative?

Type:

Procedure.

Operation:

Test whether a number is negative.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is negative. Otherwise, returns #f.

For Example:

(negative? 0)   ;; ==> #f
(negative? 1)   ;; ==> #f
(negative? -1)  ;; ==> #t

newline

Type:

Procedure.

Operation:

Write a newline character, the ASCII character whose numeric representation is 10, to a port.

Arguments:

At most one, a port.

Side Effects:

Writes a newline to the given port, if there is an argument, or to the current output port, if not.

Returned Value:

For Example:

(newline)      ;; ==> 
               ;;  Just wrote a newline.

;;  Suppose "foo" is an output port:

(newline foo)  ;; ==> #t  ;; Wrote a newline to foo

not

Type:

Procedure.

Operation:

Boolean negation.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is #f. Otherwise, returns #f.

For Example:

(not #f)   ;; ==> #t
(not 42)   ;; ==> #f
(not '())  ;; ==> #f

null-environment

Type:

Procedure.

Operation:

Return a Scheme environment which is supposed to contain only the syntactic keywords of Scheme, but which in Wraith Scheme contains a few more bindings.

Arguments:

One, which must be the exact integer 5.

Side Effects:

None.

Returned Value:

The null environment of Wraith Scheme, which contains bindings for the following symbols:

=> and begin c::begin c::if c::lambda c::set! case cond define delay do else if lambda let let* letrec or quasiquote quote set! unquote unquote-splicing

The "extra" symbols are macros used in defining several of the syntactic keywords. I couldn't come up with any other reasonable place to put them.

For Example:

(eval '(if #t 2 3) (null-environment 5))
2

null?

Type:

Procedure.

Operation:

Test whether an object is the empty list.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is the empty list. Otherwise, returns #f.

For Example:

(null? #f)   ;; ==> #f
(null? 42)   ;; ==> #f
(null? '())  ;; ==> #t

number->string

Type:

Procedure.

Operation:

Create a string containing an external representation of a given number.

Arguments:

One or two: The first a number, the second an exact integer, either 2, 8, 10 or 16, corresponding to the radix in which the number is to be represented. This procedure cannot display a quantity that is not an exact integer with using radix other than 10. Thus rationals that are not exact integers as well as complex numbers with real or imaginary parts that are not exact integers, cannot be displayed using radices 2, 8 or 16.

Side Effects:

None.

Returned Value:

A string: Returns a string representing the first argument in the given radix, if a second argument is present, or in radix 10 if there is no second argument. The result never contains a radix prefix. The result must be such that, informally, if you read it back in using "string->number" in the correct radix, the number you get is "eqv?" to the original argument.

For Example:

(number->string 10)          ;; ==> "10"
(number->string 10 2)        ;; ==> "1010"
(number->string 10 8)        ;; ==> "12"
(number->string 10 16)       ;; ==> "a"
(number->string 5/3)         ;; ==> "5/3"
(number->string 15+14i)      ;; ==> "15+14i"
(number->string 15+14i 8)    ;; ==> "17+16i"
(number->string 15+14i)      ;; ==> "15+14i"
(number->string 15.5+14i 8)  ;; ==> <error>

number?

Type:

Procedure.

Operation:

Test whether a Scheme object is a number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a number. Otherwise, returns #f. Wraith Scheme considers nans and infs not to be numbers.

For Example:

(number? 'foo)                 ;; ==> #f
(number? 1.234)                ;; ==> #t
(number? 1e10000)              ;; ==> #f  ;; inf
(number? (/ 1e10000 1e10000))  ;; ==> #f  ;; nan

numerator

Type:

Procedure.

Operation:

Obtain the numerator of a rational number, having first expressed the number as a fraction in lowest terms, with a positive denominator.

Arguments:

One rational number.

Side Effects:

None.

Returned Value:

The numerator of the argument, which is taken to be a fraction expressed in lowest terms, with a positive denominator.

For Example:

(numerator 2/3)     ;; ==> 2
(numerator -4/6)    ;; ==> -2
(numerator 0)       ;; ==> 0
(numerator 0.1)     ;; ==> 3602879701896397.

odd?

Type:

Procedure.

Operation:

Test whether an integer is odd.

Arguments:

One integer.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an odd number. Otherwise, returns #f.

Many people think that all numbers are odd. I do not sympathize, but perhaps that is because I am odd myself.

For Example:

(odd? 42)   ;; ==> #f
(odd? 137)  ;; ==> #t

open-input-file

Type:

Procedure.

Operation:

Open a port to a file for input.

Arguments:

At most one: If present, a string containing a Unix-style path to the file to be opened. If there is no argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain a path from the user.

Side Effects:

Opens a port.

Returned Value:

An input port.

For Example:

(open-input-file "/Users/Me/MySourceFile.s")
                   ;; ==> <Input Port ... >
                   ;;  The text will describe the port
(open-input-file)  ;;  Wraith Scheme will use the Dialog Panel
                   ;;  to obtain the path to the file.

open-output-file

Type:

Procedure.

Operation:

Open a port to a file for output.

Arguments:

At most one: If present, a string containing a Unix-style path to the file to be opened. If there is no argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain a path from the user.

Side Effects:

Opens a port.

Returned Value:

An output port.

For Example:

(open-output-file "/Users/Me/MyOutputFile.text")
                    ;; ==> <Output Port ... >
                    ;;  The text will describe the port
(open-output-file)  ;;  Wraith Scheme will use the Dialog Panel
                    ;;  to obtain the path to the file.

or

Type:

Operation:

Boolean or.

Arguments:

Zero or more Scheme objects of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, at least one of the arguments is true. (Recall that the only Scheme object that is false is #f.) With no arguments, returns #f. Otherwise, returns #f

This macro operates by evaluating its arguments one at a time, from left to right. When and if any argument evaluates to true, "or" returns true immediately, without evaluating any more arguments.

For Example:

(or)        ;; ==> #f
(or #t)     ;; ==> #t
(or #f)     ;; ==> #f
(or #t #t)  ;; ==> #t
(or #f #t)  ;; ==> #t
(or #f #f)  ;; ==> #f

(define (foo) (begin (display "foo ") #f)) ;; ==> foo
(define (bar) (begin (display "bar ") #t)) ;; ==> bar

(or (bar) (foo))                           ;; ==> bar #t
                                           ;; It didn't print "foo".

output-port?

Type:

Procedure.

Operation:

Test whether the argument is an output port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an output port. Otherwise, returns #f. Note that once an output port has been closed, it is no longer a port in the sense of the R5 report, because it cannot accept characters on demand.

For Example:

(define foo (open-output-file "Some.output.file"))  ;; ==> foo
(output-port? foo)                                  ;; ==> #t
(close-output-port foo)                             ;; ==> #t
(output-port? foo)                                  ;; ==> #f

(output-port? 42)                                   ;; ==> #f

pair?

Type:

Procedure.

Operation:

Test whether the argument is a pair.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a pair. Otherwise, returns #f.

For Example:

(pair? '(1 . 2))    ;; ==> #t
(pair? (list 1 2))  ;; ==> #t
(pair? '())         ;; ==> #f
(pair? 42)          ;; ==> #f

peek-char

Type:

Procedure.

Operation:

Obtain the next character available from an input port -- or hang waiting if none is available -- without doing anything to cause the port to advance to to the next character.

Arguments:

At most one, an input port.

Side Effects:

None.

Returned Value:

A character or an end-of file object: If there is an argument, obtain the result from that port. If there is no argument, obtain the result from the current input port. The procedure may not return immediately, if the port is to an interactive device, such as the keyboard, which has no character ready.

For Example:

;; Suppose that foo is an input port just opened to
;; a text file containing just one character, "a":

(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a
(peek-char foo)  ;; ==> #\a

(read-char foo)  ;; ==> #\a

(peek-char foo)  ;; ==> #<End of File>

port?

Type:

Procedure.

Operation:

Test whether the argument is a port.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a port. Otherwise, returns #f. Note that once a port has been closed, it is no longer a port as Scheme uses the term, because it can neither accept nor provide characters on demand.

For Example:

(define foo (open-output-file "Some.output.file"))         ;; ==> foo
(define bar (open-input-file "Some.existing.input.file"))  ;; ==> bar
(port? foo)              ;; ==> #t
(port? bar)              ;; ==> #t
(close-output-port foo)  ;; ==> #t
(close-input-port bar)   ;; ==> #t
(port? foo)              ;; ==> #f
(port? bar)              ;; ==> #f
(port? 42)               ;; ==> #f

positive?

Type:

Procedure.

Operation:

Test whether a number is positive.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is positive. Otherwise, returns #f.

For Example:

(positive? 0)   ;; ==> #f
(positive? 1)   ;; ==> #t
(positive? -1)  ;; ==> #f

procedure?

Type:

Procedure.

Operation:

Test whether a Scheme object is a procedure.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a procedure. Returns #f otherwise.

Macros and special forms are not procedures.

For Example:

(procedure? +)                     ;; ==> #t
(procedure? (lambda (x) (+ x 1)))  ;; ==> #t
(procedure? lambda)                ;; ==> #f
(procedure? let)                   ;; ==> #f

quasiquote

Additional Syntax:

Backquote: `<whatever> is equivalent to (quasiquote <whatever>).

Type:

Operation:

Instantiate literal data with an option for partial evaluation using "unquote" or "unquote-splicing". Thus, (quasiquote <whatever>) evaluates to <whatever>, but if any subexpression of <whatever> begins with either "unquote" or "unquote-splicing", or with their respective syntactic equivalents, "," or ",@", then that subexpression will be evaluated according to the rules for unquote or unquote-splicing before being inserted into <whatever>.

The macros "quasiquote", "unquote" and "unquote-splicing" may be nested within <whatever>: Starting with a nesting level of zero at the the left end of <whatever>, each "quasiquote" increases the nesting level by one, and each "unquote" or "unquote-splicing" reduces it by one, and normal evaluation occurs only when the nesting level thus determined is zero.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

The argument, with no further evaluation except as directed by "unquote" or by "unquote-splicing".

For Example:

(define foo "A string named foo")  ;; ==> foo
(quasiquote foo)                   ;; ==> foo
`foo                               ;; ==> foo
(quasiquote ,foo)                  ;; ==> "A string named foo."
`,foo                              ;; ==> "A string named foo."

(define a 42)         ;; ==> a
(quasiquote (+ 2 a))  ;; ==> (+ 2 a)
`(+ 2 a)              ;; ==> (+ 2 a)
`(+ 2 ,a)             ;; ==> (+ 2 42)

(define b (list 27 18 28))  ;; ==> b
`(+ 2 b)                    ;; ==> (+ 2 b)
`(+ 2 ,b)                   ;; ==> (+ 2 (27 18 28))  ;; Doesn't add up ...
`(+ 2 ,@b)                  ;; ==> (+ 2 27 18 2)

quote

Additional Syntax:

Quote: '<whatever> is equivalent to (quote <whatever>).

Type:

Operation:

Instantiate literal data; that is, (quote <whatever>) evaluates to <whatever>.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

The argument, without further evaluation.

For Example:

(quote foo)      ;; ==> foo
'foo             ;; ==> foo
(quote (+ 2 2))  ;; ==> (+ 2 2)
'(+ 2 2)         ;; ==> (+ 2 2)

quotient

Type:

Procedure.

Operation:

Mathematical quotient.

Arguments:

Two integers.

Side Effects:

None.

Returned Value:

An integer: The quotient of the first number by the second.

For Example:

(quotient 13 4)    ;; ==> 3
(quotient -13 4)   ;; ==> -3
(quotient 13 -4)   ;; ==> -3
(quotient -13 -4)  ;; ==> 3

rationalize

Type:

Procedure.

Operation:

Obtain the simplest rational number differing from the first argument by no more than the second argument. One rational is simpler than another if, when both are expressed in lowest terms, the absolute value of the numerator of the first is less than or equal to the absolute value of the numerator of the second and the absolute value of the denominator of the first is less than or equal to the absolute value of the denominator of the second, and at least one of the inequalities is strict.

Arguments:

Two real numbers.

Side Effects:

None.

Returned Value:

The simplest rational number differing from the first argument by no more than the second argument. Wraith Scheme may not be able to express the returned value as a fraction, because of the limited range of 64-bit integers.

For Example:

(rationalize .3 1/10)    ;; ==> #i1/3
(rationalize .3 1/1000)  ;; ==> #i3/10
(rationalize .3 0)       ;; ==> #i5404319552844595/18014398509481984
(rationalize 3/10 0)     ;; ==> 3/10
(rationalize .3e200 0)   ;; ==> 3.0000000000000001e199

rational?

Type:

Procedure.

Operation:

Test whether the argument is a rational number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a rational number. Otherwise, returns #f.

For Example:

(rational? #t)        ;; ==> #f
(rational? 1)         ;; ==> #t
(rational? 1.5)       ;; ==> #t
(rational? (sqrt 2))  ;; ==> #t
(rational? +i)        ;; ==> #f
(rational? (/ 1 0))   ;; ==> #f  (It's an inf.)
(rational? (/ 0 0))   ;; ==> #f  (It's a nan.)

;; Note that in Wraith Scheme

(sqrt 2)              ;; ==> 1.4142135623730951

;; which is 14142135623730951/10000000000000000
;; and thus is rational.

read

Type:

Procedure.

Operation:

Read one Scheme object from a port. What is read must "parse"; that is, it must be a valid external representation of a Scheme object, but "read" does not evaluate it.

Arguments:

At most one: If present, an input port.

Side Effects:

None.

Returned Value:

A Scheme object: If an argument is present, returns the next Scheme object available from that port, or an end-of-file object; if not, returns the next Scheme object available at the current input port, or an end-of-file object.

For Example:

;; Suppose "foo" is a newly-opened input port to a file containing
;; the text "(+ 2 2) No more".

(read foo)  ;; ==> (+ 2 2)
(read foo)  ;; ==> No
(read foo)  ;; ==> more
(read foo)  ;; ==> <End of File>

read-char

Type:

Procedure.

Operation:

Obtain the next character available from an input port -- or hang waiting if none is available.

Arguments:

At most one, an input port.

Side Effects:

Reads from a port.

Returned Value:

For Example:

;; Suppose that foo is an input port just opened to
;; a text file containing the text "abc":

(read-char foo)  ;; ==> #\a
(read-char foo)  ;; ==> #\b
(read-char foo)  ;; ==> #\c
(read-char foo)  ;; ==> #<End of File>
(read-char foo)  ;; ==> #<End of File>
(read-char foo)  ;; ==> #<End of File>

real-part

Type:

Procedure.

Operation:

Obtain the real part of a number.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The real part of the number.

For Example:

(real-part 1)     ;; ==> 1
(real-part +i)    ;; ==> 0
(real-part 1.+i)  ;; ==> 1.

real?

Type:

Procedure.

Operation:

Test whether the argument is a real number.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a real number. Otherwise, returns #f.

For Example:

(real? #t)        ;; ==> #f
(real? 1)         ;; ==> #t
(real? 1.5)       ;; ==> #t
(real? (sqrt 2))  ;; ==> #t
(real? +i)        ;; ==> #f
(real? (/ 1 0))   ;; ==> #f  (It's an inf.)
(real? (/ 0 0))   ;; ==> #f  (It's a nan.)

remainder

Type:

Procedure.

Operation:

Mathematical remainder.

Arguments:

Two integers.

Side Effects:

None.

Returned Value:

An integer: The remainder of the first number when divided (in the sense of "quotient") by the second.

For Example:

(remainder 13 4)    ;; ==> 1
(remainder -13 4)   ;; ==> -1
(remainder 13 -4)   ;; ==> 1
(remainder -13 -4)  ;; ==> -1

reverse

Type:

Procedure.

Operation:

Reverse a proper list.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

A list: Returns a newly-created list whose elements are the elements of the argument in reverse order.

For Example:

(reverse '())           ;; ==> ()
(reverse (list 1 2 3))  ;; ==> (3 2 1)

round

Type:

Procedure.

Operation:

Arithmetic round to nearest integer.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The closest integer to the argument, rounding to even when the argument is half way between two integers.

For Example:

(round 3.49) ;; ==> 3.
(round 3.51) ;; ==> 4.
(round 3.5)  ;; ==> 4.
(round 2.5)  ;; ==> 2.

scheme-report-environment

Type:

Procedure.

Operation:

Return a Scheme environment which contains the bindings in the null environment, plus all other bindings that are either required by the R5 report or are optional and are supported by Wraith Scheme.

Arguments:

One, which must be the exact integer 5.

Side Effects:

None.

Returned Value:

The Scheme-report environment of Wraith Scheme.

For Example:

(eval '(+ 2 2) (scheme-report-environment 5))
4

set!

Type:

Operation:

Change the value or binding of an identifier that already has a value or binding.

Arguments:

Two: The first, an identifier; the second, any Scheme object.

Side Effects:

Changes a pre-existing variable value or binding; informally, changes the value of a variable. The second argument becomes the value or binding of the first, in whatever environment the "set!" occurred in.

In the top-level environment, "define" may also be used to give new values or bindings to identifiers; however, in other environments, only "set!" has this capability.

Returned Value:

For Example:

;;  Suppose that "a" has never had a value or binding.

(set! a 42)    ;; ==> <error>  ;;  No value to change.

(define a 23)  ;; ==> a
a              ;; ==> 23
(set! a 42)    ;; ==> #t
a              ;; ==> 42

set-car!

Type:

Procedure.

Operation:

Change the car of a pair to a new value.

Arguments:

Two: The first, a pair; the second, any Scheme object, to become the new car.

Side Effects:

Changes the pair.

Returned Value:

For Example:

(define a (cons 1 2))  ;; ==> a
a                      ;; ==> (1 . 2)
(set-car! a 42)        ;; ==> #t
a                      ;; ==> (42 . 2)

set-cdr!

Type:

Procedure.

Operation:

Change the cdr of a pair to a new value.

Arguments:

Two: the first, a pair; the second, any Scheme object, to become the new cdr.

Side Effects:

Changes the pair.

Returned Value:

For Example:

(define a (cons 1 2))  ;; ==> a
a                      ;; ==> (1 . 2)
(set-cdr! a 42)        ;; ==> #t
a                      ;; ==> (1 . 42)

sin

Type:

Procedure.

Operation:

Mathematical sine.

Arguments:

One number. Real numbers are taken to be angles in radians.

Side Effects:

None.

Returned Value:

The sine of the argument.

For Example:

(sin 0)                   ;; ==> 0
(sin 1.5707963267948966)  ;; ==> 1.
(sin 0.7853981633974483)  ;; ==> 0.7071067811865475
(sin +i)                  ;; ==> 1.1752011936438014i

sqrt

Type:

Procedure.

Operation:

Mathematical square root.

Arguments:

One number.

Side Effects:

None.

Returned Value:

The square root of the argument.

For Example:

(sqrt 0)    ;; ==> 0
(sqrt 2.5)  ;; ==> 1.5811388300841898
(sqrt 4)    ;; ==> 2
(sqrt -1)   ;; ==> +i
(sqrt +i)   ;; ==> 0.7071067811865476+0.7071067811865475i

string

Type:

Procedure.

Operation:

Create a string containing a given list of characters.

Arguments:

Zero or more characters.

Side Effects:

None.

Returned Value:

A string containing the characters that were the arguments, in the same order

For Example:

(string)                ;; ==> ""
(string #\C #\a #\t)    ;; ==> "Cat"

string->list

Type:

Procedure.

Operation:

Make a list of the characters in a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A list: Returns a list of the characters in the argument, in order.

For Example:

(string->list "Cat")  ;; ==> (#\C #\a #\t)

string->number

Type:

Procedure.

Operation:

Read the contents of a string as a number in a particular radix.

Arguments:

One or two: The first, the string to be read, the second an exact integer, either 2, 8, 10 or 16, corresponding to the radix in which the number is to be represented. If there is no second argument, the radix is taken to be 10.

Side Effects:

None.

Returned Value:

A number: Returns a number whose external representation in the given base is the given string.

For Example:

(string->number "123")            ;; ==> 123
(string->number "1001" 2)         ;; ==> 9
(string->number "1001" 8)         ;; ==> 513
(string->number "1001" 10)        ;; ==> 1001
(string->number "1001")           ;; ==> 1001
(string->number "1001" 16)        ;; ==> 4097
(string->number "#i-123###.e23")  ;; ==> -1.2300000000000001e28

string->symbol

Type:

Procedure.

Operation:

Create a Scheme identifier from the letters of the argument.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A symbol: Returns a Scheme identifier whose characters are the same as those in the given string, in the same order.

For Example:

(string->symbol "Cat")  ;; ==> Cat  ;; Note the capitalization.

string-append

Type:

Procedure.

Operation:

Concatenate strings.

Arguments:

One or more strings.

Side Effects:

None.

Returned Value:

A string: Returns a string whose characters are the characters of the arguments, in order.

For Example:

(string-append "I " "see " "the " "cat.")
    ;; ==> "I see the cat."

string-ci<=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic less than or equal to.

Lexicographic comparison compares strings character-by-character and defines their ordering based on the ASCII integers that represent the first characters at which they differ, if any. If one string ends before a difference occurs, the longer string is taken to be greater. If both strings end with no difference, the strings are taken to be equal.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than or equal to the second. Otherwise, returns #f.

For Example:

(string-ci<=? "aa" "aardvark")        ;; ==> #t
(string-ci<=? "Aa" "aardvark")        ;; ==> #t
(string-ci<=? "aa" "Aardvark")        ;; ==> #t
(string-ci<=? "aa" "pahoehoe")        ;; ==> #t
(string-ci<=? "pahoehoe" "aa")        ;; ==> #f
(string-ci<=? "aardvark" "aardvark")  ;; ==> #t

string-ci<?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic less than.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than the second. Otherwise, returns #f.

For Example:

(string-ci<? "aa" "aardvark")        ;; ==> #t
(string-ci<? "Aa" "aardvark")        ;; ==> #t
(string-ci<? "aa" "Aardvark")        ;; ==> #t
(string-ci<? "aa" "pahoehoe")        ;; ==> #t
(string-ci<? "pahoehoe" "aa")        ;; ==> #f
(string-ci<? "aardvark" "aardvark")  ;; ==> #f

string-ci=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic equality.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically equality the second. Otherwise, returns #f.

For Example:

(string-ci=? "aa" "aardvark")        ;; ==> #f
(string-ci=? "Aa" "aardvark")        ;; ==> #f
(string-ci=? "aa" "Aardvark")        ;; ==> #f
(string-ci=? "aa" "pahoehoe")        ;; ==> #f
(string-ci=? "aardvark" "aardvark")  ;; ==> #t
(string-ci=? "aardvark" "AARDVARK")  ;; ==> #t

string-ci>=?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic greater than or equal to.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than or equal to the second. Otherwise, returns #f.

For Example:

(string-ci>=? "aa" "aardvark")        ;; ==> #f
(string-ci>=? "Aa" "aardvark")        ;; ==> #f
(string-ci>=? "aa" "Aardvark")        ;; ==> #f
(string-ci>=? "aa" "pahoehoe")        ;; ==> #f
(string-ci>=? "pahoehoe" "aa")        ;; ==> #t
(string-ci>=? "aardvark" "aardvark")  ;; ==> #t

string-ci>?

Type:

Procedure.

Operation:

Convert two strings to lower case and test for lexicographic greater than.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than the second. Otherwise, returns #f.

For Example:

(string-ci>? "aa" "aardvark")        ;; ==> #f
(string-ci>? "Aa" "aardvark")        ;; ==> #f
(string-ci>? "aa" "Aardvark")        ;; ==> #f
(string-ci>? "aa" "pahoehoe")        ;; ==> #f
(string-ci>? "pahoehoe" "aa")        ;; ==> #t
(string-ci>? "aardvark" "aardvark")  ;; ==> #f

string-copy

Type:

Procedure.

Operation:

Copy a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

A string: Returns a newly-allocated copy of the argument.

For Example:

(string-copy "Cat")  ;; ==> "Cat"

string-fill!

Type:

Procedure.

Operation:

Fill a string with a given character.

Arguments:

Two: The first a string, the second the character to fill with.

Side Effects:

Alters the string.

Returned Value:

For Example:

(define a (make-string 2))  ;; ==> a
a                           ;; ==> "  "
(string-fill! a #\x)        ;; ==> #t
a                           ;; ==> "xx"

string-length

Type:

Procedure.

Operation:

Determine the length of a string.

Arguments:

One string.

Side Effects:

None.

Returned Value:

An integer: Returns the number of characters in the argument.

For Example:

(string-length "Cat")  ;; ==> 3

string-ref

Type:

Procedure.

Operation:

Get a specific character from a string.

Arguments:

Two: The first a string, the second a nonnegative integer, taken as the zero-based index of the character to return.

Side Effects:

None.

Returned Value:

A character: Returns the first argument's character that was at position N from the start of the string, N being the second argument. A value of zero for N returns the first character in the string.

For Example:

(string-ref "Cat" 0)  ;; ==> #\C
(string-ref "Cat" 1)  ;; ==> #\a
(string-ref "Cat" 2)  ;; ==> #\t

string-set!

Type:

Procedure.

Operation:

Set one character in a string to a new value.

Arguments:

Three: The first a string, the second a nonnegative integer, taken as the zero-based index of the character to change, the third the new character.

Side Effects:

Changes the string.

Returned Value:

For Example:

(define a (make-string 3))  ;; ==> a
a                           ;; ==> "   "
(string-set! a 0 #\C)       ;; ==> #t
a                           ;; ==> "C  "
(string-set! a 1 #\a)       ;; ==> #t
a                           ;; ==> "Ca "
(string-set! a 2 #\t)       ;; ==> #t
a                           ;; ==> "Cat"

string<=?

Type:

Procedure.

Operation:

Test two strings for lexicographic less than or equal to.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than or equal to the second. Otherwise, returns #f.

For Example:

(string<=? "aa" "aardvark")        ;; ==> #t
(string<=? "Aa" "aardvark")        ;; ==> #t
(string<=? "aa" "Aardvark")        ;; ==> #f
(string<=? "aa" "pahoehoe")        ;; ==> #t
(string<=? "aardvark" "aardvark")  ;; ==> #t

string<?

Type:

Procedure.

Operation:

Test two strings for lexicographic less than.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically less than the second. Otherwise, returns #f.

For Example:

(string<? "aa" "aardvark")        ;; ==> #t
(string<? "Aa" "aardvark")        ;; ==> #t
(string<? "aa" "Aardvark")        ;; ==> #f
(string<? "aa" "pahoehoe")        ;; ==> #t
(string<? "aardvark" "aardvark")  ;; ==> #f

string=?

Type:

Procedure.

Operation:

Test two strings for lexicographic equality.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically equality the second. Otherwise, returns #f.

For Example:

(string=? "aa" "aardvark")        ;; ==> #f
(string=? "Aa" "aardvark")        ;; ==> #f
(string=? "aa" "Aardvark")        ;; ==> #f
(string=? "aa" "pahoehoe")        ;; ==> #f
(string=? "aardvark" "aardvark")  ;; ==> #t
(string=? "aardvark" "AARDVARK")  ;; ==> #f

string>=?

Type:

Procedure.

Operation:

Test two strings for lexicographic greater than or equal to.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than or equal to the second. Otherwise, returns #f.

For Example:

(string>=? "aa" "aardvark")        ;; ==> #f
(string>=? "Aa" "aardvark")        ;; ==> #f
(string>=? "aa" "Aardvark")        ;; ==> #t
(string>=? "aa" "pahoehoe")        ;; ==> #f
(string>=? "pahoehoe" "aa")        ;; ==> #t
(string>=? "aardvark" "aardvark")  ;; ==> #t

string>?

Type:

Procedure.

Operation:

Test two strings for lexicographic greater than.

Arguments:

Two strings.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the first string is lexicographically greater than the second. Otherwise, returns #f.

For Example:

(string>? "aa" "aardvark")        ;; ==> #f
(string>? "Aa" "aardvark")        ;; ==> #f
(string>? "aa" "Aardvark")        ;; ==> #t
(string>? "aa" "pahoehoe")        ;; ==> #f
(string>? "pahoehoe" "aa")        ;; ==> #t
(string>? "aardvark" "aardvark")  ;; ==> #f

string?

Type:

Procedure.

Operation:

Test whether a Scheme object is a string.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a string. Otherwise, returns #f.

For Example:

(string? #t)     ;; ==> #f
(string? 'Cat)   ;; ==> #f
(string? "Cat")  ;; ==> #t

substring

Type:

Procedure.

Operation:

Make a copy of part of a given string.

Arguments:

Three: The first a string, the second and third non-negative integers, respectively taken to be the zero-based indexes into the given string to the position of the first character of the intended substring, and to the position just past the last character of the intended substring. If the second and third arguments are equal, the substring indicated has zero length, and contains no characters.

Side Effects:

None.

Returned Value:

A string: Returns a newly-allocated copy of the substring described in the "Arguments" section above.

For Example:

(substring "Cat" 0 0)               ;; ==> ""
(substring "The cat sees me." 4 7)  ;; ==> "cat"

symbol->string

Type:

Procedure.

Operation:

Make a string containing the letters of a given symbol.

Arguments:

One symbol.

Side Effects:

None.

Returned Value:

An immutable string: Returns a string with the same characters as the argument, in the same order.

For Example:

(symbol->string 'foo)  ;; ==> "foo"

symbol?

Type:

Procedure.

Operation:

Test whether a Scheme object is a symbol.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a symbol. Otherwise, returns #f.

For Example:

(symbol? #t)     ;; ==> #f
(symbol? "foo")  ;; ==> #f
(symbol? 'foo)   ;; ==> #t

syntax-rules

Type:

Operation:

Primitive for construction of hygienic macros.

Arguments:

The form of a macro call of "syntax-rules" should match the grammar for <transformer spec> given in section 4.3.2 of the "R5" report.

Side Effects:

None.

Returned Value:

A procedure, suitable for use as the transformer of an hygienic macro.

For Example:

Strictly, there are no examples: The formal definition of Scheme mentions "syntax-rules" only in the context of the syntax required for the standard implementation of hygienic macros. There is no specification of what sort of entity "syntax-rules" should be, or even of whether or not there should be a Scheme object associated with that identifier. There is also no specification of what behavior should obtain if "syntax-rules" is used in some other context, such as

(syntax-rules foo bar baz)

I mention "syntax-rules" here only because its use in the "R5" report resembles the use of a procedure or special form: You might like to know what happens if you try to use it that way. The answer is, that if the call to "syntax-rules" matches the grammar for <transformer spec> given in section 4.3.2 of the "R5" report, you will get a procedure suitable for use as the transformer of an hygienic macro. If not, you will probably get some form of error message. For example, noting that hex values may vary:

(syntax-rules foo bar baz)  ;; ==> 

0000000000000003-0000020002df8028: Symbol -- Not a Car (Kitten 0)
Problem: Implementation error: Tried to take the car of a non-pair.
  Last lambda called (which may have returned) has never been named.
  (Resetting)
Top-level loop ...

The reason for this behavior is an implementation detail of Wraith Scheme: In Wraith Scheme, "syntax-rules" itself does not do any tests to make sure that it is being called with the correct grammar. All appropriate syntax checking is done by forms "define-syntax", "let-syntax", and "letrec-syntax", which use the symbol "syntax-rules" as part of their implementation. Thus in:

(syntax-rules foo bar baz)

the macro call is obviously not a <transformer spec>, and the error message noted occurs when the macro "syntax-rules" stumbles because of that failing. On the other hand, when Wraith Scheme encounters the form:

(define-syntax foo (syntax-rules foo bar baz))

it produces a more useful error report:

(define-syntax foo (syntax-rules foo bar baz)) "syntax-rules" used as shown, but the second argument is not a transformer specification. The problems include: Problem: The second item in that argument is not a list of identifiers. (Resetting) Top-level loop ...

If you wish to experiment with "syntax-rules" all by itself, go ahead, but beware of mysterious failures and puzzling error messages when you use it in any other context than an instance of "define-syntax", "let-syntax", or "letrec-syntax".

tan

Type:

Procedure.

Operation:

Mathematical tangent.

Arguments:

One number. Real numbers are taken angles in radians.

Side Effects:

None.

Returned Value:

The tangent of the argument.

For Example:

(tan 0)                   ;; ==> 0
(tan 1.5707963267948966)  ;; ==> 16331239353195370.
(tan 3)                   ;; ==> -0.1425465430742778
(tan +i)                  ;; ==> 0.7615941559557649i

transcript-off

Type:

Procedure.

Operation:

If a transcript file is in use, stop using it and close the port to the file. If no transcript is in use, "transcript-off" does nothing.

Arguments:

None.

Side Effects:

Closes any open transcript file.

Returned Value:

For Example:

(transcript-off)  ;; ==> #t

transcript-on

Type:

Procedure.

Also see the related enhancement procedure e::transcript-on-append.

Operation:

Open a transcript file and start using it.

Wraith Scheme allows only one transcript file to be open at a time. If a transcript file is already in use when "transcript-on" is called, Wraith Scheme will close the old transcript file before starting to use the new one. Any previous content of the transcript file will be lost; that is, the file is not opened for append.

Transcript files record everything that appeared in the Wraith Scheme Main Display Panel while the transcript file was in use, whether keyed in by the user or output by Wraith Scheme.

Procedure transcript-off closes any transcript file in use.

Arguments:

At most one: If present, a string containing a Unix-style pathname to a file to be used as a transcript file. If there is no argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain a pathname.

Side Effects:

Opens a new transcript file, and closes any transcript file that was already in use.

Returned Value:

For Example:

(transcript-on "MyTranscript.text")  ;; Opens the file
    ;; ==> #t
(transcript-on)  ;; Wraith Scheme uses the Dialog Panel
    ;; ==> #t

truncate

Type:

Procedure.

Operation:

Arithmetic truncation toward zero.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

An integer: The integer closest to the argument whose absolute value is not larger than the absolute value of the argument.

For Example:

(truncate 1)        ;; ==> 1
(truncate 1.00001)  ;; ==> 1.
(truncate 1.9999)   ;; ==> 1.
(truncate 0.9999)   ;; ==> 0.
(truncate -1)       ;; ==> -1
(truncate -1.00001) ;; ==> -1.
(truncate -1.9999)  ;; ==> -1.
(truncate -0.9999)  ;; ==> 0.

unquote

Additional Syntax:

Comma: ,<whatever> is equivalent to (unquote <whatever>).

Type:

Operation:

Reduce the level of nesting by one within a quasiquoted expression, (quasiquote <whatever>). When that level is zero, the evaluation that was inhibited by "quasiquote" resumes, and the argument of "unquote" is inserted into <whatever>.

The macros "quasiquote", "unquote" and "unquote-splicing" may be nested within <whatever>: Starting with a nesting level of zero at the the left end of <whatever>, each "quasiquote" increases the nesting level by one, each "unquote" or "unquote-splicing" reduces it by one, and normal evaluation occurs only when the nesting level thus determined is zero.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A Scheme object: Returns the argument, either evaluated or not, according to whether the nesting level, defined in the "Operation" section above, is zero or not. In either case the returned value is spliced into the enclosing quasiquoted expression.

For Example:

(define foo "A string named foo")  ;; ==> foo
(quasiquote foo)                   ;; ==> foo
`foo                               ;; ==> foo
(quasiquote ,foo)                  ;; ==> "A string named foo."
`,foo                              ;; ==> "A string named foo."

(define a 42)         ;; ==> a
(quasiquote (+ 2 a))  ;; ==> (+ 2 a)
`(+ 2 a)              ;; ==> (+ 2 a)
`(+ 2 ,a)             ;; ==> (+ 2 42)

(define b (list 27 18 28))  ;; ==> b
`(+ 2 b)                    ;; ==> (+ 2 b)
`(+ 2 ,b)                   ;; ==> (+ 2 (27 18 28))  ;; Doesn't add up ...
`(+ 2 ,@b)                  ;; ==> (+ 2 27 18 2)

unquote-splicing

Additional Syntax:

Comma and at-sign: ,@<whatever> is equivalent to (unquote-spicing <whatever>).

Type:

c::block
c::release-block
e::block-any-binding
e::block-symbol-binding
c::set-blocked-binding!

Operation:

The macros "quasiquote", "unquote" and "unquote-splicing" may be nested within <whatever>: Starting with a nesting level of zero at the the left end of <whatever>, each "quasiquote" increases the nesting level by one, each "unquote" or "unquote-splicing" reduces it by one, and normal evaluation occurs only when the nesting level thus determined is zero.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

One or more Scheme objects: If the nesting level, defined in the "Operation" section above, is zero, returns the elements of the argument; if not, returns the argument, which in either case is spliced into the enclosing quasiquoted expression.

For Example:

(define foo "A string named foo")  ;; ==> foo
(quasiquote foo)                   ;; ==> foo
`foo                               ;; ==> foo
(quasiquote ,foo)                  ;; ==> "A string named foo."
`,foo                              ;; ==> "A string named foo."

(define a 42)         ;; ==> a
(quasiquote (+ 2 a))  ;; ==> (+ 2 a)
`(+ 2 a)              ;; ==> (+ 2 a)
`(+ 2 ,a)             ;; ==> (+ 2 42)

(define b (list 27 18 28))  ;; ==> b
`(+ 2 b)                    ;; ==> (+ 2 b)
`(+ 2 ,b)                   ;; ==> (+ 2 (27 18 28))  ;; Doesn't add up ...
`(+ 2 ,@b)                  ;; ==> (+ 2 27 18 2)

values

Type:

Procedure.

Operation:

In the abstract sense, "values" modifies the continuation (in the first sense discussed herein) when it is called, so that the continuation is set up to deliver multiple values to a Scheme procedure -- the values being those provided as arguments to "values" itself, in the order given. Such a continuation is only useful when the next thing following those values is a procedure call which can accept those values as its arguments.

In practical terms, "values" provides a mechanism for returning multiple values from a procedure. Although it is technically a procedure in its own right, it is perhaps most useful to think of it as a special syntactic form, used at the end of a procedure, to return values. In that sense, "values" is analogous to the "return" statement in the C programming language, except that C's "return" can return only one value, whereas "values" can return many.

Arguments:

One or more Scheme objects.

Side Effects:

None.

Returned Value:

A "Multiple Values Return" object, which can only be interpreted in the continuation established by "call-with-values". Other Scheme implementations likely handle the return from "values" differently.

For Example:

;; Here is a fancy way to add up the integers
;; from one through ten:  This example passes
;; the list returned by "values" to "+", just
;; as if you had entered
;;
;; (+ 1 2 3 4 5 6 7 8 9 10)

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  +)  ;; ==> 55

;; We could equally well just list the numbers:

(call-with-values
  (lambda () (values 1 2 3 4 5 6 7 8 9 10))
  list)

    ;; ==> (1 2 3 4 5 6 7 8 9 10)

;; In the top-level loop:

(values 1 2 3 4 5 6 7 8 9 10)
    ;; ==> #<Multiple Values Return>
    ;;     List of values: (1 2 3 4 5 6 7 8 9 10)

vector

Type:

Procedure.

Operation:

Make a vector.

Arguments:

Zero or more Scheme objects.

Side Effects:

None.

Returned Value:

A vector of the arguments, in order.

For Example:

(vector)        ;; ==> #()
(vector 1 2 3)  ;; ==> #(1 2 3)

vector->list

Type:

Procedure.

Operation:

Make a list of the elements in a vector.

Arguments:

One vector.

Side Effects:

None.

Returned Value:

A list: Returns a newly-allocated list whose elements are the elements of the argument, in the same order.

For Example:

(define a (make-vector 3))   ;; ==> a
a                            ;; ==> #(() () ())
(define b (vector->list a))  ;; ==> b
b                            ;; ==> (() () ())
(vector-set! a 2 4)          ;; ==> #t
a                            ;; ==> #(() () 4)
b                            ;; ==> (() () ())
                             ;;      b does not share memory with a.
(vector->list a)             ;; ==> (() () 4)  ;;  New copy of a.

vector-fill!

Type:

Procedure.

Operation:

Fill every element of a vector with the same Scheme object.

Arguments:

Two: The first a vector to be filled, the second a Scheme object to fill it with.

Side Effects:

Modifies the first argument.

Returned Value:

For Example:

(define cat (make-vector 3))  ;; ==> cat
(vector-fill! cat 'meow)      ;; ==> #t
cat                           ;; ==> #(meow meow meow)

vector-length

Type:

Procedure.

Operation:

Obtain the length of a vector.

Arguments:

One vector.

Side Effects:

None.

Returned Value:

An integer: Returns the length of the argument.

For Example:

(vector-length '#())                ;; ==> 0
(vector-length '#(meow meow meow))  ;; ==> 3

vector-ref

Type:

Procedure.

Operation:

Obtain a specified element of a vector.

Arguments:

Two: The first a vector, the second a non-negative integer, taken to be the zero-based index of the argument requested.

Side Effects:

None.

Returned Value:

A Scheme object: Returns the element of the first argument that is at the zero-based index which is the second argument.

For Example:

(vector-ref '#(c a t) 0)  ;; ==> #\c  
(vector-ref '#(c a t) 1)  ;; ==> #\a  
(vector-ref '#(c a t) 2)  ;; ==> #\t

vector-set!

Type:

Procedure.

Operation:

Set one element of a vector to a new value.

Arguments:

Three: The first a vector, the second a nonnegative integer, taken as the zero-based index of the element to change, the third the new element.

Side Effects:

Changes the vector.

Returned Value:

For Example:

(define a (make-vector 3))  ;; ==> a
a                           ;; ==> #(() () ())
(vector-set! a 0 'c)        ;; ==> #t
a                           ;; ==> #(c () ())
(vector-set! a 1 'a)        ;; ==> #t
a                           ;; ==> #(c a ())
(vector-set! a 2 't)        ;; ==> #t
a                           ;; ==> #(c a t)

vector?

Type:

Procedure.

Operation:

Test whether a Scheme object is a vector.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a vector. Otherwise, returns #f.

For Example:

(vector? #t)                           ;; ==> #f
(vector? (make-vector 3))              ;; ==> #t
(vector? (list->vector (list 1 2 3)))  ;; ==> #t

with-input-from-file

Type:

Procedure.

Operation:

Temporarily change the current input port to a port to a file, and do something while the change is in effect.

Arguments:

One or two: The last a procedure of no arguments, to be called while the changed current input port is in effect. If there are two arguments, the first is a string containing a Unix-style pathname to a file: Wraith Scheme will open an input port to this file and make that port the current input port while the procedure is run. If there is only one argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain a path to the file to be used.

Side Effects:

Temporarily changes the current input port, plus whatever side effects result from the call to the given procedure.

Returned Value:

For Example:

;;  Suppose "Foo" is a file containing the text "abc".

(with-input-from-file "Foo"
  (lambda ()
    (display (read-char))
    (newline)
    (display (read-char))
    (newline)
    (display (read-char))
    (newline)))  ;; ==>
                 ;; a
                 ;; b
                 ;; c
                 ;; #t

with-output-to-file

Type:

Procedure.

Operation:

Temporarily change the current output port to a port to a file, and do something while the change is in effect.

Arguments:

One or two: The last a procedure of no arguments, to be called while the changed current output port is in effect. If there are two arguments, the first is a string containing a Unix-style pathname to a file: Wraith Scheme will open an output port to this file and make that port the current output port while the procedure is run. If there is only one argument, Wraith Scheme will use the Wraith Scheme Dialog Panel to obtain a path to the file to be used.

Side Effects:

None.

Returned Value:

Temporarily changes the current output port, plus whatever side effects result from the call to the given procedure.

For Example:

(with-output-to-file "Foo"
  (lambda ()
    (write-char #\a)
    (newline)
    (write-char #\b)
    (newline)
    (write-char #\c)
    (newline)))  ;; Writes the text "abc" to file "Foo",
                 ;;   one character to a line.
                 ;; ==> #t

write

Type:

Procedure.

Operation:

Write a Scheme object to a port.

Arguments:

One or two: The first, a Scheme object to be written; the second, if present, an output port to write to. If there is no second argument, the object will be written to the current output port.

Side Effects:

Writes something, somewhere.

Returned Value:

For Example:

;;  Suppose that "my-port" is an output port associated with
;;  file "MyFile.s".

(write (list 1 2 3) my-port)  ;; Writes (1 2 3) to "MyFile.s".
                              ;; ==> #t

write-char

Type:

Procedure.

Operation:

Write a character to a port.

Arguments:

One or two: The first, a character to be written; the second, if present, an output port to write to. If there is no second argument, the character will be written to the current output port.

Side Effects:

Writes a character somewhere.

Returned Value:

For Example:

(with-output-to-file "Foo"
  (lambda ()
    (write-char #\a)
    (write-char #\b)
    (write-char #\c)))  ;; Writes the text "abc" to file "Foo".
                        ;; ==> #t

zero?

Type:

Procedure.

Operation:

Test whether a number is zero.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is zero; the test is done using the Scheme predicate "=". Otherwise, returns #f.

For Example:

(zero? 1)     ;; ==> #f
(zero? 0)     ;; ==> #t
(zero? #i0)   ;; ==> #t
(zero? 0/42)  ;; ==> #t
(zero? 0i)    ;; ==> #t

Enhancement Procedures:
For General Use

e::active-room

Type:

Procedure.

Operation:

Find the number of bytes free in the current Wraith Scheme active memory generation.

Rationale, Explanation, Excuses:

Simple storage-instrumentation procedure: Just returns a number. Contrast with "e::show-room", which prints out text describing memory use.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: Returns the number of bytes free in the current Wraith Scheme active memory generation.

For Example:

(e::active-room)  ;; ==> 567328  ;; e.g.

e::active-store-size

Type:

Procedure.

Operation:

Find the size of the active generation in use by the Wraith Scheme generational garbage collector.

Rationale, Explanation, Excuses:

"e::active-store-size" is a basic memory-inspection function. Do not confuse it with "e::active-room": "e::active-store-size" shows how many bytes total are available for the use of the active generation has, "e::active-room" shows how many of those bytes remain unused.

NOTE that the store sizes of the active and aging memory generations are always the same.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: Returns the size, in bytes, of Wraith Scheme's active generation.

For Example:

(e::active-store-size)  ;; ==> 1052672  ;; E.g.

e::aging-room

Type:

Procedure.

Operation:

Find the number of bytes free in the current Wraith Scheme aging memory generation.

Rationale, Explanation, Excuses:

Simple storage-instrumentation procedure: Just returns a number. Contrast with "e::show-room", which prints out text describing memory use.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: Returns the number of bytes in the current Wraith Scheme aging memory generation, that are not in use.

For Example:

(e::aging-room)  ;; ==> 42  ;; e.g.

e::alarm

Type:

Wraith Scheme does not define a value for "e::alarm"; the intent is, that the symbol "e::alarm" may be bound to a lambda expression of your choice.

Operation:

Whatever you like.

Rationale, Explanation, Excuses:

The procedure "e::alarm" is not defined by Wraith Scheme; indeed, the symbol "e::alarm" does not even exist in the distributed version of Wraith Scheme! It is you who may, if you wish, define "e::alarm". You may make it be any lambda expression of no arguments that you like.

You may use the procedure "e::set-alarm!" to cause Wraith Scheme to interrupt itself at a time in the future; when that time occurs, the procedure "e::alarm" will run. You may also use the procedures "e::alarm?" and "e::alarm-time" respectively to tell whether an alarm is presently set and at what time (Unix time) it will occur.

You may also cause "e::alarm" to run by sending a "SIGALRM" signal to Wraith Scheme from some other program.

Use of these procedures makes it possible to start something happening automatically at a specified time in the future. These procedures provide a rather straightforward interface to the Unix "alarm" system call, which is the mechanism Wraith Scheme uses for implementing them

The alarm is made to go off by pushing the Scheme expression '(e::alarm) into the input queue of the Wraith Scheme process (kitten or MomCat) in which the alarm was set. If that process is busy doing something else, the alarm will not be processed until the process is no longer busy. Thus the alarm system does not provide a truly asynchronous interrupt; for an alarm to happen promptly you must run it in a kitten that is not busy, or in an un-busy MomCat.

NOTE that the fact that '(e::alarm) is pushed into an input queue means that the evaluation of (e::alarm) will always take place at top-level. Any definition of e::alarm in a local environment -- such as within a "let" -- will not be used.

If the symbol "e::alarm" is not bound to a value, or is not bound to a lambda expression, then no alarm will go off. Wraith Scheme will report an error if an alarm goes off while "e::alarm" is bound to a lambda expression that requires arguments.

Arguments:

None.

Side Effects:

Whatever you like.

Returned Value:

Whatever you like.

For Example:

(define (e::alarm) (display "Alarms and excursions!!\n"))
  ;; ==> e::alarm
(e::set-alarm! 10)  ;; ==> #t

;; Ten seconds later ...

Alarms and excursions!!

e::alarm?

Type:

Procedure.

Operation:

Tests whether an alarm is presently set.

Rationale, Explanation, Excuses:

You may also cause "e::alarm" to run by sending a "SIGALRM" signal to Wraith Scheme from some other program.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, an alarm is set and has not yet occurred.

For Example:

(define (e::alarm) (display "Alarms and excursions!!\n"))
  ;; ==> e::alarm
(e::alarm?)         ;; ==> #f
(e::set-alarm! 10)  ;; ==> #t

;; Typed immediately:

(e::alarm?)         ;; ==> #t

;; Ten seconds later ...

Alarms and excursions!!

(e::alarm?)         ;; ==> #f

e::alarm-time

Type:

Procedure.

Operation:

Tells when any presently set alarm will occur.

Rationale, Explanation, Excuses:

You may also cause "e::alarm" to run by sending a "SIGALRM" signal to Wraith Scheme from some other program.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer. If an alarm is set, the returned value will be the Unix time at which the alarm occurs. If no alarm is set, the returned value will be -1.

The returned value is only accurate to approximately the nearest second.

For Example:

(define (e::alarm) (display "Alarms and excursions!!\n"))
  ;; ==> e::alarm
(e::alarm-time)     ;; ==> -1
(e::set-alarm! 10)  ;; ==> #t

;; Typed immediately:

(e::alarm-time)     ;; ==> A large number, a Unix time.

;; Ten seconds later ...

Alarms and excursions!!

(e::alarm-time)     ;; ==> -1

e::all?

Type:

Procedure.

Operation:

Test whether all objects in a list are "true"; that is, that no object in the list is #f.

Rationale, Explanation, Excuses:

This procedure might be useful when you would like to write

(apply and <list>)

but you cannot, because "and" is a special form.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, no element of the given list is #f. Otherwise, returns #f.

For Example:

(e::all? '(1 2 3))      ;; ==> #t
(e::all? '(1 #f 3))     ;; ==> #f
(e::all? '())           ;; ==> #t  (The empty list contains no element that is #f.)

e::any?

Type:

Procedure.

Operation:

Test whether any object in a list is "true"; that is, that at least one object in the list is not #f.

Rationale, Explanation, Excuses:

This procedure might be useful when you would like to write

(apply or <list>)

but you cannot, because "or" is a special form.

Arguments:

One proper list.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, at least one element of the given list is not #f. Otherwise, returns #f.

For Example:

(e::any? '(#f 1 #f))    ;; ==> #t
(e::any? '(#f #f #f))   ;; ==> #f
(e::any? '())           ;; ==> #f  (The empty list contains no element that is not #f.)

e::atom?

Type:

Procedure.

Operation:

Test whether a Wraith Scheme object is an atom.

Note that what kinds of objects are atoms may vary from Scheme implementation to Scheme implementation.

Rationale, Explanation, Excuses:

Useful for characterizing Wraith Scheme objects and for determining whether it is useful to make an object forgettable.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an atom. Otherwise, returns #f.

For Example:

(e::atom? #f)          ;; ==> #t
(e::atom? (cons 1 2))  ;; ==> #f

e::big-red-button-enabled?

Type:

Procedure.

Operation:

Tests whether the big red button (in the Wraith Scheme Sensory Devices Drawer) is enabled. Affects only the big red button of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Required for checking the state of the big red button from Wraith Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the big red button is enabled. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(e::big-red-button-enabled?)
    ;; ==> #t -- The big red button is enabled.

e::big-red-button-interrupt-number

Type:

Procedure.

Operation:

Return the interrupt number associated with the big red button of the Wraith Scheme process where the procedure was called. Reports an error if that button is not enabled.

Rationale, Explanation, Excuses:

Required for controlling the big red button (in the Wraith Scheme Sensory Devices Drawer) from Wraith Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

An exact integer in the range [0..1023], that is the interrupt number presently associated with the big red button.

For Example:

(e::big-red-button-interrupt-number)
    ;; ==> 73 -- The big red button is set to trigger interrupt 73.

e::bit-and     e::bit-not     e::bit-or

e::bit-shift-left     e::bit-shift-right-arithmetic

e::bit-shift-right-logical     e::bit-xor

Type:

Procedure. (All of them.)

Operation:

These enhancements provide traditional bitwise boolean and shift operations for integers which can be stored as 64-bit fixnums; that is, integers in the range [-9223372036854775808 .. 9223372036854775807].

Rationale, Explanation, Excuses:

Arguments:

"e::bit-and", "e::bit-or" and "e::bit-xor": Two integers in the range that can be stored as 64-bit fixnums. "e::bit-not": One integer in the range that can be stored as 64-bit fixnums. "e::bit-shift-left", "e::bit-shift-right-arithmetic" and "e::bit-shift-right-logical": Two integers, the first in the range that can be stored as 64-bit fixnums and the second nonnegative.

Side Effects:

None.

Returned Value:

An integer stored as a 64-bit fixnum. "e::bit-and", "e::bit-or" and "e::bit-xor" return respectively the bitwise logical and, or, and xor of their arguments. "e::bit-not" returns the bitwise logical negation of its argument. The shift operators return their first argument shifted a number of bits equal to the second argument, in the direction indicated. "e::bit-shift-left" and "e::bit-shift-right-logical" pad at the shifted-in end with zeros. "e::bit-shift-right-arithmetic" pads with the most significant bit; that is, the sign bit.

For Example:

(e::bit-and #b1011 #b1101)    ;; ==> 9   ;; Binary 1001
(e::bit-or #b1011 #b1101)     ;; ==> 15   ;; Binary 1111
(e::bit-xor #b1011 #b1101)    ;; ==> 6   ;; Binary 0110

(e::bit-not #b1011)           ;; ==> -12
  ;; Binary 1111111111111111111111111111111111111111111111111111111111110100

(e::bit-shift-left #b1011 3)            ;; ==> 88  ;; Binary 1011000

(e::bit-shift-right-logical -1 48)      ;; ==> 65535   ;; Binary 1111111111111111

(e::bit-shift-right-arithmetic -1 16)   ;; ==> -1
                                        ;;      -1 shifted right and padded with 1's
                                        ;;      is still -1

e::block-any-binding

Type:

Procedure.

Operation:

Block read and write access to the value of a Wraith Scheme that is the car of a pair (perhaps most usefully, that is the car of a list), by locking the pair itself.

This procedure is one of five that are particularly useful in dealing with critical sections that involve Wraith Scheme objects, notably symbols. The five procedures in question are

First, parallel programming is a subtle art. Incorrect handling of critical sections may easily cause programs to become unresponsive or otherwise to fail. Such problems are often difficult to debug.
Second, the arguments and return values for these procedures may include Wraith Scheme objects that are already locked. Attempts to use such locked objects in any way -- including reading, displaying, or changing their values -- may cause Wraith Scheme to become unresponsive, with no possibility of recovery short of restarting the program.

Technical Note: The problem indicated is a deadlock due to an attempt to access a locked object.

Rationale, Explanation, Excuses:

Useful low-level primitive for parallel programming.

Arguments:

One pair.

Side Effects:

Blocks read and write access to the pair. That is, any attempt to access the car or cdr of the pair, than by way of the first item in the list of returned values, will result in the process making the attempt stalling until the block is released, perhaps by "c::release-block".

Contrast this procedure with "e::block-symbol-binding" -- which follows -- in which the argument is a symbol.

Returned Value:

A list of two items. The first is the car of the pair immediately after the lock was applied. (Since access to the pair is now locked, there is no other way to obtain that value.) The second is a locked object suitable both for the first argument to a call to "c::set-blocked-binding!" (to change the bound value), and for the argument to "c::release-block" (to release the lock).

When "c::set-blocked-binding!" is applied to the locked object in the manner just described, it is the car of the pair that is modified.

For Example:

e::block-any-binding

c::release-block

(define a (list 42))                                       ;; ==> a

(define (blocked-increment-of-a)
   (let* ((the-block-list (e::block-any-binding a))
          (the-value (car the-block-list))
          (the-lock (cadr the-block-list))
          )
      (c::set-blocked-binding! the-lock (+ the-value 1))
      (c::release-block the-lock)))                        ;; ==> blocked-increment-of=a

a                                ;; ==> (42)
(blocked-increment-of-a)         ;; ==> #t
a                                ;; ==> (43)

You might note in passing that the call to "e::block-any-binding" is of the form

(e::block-any-binding a)   ;; Without quote

(e::block-any-binding 'a)  ;; With quote

e::block-symbol-binding

Type:

Procedure.

Operation:

Block read and write access to the value of a bound Wraith Scheme symbol, except via c::set-blocked-binding!, which see.

This procedure is one of five that are particularly useful in dealing with critical sections that involve Wraith Scheme objects, notably symbols. The five procedures in question are

c::block
c::release-block
e::block-any-binding
e::block-symbol-binding
c::set-blocked-binding!

First, parallel programming is a subtle art. Incorrect handling of critical sections may easily cause programs to become unresponsive or otherwise to fail. Such problems are often difficult to debug.
Second, the arguments and return values for these procedures may include Wraith Scheme objects that are already locked. Attempts to use such locked objects in any way -- including reading, displaying, or changing their values -- may cause Wraith Scheme to become unresponsive, with no possibility of recovery short of restarting the program.

Technical Note: The problem indicated is a deadlock due to an attempt to access a locked object.

Rationale, Explanation, Excuses:

Useful low-level primitive for parallel programming.

Arguments:

One symbol.

Side Effects:

Blocks read and write access to the value of its argument, except via c::set-blocked-binding!, which see. That is, any attempt to access the blocked value, other than by way of the first item in the list of returned values, will result in the process making the attempt stalling until the block is released, perhaps by "c::release-block".

Contrast this procedure with "e::block-any-binding" -- which precedes -- in which the argument is a pair.

Returned Value:

A list of two items. The first is the value bound to the symbol immediately after the lock was applied. (Since access to that binding is now locked, there is no other way to obtain that value.) The second is a locked object suitable both for the first argument to a call to "c::set-blocked-binding!" (to change the bound value), and for the argument to "c::release-block" (to release the lock).

For Example:

e::block-symbol-binding

c::set-blocked-binding!

c::release-block

(define a 0)                                              ;; ==> a

(define (blocked-increment-of-a)
   (let* ((the-block-list (e::block-symbol-binding 'a))
          (the-value (car the-block-list))
          (the-lock (cadr the-block-list))
          )
      (c::set-blocked-binding! the-lock (+ the-value 1))
      (c::release-block the-lock)))                       ;; ==> blocked-increment-of-a

a                         ;; ==> 0
(blocked-increment-of-a)  ;; ==> #t
a                         ;; ==> 1

You might note in passing that the call to "e::block-symbol-binding" is of the form

(e::block-symbol-binding 'a)  ;; With quote

(e::block-symbol-binding a)   ;; No quote

e::bound-instance?

Type:

Procedure.

Operation:

Test whether a symbol has a value or binding in any environment in the lexical scope of where "e::bound-instance?" was called.

Rationale, Explanation, Excuses:

Many Lisp systems would call this procedure "boundp" or "bound?". It can be useful when investigating Scheme memory, or when one needs to make sure that a haphazardly chosen symbol has no value or binding.

Arguments:

One symbol.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument has a value or binding in the current lexical scope. Otherwise, returns #f.

For Example:

(e::bound-instance? '+)       ;; ==> #t
(e::bound-instance? 'cons)    ;; ==> #t
(define a 3)                  ;; ==> a
(e::bound-instance? 'a)       ;; ==> #t
(e::bound-instance? 'xglerb)  ;; ==> #f  -- Unless you have defined xglerb.

e::c-boolean->scheme-boolean

Type:

Procedure.

Operation:

Convert numbers, taken as C-style booleans, to #t or #f.

Rationale, Explanation, Excuses:

Useful with the Wraith Scheme foreign-function interface, for dealing with foreign booleans.

Arguments:

One number.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is nonzero. Otherwise, returns #f.

For Example:

(e::c-boolean->scheme-boolean 0)   ;; ==> #f
(e::c-boolean->scheme-boolean 1)   ;; ==> #t
(e::c-boolean->scheme-boolean -1)  ;; ==> #t
(e::c-boolean->scheme-boolean 42)  ;; ==> #t

e::clear-compiler-on!

Type:

Procedure.

Operation:

Clear the internal flag that tells Wraith Scheme to compile defines automatically.

Rationale, Explanation, Excuses:

Provides Scheme-program control of an important internal flag.

Arguments:

None.

Side Effects:

Turns off automatic compilation.

Returned Value:

For Example:

(e::clear-compiler-on!)  ;; ==> #t

e::clear-permanent!

Type:

Procedure.

Operation:

Clear the "permanent" flag associated with a symbol that has a value or binding.

Rationale, Explanation, Excuses:

To make it difficult inadvertently to redefine fundamental Scheme procedures like "+" and "cons", I provide symbols with a "permanent" flag. When set, any attempt to change the value or binding of the given symbol causes Wraith Scheme to report an error. Procedure "e::clear-permanent!" clears this flag, so you can, for example, redefine "cons", if you really, really, want to. Procedure "e::set-permanent!" sets a symbol's permanent flag, so you cannot change the value to which it is bound. Procedure "e::permanent?" tests whether that flag is set or not.

On your head be it.

You may of course use "e::clear-permanent" and its companion, "e::set-permanent!", for new variables that you yourself create.

Arguments:

One symbol.

Side Effects:

Makes it possible to change what the value or binding of the argument.

Returned Value:

For Example:

(e::clear-permanent! 'cons)  ;; ==> #t  ;; DANGER WILL ROBINSON

e::clear-show-full-precision!

Type:

Procedure.

Operation:

Clear the internal flag that tells Wraith Scheme to display numbers with the full precision available.

Rationale, Explanation, Excuses:

Provides Scheme-program control of an important internal flag.

Arguments:

None.

Side Effects:

Causes Wraith Scheme's numeric display routines to use reduced precision.

Returned Value:

For Example:

(e::clear-show-full-precision!)  ;; ==> #t

e::closed-port?

Type:

Procedure.

Operation:

Test whether a port is closed.

Rationale, Explanation, Excuses:

The entities that Wraith Scheme uses for ports persist even after they have been closed; they are in fact reused. "Open" and "closed" are elements of port state. Thus it makes sense to have a procedure to test whether a port is open or closed.

Arguments:

One port -- either an input port or an output port will do.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is closed. Otherwise, returns #f.

For Example:

(define foo (open-output-file "Whatever"))  ;; ==> foo
(e::closed-port? foo)                       ;; ==> #f
(close-output-port foo)                     ;; ==> #t
(e::closed-port? foo)                       ;; ==> #t

e::coerce-to-long-ratnum-if-possible

Type:

Procedure.

Operation:

Coerces a real to long ratnum form, if the real is in the range where that is possible.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

One real number.

Side Effects:

None.

Returned Value:

Either the real expressed as a long ratnum, or #f if the conversion is not possible.

For Example:

(e::coerce-to-long-ratnum-if-possible 42)     ;; ==> 42/1
(e::coerce-to-long-ratnum-if-possible 42.5)   ;; ==> #i85/2
(e::coerce-to-long-ratnum-if-possible 3/2)    ;; ==> 3/2
(e::coerce-to-long-ratnum-if-possible 1.e30)  ;; ==> #f

e::coercible-to-fixnum?

Type:

Procedure.

Operation:

Determines whether an object is an integer in the range wherein it can be coerced to a 64-bit signed integer.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an integer in the range of 64-bit signed integers. Otherwise, returns #f.

For Example:

(e::coercible-to-fixnum? 42)     ;; ==> #t
(e::coercible-to-fixnum? 42.5)   ;; ==> #f
(e::coercible-to-fixnum? 1.e30)  ;; ==> #f
(e::coercible-to-fixnum? '())    ;; ==> #f

e::coercible-to-long-ratnum?

Type:

Procedure.

Operation:

Determines whether an object is a number that can be expressed as a rational using 64-bit signed integers.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a number that can be expressed as a rational using 64-bit signed integers. Otherwise, returns #f.

For Example:

(e::coercible-to-long-ratnum? 42)     ;; ==> #t
(e::coercible-to-long-ratnum? 42.5)   ;; ==> #t
(e::coercible-to-long-ratnum? 1.e30)  ;; ==> #f
(e::coercible-to-long-ratnum? '())    ;; ==> #f

e::compiler-on?

Type:

Procedure.

Operation:

Return the value of the internal flag that controls whether Wraith Scheme compiles defines automatically.

Rationale, Explanation, Excuses:

Allow Scheme programs to examine important internal state of the Wraith Scheme interpreter.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean: Returns the (boolean) flag that controls whether Wraith Scheme compiles defines automatically. That flag is true if, and only if, defines are automatically compiled.

For Example:

(e::set-compiler-on!)    ;; ==> #t
(e::compiler-on?)        ;; ==> #t

(e::clear-compiler-on!)  ;; ==> #t
(e::compiler-on?)        ;; ==> #f

e::compile-form

Type:

Procedure.

Operation:

Invoke the Wraith Scheme compiler on a Scheme object.

Rationale, Explanation, Excuses:

Wraith Scheme has a rather minimal compiler built in; this is how you use it. Actually, it is perhaps better used by setting the "Compile Defines" flag from the Interpreter Menu, but this procedure allows you to compile individual objects.

The compiler only compiles lambda expressions.

The top-level loop will print out #<Interpreted lambda expression> when it returns from "e::compile-form", but if you use "e::inspect" on what it returns you will see that variable references have been replaced by references to specific locations in the environment; the form is being interpreted, but much of the work in interpreting an uncompiled form -- looking up the values or bindings of symbols -- will now be side-stepped.

Arguments:

One Scheme object; preferably, a lambda expression.

Side Effects:

Compiles the lambda expression.

Returned Value:

A Scheme object.

For Example:

;;  With the "Compile Defines" menu item disabled:

(define (increment x) (+ x 1))    ;; ==> increment

(e::inspect increment)            ;; ==>
                                  ;;  The hex numbers will vary
0004-1b8484cc: Lambda Pair -- Not a Car
(lambda (x) (+ x 1))
Lambda's non-top-level environments are:
 ... 
-------- End of Environment List --------
#<Interpreted lambda expression>

;; Now compile it, and inspect again:

(define increment (e::compile-form increment))  ;; ==> increment

(e::inspect increment)                          ;; ==>
                                                ;;  The hex numbers will vary
0004-1b8417c4: Lambda Pair -- Not a Car
(lambda (x) (#<Built-in procedure "+">
             #<Ref to var 0 in environment 0 down> 1))
Lambda's non-top-level environments are:
 ... 
-------- End of Environment List --------
#<Interpreted lambda expression>

e::cons-with-continuation

Type:

Procedure.

Operation:

Cons the argument with the Wraith Scheme continuation, which will cause it to be evaluated immediately, in the environment in which "e::cons-with-continuation" was called.

Rationale, Explanation, Excuses:

This procedure is what many Lisp interpretations would call "eval". At the time I implemented it, there was much debate in the Scheme community about whether Scheme should have an "eval" procedure at all, and if it did, what that procedure should do. Much of the debate centered around the environment in which the evaluation should take place. I side-stepped the debate by (1) not calling "e::cons-with-continuation" "eval", and (2) choosing a name that made it very clear what environment was in use.

At least, it is clear if you know what a "continuation" is.

Note that

(e::cons-with-continuation <whatever>)

is not equivalent to

(eval <whatever> (interaction-environment))

In Wraith Scheme, the interaction environment is the one encountered when entering Scheme expressions into the top-level loop, but "e::cons-with-continuation" uses the environment in which it was called, which may be the local environment of a lambda expression containing that call.

Note further that because of the renaming of formal parameters of lambda expressions during macro expansion, use of "e::cons-with-continuation" within lambda expressions, with quoted arguments, may give unexpected results, such as:

(let ((x 3)) (e::cons-with-continuation 'x))
  ;; ==> <error>
x
Problem: No lexically visible binding of this symbol.

What is happening is that in Wraith Scheme, "let" is a macro, which in this case expands using a renamed lambda variable, into something like:

((c::lambda (g23008) (e::cons-with-continuation (quote x))) 3)

(The actual name used will vary depending on how many similar substitutions Wraith Scheme has made since it was started.)

Arguments:

One Scheme object.

Side Effects:

Evaluates the argument immediately, in the environment in which "e::cons-with-continuation" is called.

Returned Value:

Any Scheme object. Strictly, e::cons-with-continuation does not return: Where you would have expected a return value to appear, what appears instead is the result of evaluating the argument.

For Example:

(define form-to-be-evaled
  (list 
    'begin
    (list 'display "Hello from the continuation!")
    (list 'newline)))  ;; ==> form-to-be-evaled

form-to-be-evaled  ;; ==>
  (begin
    (display "Hello from the continuation!")
    (newline))

(e::cons-with-continuation form-to-be-evaled)  ;; ==>
Hello from the continuation!
#t

e::continued-fraction-list->real

Type:

Procedure.

Operation:

Accepts a list of numbers in the usual form for representing a continued fraction and returns the corresponding value as a long ratnum.

Rationale, Explanation, Excuses:

Useful in connection with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

A proper list of integers.

Side Effects:

None.

Returned Value:

A long ratnum.

For Example:

(e::continued-fraction-list->real '(1 2))                         ;; ==> 3/2
(e::continued-fraction-list->real '(0 1 1))                       ;; ==> 1/2
(e::continued-fraction-list->real '(1 1 1 1 1 1 1 1 1 1 1 1))     ;; ==> 233/144

e::current-directory

Type:

Procedure.

Operation:

Find the current directory; the directory from which Unix relative paths begin.

Rationale, Explanation, Excuses: Making effective use of the MacIntosh's Unix file system from Wraith Scheme requires means to set and determine the current directory.

Arguments:

None.

Side Effects:

None.

Returned Value:

A string: Returns a string containing a Unix-style path to the current directory. The returned string will end in a '/'.

For Example:

(e::current-directory)  ;; ==> "/"  (When Wraith Scheme starts from the Dock.)

e::debug

Type:

Procedure.

Operation:

Not built in to Wraith Scheme; to be defined by the user.

Rationale, Explanation, Excuses:

Wraith Scheme has no complicated built-in debugger; proper use of the symbol "e::debug" allows loading run at run-time, or at start-Wraith-Scheme time, or whenever you like.

Fundamentally, a debugging program is no different from any other Scheme program. You should be able to install whatever debugger you like, and -- if you have the source code -- modify it to suit yourself. The catch is, that the Wraith Scheme program needs to be able to call your debugging program when an error occurs, and to do so it needs to know the program's "name". Thus I have provided a special symbol, "e::debug", which the Wraith Scheme program recognizes and uses for that purpose.

When a non-fatal error occurs, the Wraith Scheme error-handling mechanism prints out an error message, then determines whether "e::debug" has been defined. If not, error handling provides some simple trace information -- in effect using a very simple built-in debugger.

Alternatively, If "e::debug" has been defined, Wraith Scheme will call it (and it had better be a procedure accepting one argument), passing as an argument a list of all the environments within the lexical scope of the place where the error occurred, that list being sorted in order of lexical nesting, so that more closely-nested environments occur earlier in the list.

The procedure "e::debug" may do whatever its creator wishes with that information. It might well terminate with a call to "e::reset": A normal return will merely return control to the Wraith Scheme error-handling mechanism, which will then proceed with its simple, built-in trace.

Any value returned by "e::debug" will be ignored.

Arguments:

When called by Wraith Scheme, "e::debug" is passed a list of all the environments in the lexical scope of the call to "e::debug".

Side Effects:

Depends on the definition of "e::debug".

Returned Value:

Undefined.

For Example:

Does not apply.

e::deep-copy

Type:

Procedure.

Operation:

Return a copy of its argument which is "equal?" to the argument, but in which copied vectors, lists and strings in corresponding positions in the structure are not "eq?".

Rationale, Explanation, Excuses:

I needed this procedure for development of Wraith Scheme, and thought it might be generally useful. The source code for "e::deep-copy" is:

(define (e::deep-copy x)
  (cond
    ((pair? x)   (cons (e::deep-copy (car x)) (e::deep-copy (cdr x))))
    ((vector? x) (list->vector (map e::deep-copy (vector->list x))))
    ((string? x) (string-copy x))
    (#t x)))

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A Scheme object of the same structure as the argument, and "equal?" to it, but containing newly-allocated structures for lists, vectors and strings, where applicable.

For Example:

(e::deep-copy (list 1 2 3))  ;; ==> (1 2 3)

e::define-no-compile

Type:

Procedure.

Operation:

Automatically skips automatic compilation; even when the "Compile Defines" menu item is set, "(e::define-no-compile foo <bar>)" does not compile <bar>, and binds it to "foo". That is, it does what "(define foo <bar>)" would do if the "Compile Defines" menu item were not set.

Rationale, Explanation, Excuses:

Sometimes it is useful to compile most things but not all, or to exempt some procedures from being compiled.

Arguments:

Two: The first an identifier, the second any Scheme object.

Note that "e::define-no-compile" only accepts the simple, two-argument syntax for "define". It is an error, for example, to attempt

(e::define-no-compile (increment x) (+ x 1))

Side Effects:

Causes the second argument to become the value or binding of the first.

Returned Value:

A symbol: Returns the first argument.

For Example:

(e::define-no-compile
  increment
  (lambda (x) (+ x 1)))  ;; ==> increment

(e::inspect increment)  ;; The hexadecimal numbers may differ
0004-1b7bb660: Lambda Pair -- Not a Car
(lambda (x) (+ x 1))    ;; No variable substitution --
                        ;;   not compiled.
Lambda's non-top-level environments are:
 ... 
-------- End of Environment List --------
#<Interpreted lambda expression>

e::derationalize

Type:

Procedure.

Operation:

If necessary, convert a real number to a form that is not a rational in which numerator and denominator are stored separately.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

One real number.

Side Effects:

If the argument is a rational in which numerator and denominator are stored separately, divide the numerator by the denominator and return the result as some other form of number. Otherwise, return the argument unchanged.

Returned Value:

A real number.

For Example:

(e::derationalize 1/3)  ;; ==> 0.33333333333333331
(e::derationalize 3.)   ;; ==> 3.

e::disable-big-red-button!

Type:

Procedure.

Operation:

Disable the big red button of the Wraith Scheme Process where the procedure was called.

Rationale, Explanation, Excuses:

Required for controlling the big red button (in the Wraith Scheme Sensory Devices Drawer) from Wraith Scheme.

Arguments:

None.

Side Effects:

Disables the big red button, if it is enabled. Has no effect, and does not report an error, if the big red button is already disabled.

Returned Value:

For Example:

(e::disable-big-red-button!)  ;; Disables the big red button.

e::disable-pushbutton!

Type:

Procedure.

Operation:

Disable a pushbutton of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Required for controlling the pushbuttons (in the Wraith Scheme Sensory Devices Drawer) from Wraith Scheme.

Arguments:

One integer in the range [0..3].

Side Effects:

Disables the given pushbutton, if it is enabled. Has no effect, and does not report an error, if the pushbutton is already disabled.

Returned Value:

For Example:

(e::disable-pushbutton! 1)  ;; ==> Disables pushbutton 1.

e::enable-big-red-button!

Type:

Procedure.

Operation:

Assign an interrupt number to the big red button, and enable that button so that it will trigger the given interrupt when pushed. Affects only the big red button of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Required for controlling the big red button (in the Wraith Scheme Sensory Devices Drawer) from Wraith Scheme.

Arguments:

One exact integer in the range [0..1023]

Side Effects:

Enables the big red button to trigger the given interrupt when pushed.

Returned Value:

For Example:

(e::enable-big-red-button! 88)  ;; ==> Set the big red button
                                ;;     to trigger interrupt
                                ;;     88 when pushed.

e::enable-pushbutton!

Type:

Procedure.

Operation:

Assign an interrupt number to a pushbutton of the Wraith Scheme process where the procedure was called, and enable that button so that it will trigger the given interrupt when pushed.

Rationale, Explanation, Excuses:

Required for controlling the pushbuttons (in the Wraith Scheme Sensory Devices) Drawer from Wraith Scheme.

Arguments:

Two: The first an integer in the range [0..3], the second an integer in the range [0..1023]

Side Effects:

Enables the pushbutton whose number is the first argument, to trigger the interrupt given as the second argument.

Returned Value:

For Example:

(e::enable-pushbutton! 3 137)  ;; ==> Set pushbutton 3 to
                               ;;     trigger interrupt 137
                               ;;     when pushed.

e::entropy-death

Type:

Constant -- a very large integer.

Operation:

Intended to provide a Unix time for use with forgettable objects that is sufficiently far in the future that it is unlikely to be passed by any executing Wraith Scheme program.

Rationale, Explanation, Excuses:

Adds clarity of purpose to code and saves typing large integers.

For Example:

(e::make-forgettable (cons 1 2) e::entropy-death 0.5)
     ;; ==> #<Forgettable Object Pointer, unexpired, expiration time 9223372036854775807>

e::error

Type:

Procedure.

Operation:

Print an error message and reset to top-level loop.

Rationale, Explanation, Excuses:

Useful primitive for error-handling.

Arguments:

One string.

Side Effects:

Resets Wraith Scheme to the top-level loop.

Returned Value:

Does not return.

For Example:

(e::error "Oops!!")  ;; ==>

Problem: Oops!!  (Resetting)
Top-level loop ...

e::error-port

Type:

Procedure.

Operation:

Return the default output port for error messages.

Rationale, Explanation, Excuses:

Wraith Scheme generally handles the output from error messages differently from normal output. For example, even when "current-output-port" returns a port to a file, error messages are usually sent to the console (and thereby also to any transcript file that may be open). "e::error-port" returns the port to which Wraith Scheme's error messages are sent, so that you may make procedures that you create handle errors in the same way.

Arguments:

None.

Side Effects:

None.

Returned Value:

An output port: Returns the current error port, which is typically the console.

For Example:

;; You can write a procedure that displays error messages
;; at the console when normal output is being sent elsewhere.

(define (my-procedure)
    ...
  (if <disaster>
    (begin 
      (display
        "My-procedure is going down in flames!\n"
        (e::error-port))
      (e::reset)))
    ...
  )  ;; ==> my-procedure

;; If disaster strikes the message
;; "My-procedure is going down in flames!"
;; will appear in the Wraith Scheme window,
;; even if normal output goes to a file, as in:

(with-output-to-file "foo" my-procedure)

e::exit

Type:

Procedure.

Operation:

Exit the Wraith Scheme program immediately, with no second chances and no confirmation dialog.

When invoked from the MomCat, this procedure also causes all other instances of Wraith Scheme that are running -- that is, all kittens -- to exit. When called from a kitten that is not the MomCat, only that kitten will exit.

Rationale, Explanation, Excuses:

It is sometimes useful to run a Scheme program autonomously -- perhaps from the Unix command line or from a script. A forced exit is useful in such circumstances.

Arguments:

None.

Side Effects:

Quits from the Wraith Scheme program. When called from the MomCat, also causes any kittens present to exit.

Returned Value:

Does not apply.

For Example:

(e::exit)  ;; ==> ;;  Wraith Scheme exits.

e::expand-macro

Type:

Procedure.

Operation:

Expand a macro, but do not evaluate the expanded form.

Rationale, Explanation, Excuses:

A "call" or invocation of a Wraith Scheme macro involves using a procedure -- sometimes called a "transformer" -- that was created when the macro was defined, to transform the expression in which the macro call occurred, into something else. That "something else" is evaluated by Wraith Scheme, to produce the result of the macro "call".

"e::expand-macro" does all of these steps except for the last one: It produces the "something else", but does not evaluate it.

For example, in Wraith Scheme, "if" is a macro. When Wraith Scheme encounters an expression like "(if #t 1 2)", Wraith Scheme

Evaluates the symbol "if".
Notices that the value of "if" is a macro.
Looks up the transforming procedure associated with that macro.
Performs the indicated transformation on the original expression, producing a transformed expression, which happens to be (c::if #t 1 2). ("c::if" is a simpler form of "if", which only works with three arguments; in this case they are "#t", "1", and "2".)
Evaluates the transformed expression, producing -- you guessed it -- "1".

e::expand-macro does all of that except for the last step. It returns (c::if #t 1 2) as its result. I installed this procedure primarily for debugging Wraith Scheme's low-level macro implementation.

Arguments:

A list, whose car evaluates to a macro.

Side Effects:

None in its own right, but macro expansion may have side effects that depend on the transforming procedure associated with the particular macro.

Returned Value:

A list: Returns the expansion of the macro.

For Example:

(e::expand-macro
  '(cond (#f 1) (#f 4) (#t 42) (else 'foo)))  ;; ==>

;; Formatted for clarity:  Note that the expansion of
;; the macro is not recursive -- the returned form
;; contains another instance of the "cond" macro.

(c::if #f
  (begin 1)
  (cond (#f 4) (#t 42) (else (quote foo))))

e::expand-macros-recursively

Type:

Procedure.

Operation:

Recursively expand all the macros, in a Wraith Scheme expression until none remain, but do not evaluate the expanded form.

Note that this procedure modifies its argument. (Perhaps I should have named it "e::expand-macros-recursively!".) For that reason, an attempt to use "e::expand-macros-recursively" with an argument that is a quoted expression, like

(e::expand-macros-recursively
  '(cond (#f 1) (#f 4) (#t 42) else 'foo))

will fail, because quoted expressions are supposed to be constants, and are not supposed to be modifiable, and Wraith Scheme is pretty good about catching attempts to do so. Use e::deep-copy, as shown in the example below.

Rationale, Explanation, Excuses:

This procedure is rather an elaboration of "e::expand-macro", immediately above: Whereas "e::expand-macro" only expands the outermost macro in a Scheme expression (and only works if the car of the expression is in fact a macro), "e::expand-macros-recursively" goes through the entire expression, expanding every macro it can find, and doesn't stop until no macros remain.

Like "e::expand-macro", "e::expand-macros-recursively" does not evaluate the fully-expanded expression.

Arguments:

A Scheme expression, presumably containing macros.

Side Effects:

None in its own right, but macro expansion may have side effects that depend on the transforming procedure associated with the particular macro.

Returned Value:

Returns the given Scheme expression with all macros expanded.

For Example:

(e::expand-macros-recursively
  (e::deep-copy
    '(cond (#f 1) (#f 4) (#t 42) (else 'foo))))  ;; ==>

;; Formatted for clarity:

(c::if #f 
  1 
  (c::if #f
    4 
    (c::if #t 
      42 
      (quote foo))))

e::file-exists?

Type:

Procedure.

Operation:

Determine whether Unix-style pathname is a path to a file that can be opened for reading.

Rationale, Explanation, Excuses:

This procedure is useful for working with the Macintosh's Unix-based file system.

The name "e::file-exists?" is a little misleading: Strictly, the procedure returns a boolean indicating whether the Unix command "fopen" was able to open the indicated pathname for reading; the procedure may return #f if the file existed but had Unix permission settings inappropriate for reading by the current user of Wraith Scheme.

Arguments:

One string, presumably containing something that looks like a Unix-style pathname.

Side Effects:

None. Note in particular, that this procedure closes any file that it opens.

Returned Value:

A boolean: Returns #t if, and only if, Unix "fopen" could open the path contained within the argument for reading. Otherwise, returns #f.

For Example:

(e::file-exists? "/")             ;; ==> #t
(e::file-exists? "No.such.file")  ;; ==> #f  ;;  If there is no such file.

e::fixnum?

Type:

Procedure.

Operation:

Determine whether a Scheme object is a number stored as a fixnum.

Rationale, Explanation, Excuses:

I installed this procedure to aid in debugging Wraith Scheme's functions that deal with numbers. In the present version of Wraith Scheme, the only fixnums stored are 64-bit integers.

Note that it is possible to store integers as flonums: Wraith Scheme does so frequently.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a number stored as a fixnum. Otherwise, returns #f.

For Example:

(e::fixnum? #t)             ;; ==> #f
(e::fixnum? 1)              ;; ==> #t
(e::fixnum? 1.000)          ;; ==> #t
(e::fixnum? 1.001)          ;; ==> #f
(e::fixnum? (sqrt 4))       ;; ==> #f

;;  But note that

(integer? (sqrt 4))         ;; ==> #t

(e::fixnum? 10000000000000000000)  ;; ==> #f
(integer? 10000000000000000000)    ;; ==> #t

e::float?

Type:

Procedure.

Operation:

Determine whether a Scheme object is a number stored as a flonum

Rationale, Explanation, Excuses:

I installed this procedure to aid in debugging Wraith Scheme's functions that deal with numbers. In the present version of Wraith Scheme, flonums are used to store only 64-bit floating-point numbers.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a number stored as a flonum. Otherwise, returns #f.

For Example:

(e::float? #t)              ;; ==> #f
(e::float? 1)               ;; ==> #f
(e::float? 1.000)           ;; ==> #f
(e::float? 1.001)           ;; ==> #t
(e::float? (sqrt 4))        ;; ==> #t

;;  But note that

(integer? (sqrt 4))         ;; ==> #t

(e::float? 10000000000000000000)   ;; ==> #t
(integer? 10000000000000000000)    ;; ==> #t

e::float-matrix-=

Type:

Procedure.

Operation:

Determine whether two float matrices are numerically equal,

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the two float matrices have the same numbers of rows and columns, and if their elements at positions (i, j) are numerically equal for all allowed row numbers i and column numbers j. Otherwise, returns #f.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 3 2 '#(1 2 3 4 5 6)))  ;; ==> b
(define c (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 7)))  ;; ==> c

(e::float-matrix-= a a)  ;; ==> #t
(e::float-matrix-= a b)  ;; ==> #f
(e::float-matrix-= a c)  ;; ==> #f

e::float-matrix-add

Type:

Procedure.

Operation:

Add two float matrices.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

Returns a new float matrix which is the matrix sum of the two given matrices.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(2 4 6 8 10 12)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4  5  6)))  ;; ==> b

(e::float-matrix-add a b)  ;; ==>
                           ;; 3. 6. 9.
                           ;; 12. 15. 18.

e::float-matrix-antisymmetric?

Type:

Procedure.

Operation:

Is the argument an antisymmetric float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an antisymmetric float matrix. Returns #f otherwise.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))           ;; ==> a
(define b (e::make-float-matrix-from-vector 3 3 '#(1 0 0 0 2 0 0 0 3)))     ;; ==> b
(define c (e::make-float-matrix-from-vector 3 3 '#(0 1 2 -1 0 3 -2 -3 0)))  ;; ==> c

(e::float-matrix-antisymmetric? #t)  ;; ==> #f
(e::float-matrix-antisymmetric? a)   ;; ==> #f
(e::float-matrix-antisymmetric? b)   ;; ==> #f
(e::float-matrix-antisymmetric? c)   ;; ==> #t

e::float-matrix-copy

Type:

Procedure.

Operation:

Copy a float matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

A new float matrix, which is a copy of the argument.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(define b (e::float-matrix-copy a))                                ;; ==> b
a  ;; ==>
   ;; 1. 2. 3.
   ;; 4. 5. 6.
b  ;; ==>
   ;; 1. 2. 3.
   ;; 4. 5. 6.

e::float-matrix-determinant

Type:

Procedure.

Operation:

Calculate the determinant of a matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One square float matrix.

Side Effects:

None.

Returned Value:

An inexact real: The determinant of the argument.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(e::float-matrix-determinant a)                                ;; ==> -2.

e::float-matrix-diagonal?

Type:

Procedure.

Operation:

Is the argument a diagonal float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a square float matrix, all of whose off-diagonal elements are zero. Returns #f otherwise.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))           ;; ==> a
(define b (e::make-float-matrix-from-vector 3 3 '#(1 0 0 0 2 0 0 0 3)))     ;; ==> b
(define c (e::make-float-matrix-from-vector 3 3 '#(1 1 0 0 2 0 0 0 3)))     ;; ==> c

(e::float-matrix-diagonal? #t)  ;; ==> #f
(e::float-matrix-diagonal? a)   ;; ==> #f
(e::float-matrix-diagonal? b)   ;; ==> #t
(e::float-matrix-diagonal? c)   ;; ==> #f

e::float-matrix-cross-product

Type:

Procedure.

Operation:

Given two float matrices each of which has one row and three columns, and is thereby a three-vector, calculate a new one-by-three float matrix which is the vector cross product of the two given matrices. Specifically,

(e::float-matrix-cross-product A B)

A x B

Rationale, Explanation, Excuses:

Useful in mathematical physics and in engineering

Arguments:

Two float matrices, each with one row and three columns.

Side Effects:

None.

Returned Value:

A new float matrix with one row and three columns, which is the vector cross-product of the arguments in the order given. That is,

(e::float-matrix-cross-product A B)

A x B

For Example:

(define a (e::make-float-matrix-from-vector 1 3 '#(1 2 3)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 1 3 '#(4 5 6)))  ;; ==> b
(e::float-matrix-cross-product a b)                          ;; ==>
    -3. 6. -3.

e::float-matrix-dot-product

Type:

Procedure.

Operation:

Given two matrices which have the same number of rows and the same number of columns, calculate the sum over all positions ( i, j ) of the product of the first matrix element at ( i, j ) and the second matrix element at ( i, j ).

Rationale, Explanation, Excuses:

Useful in machine learning algorithms.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

The sum over all positions ( i, j ), of the product of the first matrix element at ( i, j ) and the second matrix element at ( i, j ).

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(2 4 6 8)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 2 2 '#(1 3 5 7)))  ;; ==> b
(e::float-matrix-dot-product a b)                              ;; ==> 100.

e::float-matrix-dump-row-to-vector

Type:

Procedure.

Operation:

Export the elements of one row of a float matrix into a Scheme vector.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two: The first a float matrix, the second an integer indicating the row to be dumped.

Side Effects:

None.

Returned Value:

A vector containing all elements of the given row.

For Example:

(define a
  (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(e::float-matrix-dump-row-to-vector a 0)                   ;; ==> #(1. 2. 3.)

e::float-matrix-dump-to-vector

Type:

Procedure.

Operation:

Export the elements of a float matrix into a Scheme vector, in row-major order.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

A vector containing all elements of the given matrix, in row-major order.

For Example:

(define a
  (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(e::float-matrix-dump-to-vector a)                         ;; ==> #(1. 2. 3. 4. 5. 6.)

e::float-matrix-dump-column-to-vector

Type:

Procedure.

Operation:

Export the elements of one column of a float matrix into a Scheme vector.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two: The first a float matrix, the second an integer indicating the column to be dumped.

Side Effects:

None.

Returned Value:

A vector containing all elements of the given column.

For Example:

(define a
  (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(e::float-matrix-dump-column-to-vector a 0)                ;; ==> #(1. 4.)

e::float-matrix-?

Type:

Procedure.

Operation:

Is the argument a float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a float matrix. Otherwise, returns #f.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))           ;; ==> a
(e::float-matrix? #t)  ;; ==> #f
(e::float-matrix? a)   ;; ==> #t

e::float-matrix-fill-row-from-vector!

Type:

Procedure.

Operation:

Set the elements of the given row of the given float matrix to the values in the given vector.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Three: The first a float matrix, the second an integer indicating one of its rows (zero-based), and the third a Scheme vector containing data with which to fill the row.

Side Effects:

Overwrites all elements of the given row.

Returned Value:

The given matrix, with the new data loaded.

For Example:

(define a (e::make-float-matrix 2 3))  ;; ==> a
a  ;; ==>
   ;; 0. 0. 0. 
   ;; 0. 0. 0. 
(e::float-matrix-fill-row-from-vector! a 0 '#(1 2 3))
   ;; ==>
   ;; 1. 2. 3.
   ;; 0. 0. 0.

e::float-matrix-fill-from-vector!

Type:

Procedure.

Operation:

Set the elements of the given float matrix to the values in the given vector, which are provided in row-major order.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two: The first a float matrix, the second a Scheme vector containing data with which to fill the matrix, in row-major order.

Side Effects:

Overwrites all elements of the given matrix.

Returned Value:

The given matrix, with the new data loaded.

For Example:

(define a (e::make-float-matrix 2 3))  ;; ==> a
a  ;; ==>
   ;; 0. 0. 0. 
   ;; 0. 0. 0. 
(e::float-matrix-fill-from-vector! a '#(1 2 3 4 5 6))
   ;; ==>
   ;; 1. 2. 3.
   ;; 4. 5. 6.

e::float-matrix-fill-column-from-vector!

Type:

Procedure.

Operation:

Set the elements of the given column of the given float matrix to the values in the given vector.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Three: The first a float matrix, the second an integer indicating one of its columns (zero-based), and the third a Scheme vector containing data with which to fill the column.

Side Effects:

Overwrites all elements of the given column.

Returned Value:

The given matrix, with the new data loaded.

For Example:

(define a (e::make-float-matrix 2 3))  ;; ==> a
a  ;; ==>
   ;; 0. 0. 0. 
   ;; 0. 0. 0. 
(e::float-matrix-fill-column-from-vector! a 0 '#(1 2))
   ;; ==>
   ;; 1. 0. 0.
   ;; 2. 0. 0.

e::float-matrix-get-columns

Type:

Procedure.

Operation:

Get the number of columns in the given matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

An exact integer: The number of columns in the matrix.

For Example:

(define a (e::make-float-matrix 2 3))  ;; ==> a
(e::float-matrix-get-columns a)        ;; ==> 3

e::float-matrix-get-element

Type:

Procedure.

Operation:

Get the matrix element at a specified row and column.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Three: The first, a float matrix. The second and third, respectively, the (zero-based) row and column of the matrix element whose value is sought.

Side Effects:

None.

Returned Value:

An inexact real: The matrix element at the given row and column.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6))) ;; ==> a
(e::float-matrix-get-element a 1 2)                               ;; ==> 6.0

e::float-matrix-get-rows

Type:

Procedure.

Operation:

Get the number of rows in the given matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

An exact integer: The number of rows in the matrix.

For Example:

(define a (e::make-float-matrix 2 3))  ;; ==> a
(e::float-matrix-get-rows a)           ;; ==> 2

e::float-matrix-hadamard-product

Type:

Procedure.

Operation:

Calculate a new float matrix, each of whose values is the product of the values in the corresponding locations in the given matrices.

Rationale, Explanation, Excuses:

Useful for machine-learning algorithms.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

A float matrix, each of whose values is the product of the values in the corresponding locations in the given matrices.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 2 2 '#(2 3 4 5)))  ;; ==> b
(e::float-matrix-hadamard-product a b)                         ;; ==>
                                                               ;; 2. 6. 
                                                               ;; 12. 20.

e::float-matrix-identity?

Type:

Procedure.

Operation:

Is the argument an identity float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if,the argument is an identity float matrix. Otherwise, returns #f.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))        ;; ==> a
(define b (e::make-float-matrix-from-vector 3 3 '#(1 0 0 0 1 0 0 0 1)))  ;; ==> b
(define c (e::make-float-matrix-from-vector 3 3 '#(1 1 0 0 1 0 0 0 1)))  ;; ==> c

(e::float-matrix-identity? #t)  ;; ==> #f
(e::float-matrix-identity? a)   ;; ==> #f
(e::float-matrix-identity? b)   ;; ==> #t
(e::float-matrix-identity? c)   ;; ==> #f

e::float-matrix-invert

Type:

Procedure.

Operation:

Invert the given matrix, if possible. Report an error if its determinant is zero.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

The inverse of the given matrix.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(2 2 1 2)))  ;; ==> a
(e::float-matrix-invert a)                                     ;; ==>
                                                               ;; 1. -1.
                                                               ;; =0.5 1.

e::float-matrix-multiply

Type:

Procedure.

Operation:

Multiply the given matrices.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

Returns a new float matrix which is the product of the given matrices.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 3 2 '#(2 3 4 5 6 7)))  ;; ==> b
(e::float-matrix-multiply a b)                                     ;; ==>
                                                                   ;; 28. 34.
                                                                   ;; 64. 79.

e::float-matrix-multiply-by-scalar

Type:

Procedure.

Operation:

Multiply the given matrix by the given scalar.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two: The first a float matrix, the second a real number.

Side Effects:

None.

Returned Value:

A new float matrix, which is the product of the given matrix and the given scalar.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(e::float-matrix-multiply-by-scalar a 2)                       ;; ==>
                                                               ;; 2. 4.
                                                               ;; 6. 8.

e::float-matrix-normalize

Type:

Procedure.

Operation:

Calculate a new matrix, each of whose elements is the corresponding element of the given matrix divided by the root-sum-square of all elements in the given matrix.

Rationale, Explanation, Excuses:

Useful if the given matrix is a mathematical vector; that is, if either its row number or its column number is one.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

A new float matrix, each of whose elements is the corresponding element of the given matrix divided by the root-sum-square of all elements in the given matrix.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(e::float-matrix-normalize a)                                  ;; ==>
    0.18257418583505536 0.36514837167011072 
    0.5477225575051661 0.7302967433402214

e::float-matrix-product-of-diagonals

Type:

Procedure.

Operation:

Multiply together all the diagonal elements of the given matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

An inexact real: The product of the diagonal elements of the matrix.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(e::float-matrix-product-of-diagonals a)                       ;; ==> 4.

e::float-matrix-set-element!

Type:

Procedure.

Operation:

Change one element of the given matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Four: First, the float matrix whose element is to be changed; Second and third, the (zero-based) row and column of the element to be changed; Fourth, the new value of that element.

Side Effects:

Alters the given float matrix.

Returned Value:

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
a                                                              ;; ==>
                                                               ;; 1. 2.
                                                               ;; 3. 4.
(e::float-matrix-set-element! a 1 1 42)                        ;; ==> a
a                                                              ;; ==>
                                                               ;; 1. 2.
                                                               ;; 3. 42.

e::float-matrix-square?

Type:

Procedure.

Operation:

Is the argument a square float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a square float matrix. Returns #f otherwise.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))           ;; ==> a
(define b (e::make-float-matrix-from-vector 3 3 '#(1 0 0 0 2 0 0 0 3)))     ;; ==> b
(define c (e::make-float-matrix-from-vector 3 3 '#(0 1 2 -1 0 3 -2 -3 0)))  ;; ==> c

(e::float-matrix-square? #t)  ;; ==> #f
(e::float-matrix-square? a)   ;; ==> #f
(e::float-matrix-square? b)   ;; ==> #t
(e::float-matrix-square? c)   ;; ==> #t

e::float-matrix-subtract

Type:

Procedure.

Operation:

Subtract float matrices.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

Two float matrices.

Side Effects:

None.

Returned Value:

Returns a new float matrix which is the second argument subtracted from the first.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(3 6 9 12 15 18)))  ;; ==> a
(define b (e::make-float-matrix-from-vector 2 3 '#(2 4 6  8 10 12)))  ;; ==> b

(e::float-matrix-subtract a b)  ;; ==>
                                ;; 1. 2. 3.
                                ;; 4. 5. 6.

e::float-matrix-symmetric?

Type:

Procedure.

Operation:

Is the argument a symmetric float matrix?

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a symmetric float matrix. Returns #f otherwise.

For Example:

(define a (e::make-float-matrix-from-vector 2 3 '#(1 2 3 4 5 6)))           ;; ==> a
(define b (e::make-float-matrix-from-vector 3 3 '#(5 2 2 1 8 3 2 3 13)))    ;; ==> b
(define c (e::make-float-matrix-from-vector 3 3 '#(5 1 2 1 8 3 2 3 13)))    ;; ==> c

(e::float-matrix-symmetric? #t)  ;; ==> #f
(e::float-matrix-symmetric? a)   ;; ==> #f
(e::float-matrix-symmetric? b)   ;; ==> #f
(e::float-matrix-symmetric? c)   ;; ==> #t

e::float-matrix-trace

Type:

Procedure.

Operation:

Calculate the trace of the given float matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

An inexact real: The trace of the matrix.

For Example:

(define a (e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==> a
(e::float-matrix-trace a)                                      ;; ==> 5.

e::float-matrix-transpose

Type:

Procedure.

Operation:

Calculate the transpose of the given float matrix.

Rationale, Explanation, Excuses:

Generally useful.

Arguments:

One float matrix.

Side Effects:

None.

Returned Value:

Returns a new float matrix which is the transpose of the argument.

For Example:

(define a (e::make-float-matrix-from-vector 3 3
             '#(1 2 3
                4 5 6
                7 8 9)))      ;; ==> a
(e::float-matrix-transpose a) ;; ==>
                              ;; 1. 4. 7. 
                              ;; 2. 5. 8.
                              ;; 3. 6. 9.

e::float-matrix-transpose-square-matrix!

Type:

Procedure.

Operation:

Transpose the given matrix.

Rationale, Explanation, Excuses:

Useful to reduce Scheme main memory use when the un-transposed matrix is no longer needed.

Arguments:

One square float matrix.

Side Effects:

Modifies the given float matrix: Turns it into its transpose.

Returned Value:

The given matrix, after being transposed.

For Example:

(define a (e::make-float-matrix-from-vector 3 3
             '#(1 2 3
                4 5 6
                7 8 9)))                     ;; ==> a
a                                            ;; ==>
                                             ;; 1. 2. 3. 
                                             ;; 4. 5. 6.
                                             ;; 7. 8. 9. 
(e::float-matrix-transpose-square-matrix! a) ;; ==>
                                             ;; 1. 4. 7. 
                                             ;; 2. 5. 8.
                                             ;; 3. 6. 9.

e::forced?

Type:

Procedure.

Operation:

Test whether a promise has been forced.

Rationale, Explanation, Excuses:

In case the evaluation of a promise causes side effects, it may be useful to determine whether or not that evaluation has already taken place.

Recall that the result of forcing a promise the first time is cached, so that subsequent forces of the same promise cause no additional evaluation.

Arguments:

One promise.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument has been forced. Otherwise, returns #f.

For Example:

(define a (delay (+ 2 2)))  ;; ==> a
(e::forced? a)              ;; ==> #f
(force a)                   ;; ==> 4
(e::forced? a)              ;; ==> #t

e::forgettable?

Type:

Procedure.

Operation:

Test whether its argument is a forgettable object.

Rationale, Explanation, Excuses:

Predicate to identify object of this type.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a forgettable object. Returns #f otherwise.

For Example:

(e::forgettable? (e::make-forgettable #t 0 0))  ;; ==> #t
(e::forgettable? #t)                            ;; ==> #f

e::forgettable-expiration-time

Type:

Procedure.

Operation:

Retrieve a the expiration time of a Scheme object that has been made forgettable.

Rationale, Explanation, Excuses:

Primitive required to access the content of forgettable objects.

Arguments:

One forgettable object.

Side Effects:

None.

Returned Value:

Multiple-values return: The first item is a boolean indicating whether the forgettable object has not been forgotten; that is, it is #t if the forgettable object is remembered or unexpired and #f if the forgettable object has been forgotten. The second item is the expiration time that was provided for the object. The second value is returned even if the object has expired.

For Example:

(e::forgettable-expiration-time (e::make-forgettable "foo" 5000000000 0.6))  ;; ==> 
    ;; #<Multiple Values Return>
    ;; List of values: (#t #e5.e9)

e::forgettable-forgotten?

Type:

Procedure.

Operation:

Test whether its argument is a forgettable object that has been forgotten.

Rationale, Explanation, Excuses:

Predicate to identify object of this type.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a forgettable object that has been forgotten. Returns #f otherwise.

For Example:

(define foo (e::make-forgettable #t 0 0))  ;; ==> foo
(e::forgettable-forgotten? foo)  ;; ==> #f
     ;; The forgettable object is created in the "unexpired" state;
     ;;  it has not yet been forgotten, even though it is past its
     ;;  expiration time and the probability of remembering is zero.
(e::full-gc)                     ;;  During garbage collection, foo becomes expired.
(e::forgettable-forgotten? foo)  ;; ==> #t

(e::forgettable-forgotten? #t)   ;; ==> #f

e::forgettable-object

Type:

Procedure.

Operation:

Retrieve a reference or copy of a Scheme object that has been made forgettable.

Rationale, Explanation, Excuses:

Primitive required to access the content of forgettable objects.

Arguments:

One forgettable object.

Side Effects:

None.

Returned Value:

Multiple-values return: The first item is a boolean indicating whether the forgettable object has not been forgotten; that is, it is #t if the forgettable object is remembered or unexpired and #f if the forgettable object has been forgotten. The second item is the object that has been made forgettable, if it has not been forgotten (that is, if the first item is #t), or undefined, if that object has been forgotten.

If the object made forgettable was not an atom, then the reference to it returned by this procedure is sufficient to prevent the forgettable object itself from being forgotten, as long as that reference remains non-garbage. If the object made forgettable was an atom, then what is returned is not the actual object but a copy of it; no reference exists, and the forgettable object is given no additional protection against being forgotten.

It is not particularly useful to make atoms forgettable.

Wraith Scheme provides the procedure e::atom? to determine what kinds of objects are atoms.

For Example:

(e::forgettable-object (e::make-forgettable "foo" 5000000000 0.6))  ;; ==> 
    ;; #<Multiple Values Return>
    ;; List of values: (#t "foo")

e::forgettable-remembered?

Type:

Procedure.

Operation:

Test whether its argument is a forgettable object that has been remembered.

Rationale, Explanation, Excuses:

Predicate to identify object of this type.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a forgettable object that has been remembered. Returns #f otherwise.

For Example:

(define foo (e::make-forgettable #t 0 1))  ;; ==> foo
(e::forgettable-remembered? foo)  ;; ==> #f
     ;; The forgettable object is created in the "unexpired" state;
     ;;  it has not yet been remembered, even though it is past its
     ;;  expiration time and the probability of remembering is one.
(e::full-gc)                     ;;  During garbage collection, foo becomes expired.
(e::forgettable-remembered? foo)  ;; ==> #t

(e::forgettable-remembered? #t)   ;; ==> #f

e::forgettable-remember-probability

Type:

Procedure.

Operation:

Retrieve a the probability of remembering a Scheme object that has been made forgettable.

Rationale, Explanation, Excuses:

Primitive required to access the content of forgettable objects.

Arguments:

One forgettable object.

Side Effects:

None.

Returned Value:

Multiple-values return: The first item is a boolean indicating whether the forgettable object has not been forgotten; that is, it is #t if the forgettable object is remembered or unexpired and #f if the forgettable object has been forgotten. The second item is the expiration time that was provided for the object, if the forgettable object has not been forgotten (that is, if the first item is #t), and is undefined if the forgettable object has been forgotten.

For Example:

(e::forgettable-remember-probability (e::make-forgettable "foo" 5000000000 0.6))  ;; ==> 
#<Multiple Values Return>
List of values: (#t 0.6)

e::forgettable-unexpired?

Type:

Procedure.

Operation:

Test whether its argument is a forgettable object that has been unexpired.

Rationale, Explanation, Excuses:

Predicate to identify object of this type.

Arguments:

One Scheme object of any kind.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a forgettable object that has been unexpired. Returns #f otherwise.

For Example:

(define foo (e::make-forgettable #t 1000000000000 0))  ;; ==> foo
(e::forgettable-unexpired? foo)  ;; ==> #t
     ;; The forgettable object is created in the "unexpired" state.
(e::full-gc)                     ;;  The object will not expire until the distant future;
                                 ;;  it remains unexpired after garbage collection.
(e::forgettable-unexpired? foo)  ;; ==> #t

(e::forgettable-unexpired? #t)   ;; ==> #f

e::full-gc

Type:

Procedure.

Operation:

Cause garbage collection.

Rationale, Explanation, Excuses:

Garbage collection happens automatically, when Wraith Scheme's current main memory is about to fill up. It may be useful to force it; for example, when about to measure code speed, or when a time-consuming interruption of a process controlled by Wraith Scheme would be unfortunate ...

Computer: Captain! CAPTAIN!! Klingons close on the port bow!

Captain James T. Schemer: Shields up! Fire photon torpedoes!

Computer: Just a few minutes while I garbage-collect. Be patient ...

Arguments:

None.

Side Effects:

None.

Returned Value:

For Example:

(e::full-gc)  ;;  Wraith Scheme garbage collects.
              ;; ==> #t

e::gensym

Type:

Procedure.

Operation:

Generate a symbol that has no value or binding.

This operation is atomic, in the sense that even if many Wraith Scheme procedures call "e::gensym", even at the same time, every gensym'd value returned will be unique.

Rationale, Explanation, Excuses:

Gensym'd symbols are useful for various kinds of software that needs "scratch" labels for things.

The symbols created by "e::gensym" are of the general form "gNNNNN...", where the N's constitute the external representation of a positive integer greater than or equal to 23000. The value of "NNNNN..." will be congruent to the kitten number of the Wraith Scheme process that called "e::gensym", modulo the maximum possible number of kittens: That constraint provides a different set of gensym symbols for each kitten, and so allows more than one kitten to use the "gensym" mechanism at the same time with no possibility that two kittens will inadvertently create the same symbol.

I chose to use these particular gensym symbols in memory of Ratfor (rational Fortran), which generated symbols of the same form.

The procedure will check each generated symbol before returning; if the symbol it generates already happens to have a value or a binding, it will choose another; that is, the user is free to use symbols of the form "gNNNNN..." without worrying about conflict with symbols generated by "e::gensym".

Arguments:

None.

Side Effects:

None.

Returned Value:

A symbol: Returns a symbol that had no value or binding when it was generated.

For Example:

(e::gensym)  ;; ==> g23000

e::get-tag

Type:

Procedure.

Operation:

Obtain the 64-bit tag portion of the Wraith Scheme tagged aval associated with a Wraith Scheme object.

Rationale, Explanation, Excuses:

This procedure provides a low-level view of part of the structure of Wraith Scheme objects. I implemented it to aid in debugging Wraith Scheme.

I am reluctant to document what the tag bits mean because their meaning will almost certainly change from release to release. Send me EMail if you really want to know.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

An integer: Returns the tag associated with the argument.

For Example:

(e::get-tag 42)  ;; ==> 57  ;;  #b111001

e::hide-sense-lights!

Type:

Procedure.

Operation:

Hides the Wraith Scheme sense lights, without changing their illumination state; that is, if you subsequently make the sense lights visible, they will appear the way you last set them. Affects only the sense lights of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Useful for controlling the Wraith Scheme sense lights.

Arguments:

None.

Side Effects:

Makes all of the Wraith Scheme sense lights invisible.

Returned Value:

For Example:

(e::hide-sense-lights!)        ;; ==> #t, and makes the sense lights invisible.

e::inf?

Type:

Procedure.

Operation:

Test whether a Scheme object is an "inf" -- a special flonum value used to represent an infinity. (More commonly, used to represent the result of a calculation that has overflowed the allowed range of flonums.) Also returns #t if the object is a rational whose numerator and denominator are stored separately, when the denominator is zero and the numerator is not.

Rationale, Explanation, Excuses:

Wraith Scheme uses IEEE floating-point numbers, which have infs and nans, so it is useful to be able to test for their presence.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an inf (of any sign), or if it is a rational whose numerator and denominator are stored separately, when the denominator is zero and the numerator is not. Otherwise, returns #f.

For Example:

(e::inf? #t)          ;; ==> #f
(e::inf? 3)           ;; ==> #f
(e::inf? 1.e10000)    ;; ==> #t
(e::inf? 1+1.e1000i)  ;; ==> #t
(e::inf? 1/0)         ;; ==> #t

e::inspect

Type:

Procedure.

Operation:

Report a useful selection of information about the low-level structure of a Wraith Scheme object.

Rationale, Explanation, Excuses:

I installed this procedure primarily for debugging Wraith Scheme. It is also useful for satisfying one's curiosity about what Wraith Scheme is doing.

"e::inspect" returns its argument. Thus you may wrap "(e::inspect ...)" around basically any Scheme object, anywhere, to print out useful information, without interrupting the flow of calculation at the point where the object is used.

The first line of output from "e::inspect" is generally the numeric values of the Wraith Scheme tagged aval that represents it, with the 64-bit tag separated from the 64-bit value by a dash. The numbers will be printed in hexadecimal, and will be followed by information about the cdr-coding (if any) of the object.

"e::inspect" is capable of printing lots of output, such as the entire source code or compiled code of a lambda expression or macro. The volume of printout is thus affected by the settings of the print-length and print-depth variables for lists and for vectors. Set these quantities to large numbers if you want to see all of the output from "e::inspect".

Arguments:

Any Scheme object.

Side Effects:

None.

Returned Value:

Any Scheme object: "e::inspect" returns its argument.

For Example:

;;  Hexadecimal output will vary ...

(e::inspect 42)        ;; ==>
0039-0000002a: Exact Short Fixnum -- Not a Car
42

(e::inspect define)    ;; ==>
(e::inspect define)
000a-1b7bfe34: Macro -- Not a Car
(lambda (form)
  (c::if (list? form)  ;; ... lots more output.
#<Macro>

;; When there is more than one Wraith Scheme process active, e::inspect will
;; also print out the number of the kitten in which it was called. Thus,
;; assuming that someone somewhere has defined "foo" to be eleven, then
;; using e::inspect to investigate it on kitten two will yield ...

(e::inspect foo)       ;; ==>
0000000000000039-000000000000000b: Exact Short Fixnum -- Not a Car (Kitten 2)
11

e::inspect-world

Type:

Procedure.

Operation:

Provide a lengthy human-readable description of the contents of a Wraith Scheme world file.

Rationale, Explanation, Excuses:

I implemented this procedure for debugging Wraith Scheme's mechanisms for loading and storing worlds.

WARNING: Wraith Scheme does a poor job of identifying world files. Using "e::inspect-world" with a file that is not actually a Wraith Scheme world file may cause Wraith Scheme to crash.

Caution: A very large world file may cause this procedure to produce hundreds of GBytes of text output -- or at least to try to do so -- and there is no way to preselect just part of it: When I use "e::inspect-world" for debugging, I use small world files.

Arguments:

At most one: If there is an argument, it should be a string containing a Unix-style path to a Wraith Scheme world file; if there is no argument, Wraith Scheme will use the Dialog Panel to obtain a path.

Side Effects:

None.

Returned Value:

For Example:

(e::inspect-world "<the default Wraith Scheme world>")
    ;; ==> ;; Lots of output

;; If you would like to see what a world file dump
;; looks like, use the Wraith Scheme Instrument Panel
;; to obtain the path to the standard Wraith Scheme world
;; -- the default one that gets loaded when Wraith Scheme
;; is launched, and try "e::inspect-world" with that one.

(e::inspect-world)  ;; Wraith Scheme uses Dialog Panel 
                    ;;   to obtain a path to the file
                    ;;   to be inspected.
    ;; ==> #t

e::interrupt-file-information

Type:

Procedure.

Operation:

Obtain the pathname for the file used to memory-map Wraith Scheme's interrupt flags and Unix process identifications, and its size.

Rationale, Explanation, Excuses:

Part of the mechanism for allowing Wraith Scheme to deal with to "SIGUSR1" Unix software interrupts.

Arguments:

None.

Side Effects:

None.

Returned Value:

Multiple-values return: The first item is a string containing the full absolute pathname of the file used to memory-map Wraith Scheme's interrupt flags and Unix process identifications, the second item is the size of that file in bytes.

For Example:

(e::interrupt-file-information)
  ;; ==> #<Multiple Values Return>
  ;;      List of values: ("/Users/JayFreeman/Library/Application Support/WraithScheme/Wraith Scheme Interrupt Information" 1088)

e::kitten-number

Type:

Procedure.

Operation:

Return the kitten number of the Wraith Scheme process where called.

Rationale, Explanation, Excuses:

Provides elementary information about parallel instances of Wraith Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: The kitten number of the process in which the procedure was called.

For Example:

(e::kitten-number)  ;; ==> 0  ;; In MomCat
(e::kitten-number)  ;; ==> 7  ;; In kitten 7

e::kitty-color

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, report the color currently in use for drawing in the kitten graphics window of the kitten where the procedure was called.

Rationale, Explanation, Excuses:

Useful for kitten graphics procedures.

Arguments:

None.

Side Effects:

None.

Returned Value:

An exact integer representing the color used for drawing in the kitten graphics window of the kitten where the procedure was called.

For Example:

(e::kitty-color)  ;; ==> 1, perhaps, which would be red.

e::kitty-color?

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, report whether or not the argument is a number representing a kitty pen color.

Rationale, Explanation, Excuses:

Useful for kitten graphics procedures.

Arguments:

One scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an exact integer in the range allowed for kitty pen colors; that is, in the range [0..9]. Otherwise, returns #f.

For Example:

(e::kitty-color? 3)   ;; ==> #t
(e::kitty-color? 10)  ;; ==> #f
(e::kitty-color? #t)  ;; ==> #f

e::kitty-come-home

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, reposition the kitty to her home position and orientation, which is in the middle of the drawing area of the Wraith Scheme Kitten Graphics Window, facing upward.

This operation may also be performed by pressing the "Kitty Come Home" button, located near the lower right corner of the Wraith Scheme Kitten Graphics Window.

If you perform this operation by pushing the button, and the kitty is in motion when you do so, the motion will not stop: It is possible that the kitty will move away immediately. To stop the kitty, you must reset Wraith Scheme to top level.

This operation works whether the kitty is visible or not, and does not change the visibility of the kitty, only her location.

The kitty does not draw anything during her journey homeward.

Rationale, Explanation, Excuses:

Repositions and reorients the pen of the drawing system to a known state. This operation is particularly useful if the kitty has somehow escaped from the drawing area of the Wraith Scheme Kitten Graphics Window.

Arguments:

None.

Side Effects:

Repositions the kitty.

Returned Value:

For Example:

(e::kitty-come-home)  ;; ==> Moves the kitty to the center of the drawing area, facing up.

e::kitty-erase-drawing

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, erase the entire drawing.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

None.

Side Effects:

Erases the drawing.

Returned Value:

For Example:

(e::kitty-erase-drawing)  ;; ==> Erases the drawing.

e::kitty-forward

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, move the kitty forward the number of points (Macintosh screen coordinates) that is the argument. With an argument that is a negative number, move the kitty backward.

The kitty will draw a line during this operation if, and only if, the pen is down.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

One real number, taken to be the number of points for the kitty to move. Positive numbers cause the kitty to move forward; negative numbers cause the kitty to back up.

Side Effects:

Moves the kitty. If the pen is down, draws a line.

Returned Value:

For Example:

(e::kitty-forward 40)  ;; ==> Moves the kitty forward 50 points.
                       ;;    If the pen is down, draws a line.

e::kitty-heading

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, retrieve the kitty's heading -- the direction in which she is facing. Headings are measured in degrees, in the range [0 .. 360). A heading of 0 corresponds to the kitty facing straight up. Headings increase clockwise; thus for example, a heading of 90 corresponds to the kitty facing to the right.

Rationale, Explanation, Excuses:

Basic drawing instrumentation.

Arguments:

None.

Side Effects:

None.

Returned Value:

A real number: The kitty heading, in degrees.

For Example:

(e::kitty-heading)  ;; ==> The kitty heading, e.g., "45" ...

e::kitty-hide

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, make the kitty invisible.

This operation may also be performed by pressing the "Hide Kitty" button, located near the lower right corner of the Wraith Scheme Kitten Graphics Window. That button has the title "Hide Kitty" when the kitty is visible, and "Show Kitty" when the kitty is invisible.

The kitty's ability to draw has nothing to do with whether she is visible or not. The kitty will draw whenever the pen is down, without regard to her visibility.

Rationale, Explanation, Excuses:

Useful for seeing the drawing without the kitty getting in the way.

Arguments:

None.

Side Effects:

Hides the kitty.

Returned Value:

For Example:

(e::kitty-hide)  ;; ==> Hides the kitty.

e::kitty-left

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, make the kitty turn left by the number of degrees which is its argument. Negative numbers make the kitty turn right.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

A real number, taken to be the number of degrees to the left that the kitty is to turn.

Side Effects:

Changes kitty orientation.

Returned Value:

For Example:

(e::kitty-left 90)  ;; ==> Kitty makes a ninety-degree turn to the left.

e::kitty-line-width

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, report the line width currently in use for drawing.

Rationale, Explanation, Excuses:

Useful for kitten graphics procedures.

Arguments:

None.

Side Effects:

None.

Returned Value:

A real number: The current width of lines that will be drawn, in points (Macintosh screen coordinate units).

For Example:

(e::kitty-line-width)  ;; ==> 1, e.g. (which is the default).

e::kitty-line-width?

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, report whether or not the argument is a number representing a line width permitted for drawing.

Rationale, Explanation, Excuses:

Useful for kitten graphics procedures.

Arguments:

One scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is an exact real in the range allowed for kitty line widths; that is, in the range [0..10]. Otherwise, returns #f.

For Example:

(e::kitty-line-width? 3)   ;; ==> #t
(e::kitty-line-width? 10)  ;; ==> #f
(e::kitty-line-width? #t)  ;; ==> #f

e::kitty-pen-down

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, tell the kitty to start drawing. The kitty will continue drawing until advised otherwise, except when she is being brought home by the "e::kitty-come-home" operation.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

None.

Side Effects:

Puts the kitty in a state in which lines will be drawn when she moves.

Returned Value:

For Example:

(e::kitty-pen-down)  ;; ==> Kitty starts drawing.

e::kitty-pen-down?

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, report whether or not the kitty is drawing; that is, whether or not the pen is down.

Rationale, Explanation, Excuses:

Useful for kitten graphics procedures.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the pen is down. Otherwise, returns #f.

For Example:

(e::kitty-pen-down?)  ;; ==> Kitty starts drawing.

e::kitty-pen-up

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, tell the kitty to stop drawing. The kitty will do no further drawing until advised otherwise.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

None.

Side Effects:

Puts the kitty in a state in which nothing will be drawn when she moves.

Returned Value:

For Example:

(e::kitty-pen-up)  ;; ==> Kitty stops drawing.

e::kitty-right

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, make the kitty turn right by the number of degrees which is its argument. Negative numbers make the kitty turn left.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

A real number, taken to be the number of degrees to the right that the kitty is to turn.

Side Effects:

Changes kitty orientation.

Returned Value:

For Example:

(e::kitty-right 45)  ;; ==> Kitty turns forty-five degrees to the right.

e::kitty-set-color

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, change the color with which lines will be drawn. This operation does not change whether the pen is up or down, and does not change the color of any lines that have already been drawn.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

One exact integer, representing the line color to be used.

Line colors are represented by exact integers, as follows:

0 -- white
1 -- red
2 -- orange
3 -- yellow
4 -- green
5 -- cyan
6 -- magenta
7 -- black
8 -- blue
9 -- purple

The reason for the rather odd order of colors is so that the same numbers may be used for sense light colors as for line colors, with similar result. Wraith Scheme sense lights predate Wraith Scheme kitten graphics, and only the integers [0..7] are used for sense light colors.

Side Effects:

Changes the color of subsequent lines.

Returned Value:

For Example:

(e::kitty-set-color 6)  ;; ==> Future lines will be drawn in magenta.

e::kitty-set-line-width

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, change the width of lines to be drawn. This operation does not change whether the pen is up or down, and does not change the width of any lines that have already been drawn.

Rationale, Explanation, Excuses:

Basic drawing primitive.

Arguments:

One exact real number not less than zero and not greater than ten, representing the line width in points (Macintosh screen coordinates) to use for drawing.

Side Effects:

Changes the width of subsequent lines.

Returned Value:

For Example:

(e::kitty-set-line-width #e6.5)  ;; ==> Future lines will have a width of 6.5 points.

e::kitty-show

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, make the kitty visible.

This operation may also be performed by pressing the "Show Kitty" button, located near the lower right corner of the Wraith Scheme Kitten Graphics Window. That button has the title "Show Kitty" when the kitty is invisible, and "Hide Kitty" when the kitty is visible.

The kitty's ability to draw has nothing to do with whether she is visible or not. The kitty will draw whenever the pen is down, without regard to her visibility.

Rationale, Explanation, Excuses:

Useful as a visual cue of pen location and orientation.

Arguments:

None.

Side Effects:

Shows the kitty.

Returned Value:

For Example:

(e::kitty-show)  ;; ==> Shows the kitty.

e::kitty-x

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, retrieve the x coordinate of the kitty's position, measured in points (Macintosh screen coordinates). The x coordinate axis is horizontal. The x coordinate increases to the right, and is zero at the lower left corner of the drawing area of the Wraith Scheme Kitten Graphics Window.

Rationale, Explanation, Excuses:

Basic drawing instrumentation.

Arguments:

None.

Side Effects:

None.

Returned Value:

A real number: The kitty x coordinate, in points.

For Example:

(e::kitty-x)  ;; ==> The kitty x coordinate, e.g., "25.0617".

e::kitty-y

Type:

Procedure.

Operation:

In the Wraith Scheme Kitten Graphics system, in the kitten graphics window of the kitten where the procedure was called, retrieve the y coordinate of the kitty's position, measured in points (Macintosh screen coordinates). The y coordinate axis is vertical. The y coordinate increases upward, and is zero at the lower left corner of the drawing area of the Wraith Scheme Kitten Graphics Window.

Rationale, Explanation, Excuses:

Basic drawing instrumentation.

Arguments:

None.

Side Effects:

None.

Returned Value:

A real number: The kitty y coordinate, in points.

For Example:

(e::kitty-y)  ;; ==> The kitty y coordinate, e.g., "42.137".

e::list-print-depth

e::list-print-length

e::set-list-print-depth!

e::set-list-print-length!

e::set-vector-print-depth!

e::set-vector-print-length!

e::vector-print-depth

e::vector-print-length

Type:

Procedures.

Operation:

Get and set internal variables used to control printing of large data structures.

Rationale, Explanation, Excuses:

Printing a circularly-linked data structure is a task that does not end. To help avoid such conditions, Wraith Scheme uses four internal variables to control how many elements of lists and vectors are printed, and to control how deep nested lists and vectors are printed.

The variables are not accessible by name; procedures are used to set and obtain their values, but for purposes of discussion, let us imagine that they are called:

list-print-depth list-print-length vector-print-depth vector-print-length

Current values of all these variables are displayed in the Wraith Scheme Instrument Panel.

When a list is longer than the value of "list-print-length", the print routines use an ellipsis to indicate the "extra" elements. Thus if "list-print-length" is 6, a list might print as:

(foo bar baz frob quux mumble ...)

and similarly for vectors.

When lists are nested more deeply than the value of "list-print-depth", the print routines use an ellipsis to indicate the "extra" elements. Thus if "list-print-depth" is 6, a deeply-nested list might print as:

(((((((...)))))))

Two caveats apply to the use of these internal variables:

If you are dealing with long or deep data structures, using values of the print-controlling variables that are too small may deprive you of your chance to look at the data. When doing lengthy calculations that result in long printouts, be sure to save what is going to be printed in some handy variable, which you can print again once you have set the print-controlling variables to more appropriate values.
These variables catch many cases of infinite-loop printouts, but not all. The "Reset to Top-Level Loop" command, from the Wraith Scheme Interpreter Menu, will probably stop any such loop.

Arguments:

The "set" procedures: An integer no less than three.

The other procedures: None.

Side Effects:

None.

Returned Value:

The "set" procedures: #t.

The other procedures: An integer: Return the present value of the indicated special variable.

For Example:

(e::list-print-length)          ;; ==> 20  ;;  The default.
(list 1 2 3 4)                  ;; ==> (1 2 3 4)

(e::set-list-print-length!  3)  ;; ==> #t
(list 1 2 3 4)                  ;; ==> (1 2 3 ...)

e::load-and-export-to-calling-environment

Type:

Procedure.

Operation:

Load a "package" and export some of its definitions into the calling environment. The package is represented by a file of Scheme code: Any file which could be loaded in the regular manner, by the regular “load” command, will do. All bindings that it creates (e.g., by the use of define) are hidden in a special environment, and are not visible at top level, or in the calling environment, or in any other environment, except for those that are explicitly exported. If procedures in the file being loaded call one another, the relevant bindings are resolved in the hidden environment, so that those procedures work together properly.

Bindings created in the file may be exported with their original names, or with any name you choose to give them.

Rationale, Explanation, Excuses:

A package system is handy, both for keeping the top-level namespace uncluttered and for resolving conflicts between instances of the same name used in different blocks of code.

Arguments:

Two: The first a string providing the path to a file to be loaded, the second a list of "export descriptors" indicating which bindings are to be exported, and under what names.

An export descriptor is either

A symbol, which must be one defined in the file being loaded; its binding will be installed in the calling environment with that original name, or
A list of two symbols, the first defined in the file being loaded, and the second any symbol; the binding of the first symbol will be installed in the calling environment with the name indicated by the second symbol.

Side Effects:

Depends on the content of the file, and on the arguments to the procedure.

Returned Value:

For Example:

;;  Suppose the file "PackageCode.s" contains the following:

(define (foo123) (bar456 1))
(define (bar456 x) (baz789 x))
(define (baz789 x) (display "This is baz789\n") (display x)(newline))

;; Then the top-level command sequence

(define foo123 #t)
(define bar456 #t)
(define baz789 #t)
((lambda () 
   (e::load-and-export-to-calling-environment "PackageCode.s" '(foo123 (bar456 bar)))
   (foo123)
   (bar 1)))
foo123
bar456
baz789


;; will produce the following (showing the output separate from the input for clarity):
;; (Note that the procedure itself produces several lines of output messages.)

;; These from the original defines of foo123, bar456, and baz789:

foo123
bar456
baz789

;; These from e::load-and-export-to-calling-environment:

Loading from file "PackageCode.s" ...
foo123
bar456
baz789
Starting to process and export symbols ...
Exporting foo123.
Exporting bar456 as bar.
Exported: (foo123 bar)
#t

;; These from evaluating (foo123) and (baz) in the calling environment:

This is baz789
1
#t
This is baz789
1
#t

;; These from evaluating the symbols foo123, bar456 and baz789 in the top-level environment:
;; (Note that the original top-level definitions have not been overwritten.)

#t
#t
#t

e::load-and-export-to-top-level

Type:

Procedure.

Operation:

Load a "package" and export some of its definitions into the top-level environment. The package is represented by a file of Scheme code: Any file which could be loaded in the regular manner, by the regular “load” command, will do. All bindings that it creates (e.g., by the use of define) are hidden in a special environment, and are not visible at top level or in any other environment, except for those that are explicitly exported. If procedures in the file being loaded call one another, the relevant bindings are resolved in the hidden environment, so that those procedures work together properly.

Bindings created in the file may be exported with their original names, or with any name you choose to give them.

Rationale, Explanation, Excuses:

A package system is handy, both for keeping the top-level namespace uncluttered and for resolving conflicts between instances of the same name used in different blocks of code.

Arguments:

Two: The first a string providing the path to a file to be loaded, the second a list of "export descriptors" indicating which bindings are to be exported, and under what names.

An export descriptor is either

A symbol, which must be one defined in the file being loaded; its binding will be installed in the top-level environment with that original name, or
A list of two symbols, the first defined in the file being loaded, and the second any symbol; the binding of the first symbol will be installed in the top-level environment with the name indicated by the second symbol.

Side Effects:

Depends on the content of the file, and on the arguments to the procedure.

Returned Value:

For Example:

;;  Suppose the file "PackageCode.s" contains the following:

(define (foo123) (bar456 1))
(define (bar456 x) (baz789 x))
(define (baz789 x) (display "This is baz789\n") (display x)(newline))

;; Then the top-level command sequence

(define foo123 #t)
(define bar456 #t)
(define baz789 #t)
(e::load-and-export-to-top-level "PackageCode.s" '(foo123 (bar456 bar)))
(foo123)
(bar 1)
foo123
bar456
baz789

;; will produce the following (showing the output separate from the input for clarity):
;; (Note that the procedure itself produces several lines of output messages.)

;; These from the original defines of foo123, bar456, and baz789:

foo123
bar456
baz789

;; These from e::load-and-export-to-top-level:

Loading from file "PackageCode.s" ...
foo123
bar456
baz789
Starting to process and export symbols ...
Exporting foo123.
Exporting bar456 as bar.
Exported: (foo123 bar)
#t

;; These from evaluating (foo123) and (baz) in the top-level environment:

This is baz789
1
#t
This is baz789
1
#t

;; These from evaluating foo123, bar456 and baz789 in the top-level environment:
;; (Note that the original top-level definitions of bar456 and baz789
;; have not been overwritten.)

#<Interpreted lambda expression, possibly named "foo123">
#t
#t

e::load-world!

Type:

Procedure.

Operation:

Load a Wraith Scheme world file.

Only the MomCat may perform this procedure; calling this procedure in any other Wraith Scheme process will cause an error.

Rationale, Explanation, Excuses:

A world file is a machine-readable image of the entire content of Wraith Scheme main memory. Storing one saves the what you were working on in Wraith Scheme so that you may resume work in another session. Loading one restores that saved work.

Arguments:

Side Effects:

Overwrites all of Wraith Scheme's main memory.

Returned Value:

Does not apply; after a world load, Wraith Scheme will reset to the top-level loop.

For Example:

(e::load-world! "MyFavoriteWorld")
    ;; ==> ;; Load world and reset.

(e::load-world)  ;; Wraith Scheme uses Dialog Panel 
                 ;;   to obtain a path to the file
                 ;;   to be used.
    ;; ==> #t

e::logic-constant?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "logic constant" -- one of "#u" and "#s".

Rationale, Explanation, Excuses:

This procedure is for logic programming along the lines described in Daniel P. Friedman, William E. Byrd and Oleg Kiselyov, The Reasoned Schemer, MIT Press, 2005. Wraith Scheme provides the logic constants #u and #s.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is either #u or #s. Otherwise, returns #f.

For Example:

(e::logic-constant? #t)  ;; ==> #f
(e::logic-constant? #u)  ;; ==> #t
(e::logic-constant? #s)  ;; ==> #t

e::long-complex?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "long complex" -- a complex number with nonzero imaginary part.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of complex numbers, in which the real and imaginary parts are stored separately.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a complex number with nonzero imaginary part. Otherwise, returns #f.

For Example:

(e::long-complex? 1+i)  ;; ==> #t
(e::long-complex? 3)    ;; ==> #f
(e::long-complex? #t)   ;; ==> #f

e::long-ratnum?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "long ratnum" -- a rational number in which the numerator and denominator are stored separately.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a rational number in which the numerator and denominator are stored separately. Otherwise, returns #f.

For Example:

(e::long-ratnum? 1/3)  ;; ==> #t
(e::long-ratnum? 3.2)  ;; ==> #f
(e::long-ratnum? #t)   ;; ==> #f

e::macro

Type:

Operation:

Create a Wraith Scheme low-level macro, and make it be the value of a symbol.

Rationale, Explanation, Excuses:

The macros referred to are Wraith Scheme's low-level internal implementation, not the hygienic macros defined in the R5 report.

A "call" or invocation of a Wraith Scheme macro involves using a procedure that was created when the macro was defined, to transform the expression in which the macro call occurred, into something else. That "something else" is evaluated by Wraith Scheme, to produce the result of the macro "call".

"e::macro" creates the procedure in question, makes it part of a Wraith Scheme low-level macro object, and binds that object to a symbol -- the symbol being what we might informally call the macro's "name".

The Wraith Scheme code for a macro "call" is similar to the code for a procedure call: It is a list whose first item evaluates to the macro in question. When Wraith Scheme encounters such an expression, it passes the entire list as an argument to the lambda expression associated with that macro, then further evaluates whatever the lambda expression returns.

The most conventional use of macros is to perform some syntactic transformation on the list which constitutes the macro call, but other uses are certainly possible.

Arguments:

Two: The first, a symbol, and the second, a lambda expression of one argument, which will be passed the entire expression that constitutes a macro "call", when the macro in question is called.

Side Effects:

None.

Returned Value:

A symbol: Returns the first argument.

For Example:

;; Suppose you are tired of writing "set!" and would
;; rather write things like "(assign 3 to foo)".
;; Define this macro:

(e::macro
  assign          ;;  The macro "name".
  (lambda (form)  ;;  form is, e.g., "(assign 3 to foo)"
    ;;  We build up the returned value from
    ;;  a quasiquoted "set!" ...
    `(set!           
      ,(cadddr form)  ;; The cadddr is, e.g., "foo".
      ,(cadr form)))) ;; The cadr is, e.g., "3".

    ;; ==> assign

;; Let's expand a call and see if it works:

(e::expand-macro '(assign 3 to foo))
    ;; ==> (set! foo 3)

;; Looks promising, let's try it.  The
;; "set!" won't work unless "foo" is already
;; defined, so ...

(define foo 0)     ;; ==> foo
foo                ;; ==> 0
(assign 3 to foo)  ;; ==> #t
foo                ;; ==> 3  ;; Yippee!!

e::macro-body

Type:

call-with-current-continuation

Operation:

Create a Wraith Scheme low-level macro, but do not bind it to a symbol.

Rationale, Explanation, Excuses:

The macros referred to are Wraith Scheme's low-level internal implementation, not the macros defined in the R5 report.

"e::macro-body" creates the procedure in question and makes it part of a Wraith Scheme low-level macro object, but does not bind that object to a symbol -- less formally, the object is not given a "name".

The most conventional use of macros is to perform some syntactic transformation on the list which constitutes the macro call, but other uses are certainly possible.

Arguments:

One lambda expression of one argument, which will be passed the entire expression that constitutes a macro "call", when the macro in question is called.

Side Effects:

None.

Returned Value:

A macro.

For Example:

;; Suppose you are tired of writing "set!" and would
;; rather write things like "(assign 3 to foo)".
;; Define this macro:

(define assign            ;;  The macro "name".
  (e::macro-body
    (lambda (form)        ;;  form is, e.g., "(assign 3 to foo)"
      ;;  We build up the returned value from
      ;;  a quasiquoted "set!" ...
      `(set!           
        ,(cadddr form)    ;; The cadddr is, e.g., "foo".
        ,(cadr form)))))  ;; The cadr is, e.g., "3".

    ;; ==> assign

;; Let's expand a call and see if it works:

(e::expand-macro '(assign 3 to foo))
    ;; ==> (set! foo 3)

;; Looks promising, let's try it.  The
;; "set!" won't work unless "foo" is already
;; defined, so ...

(define foo 0)     ;; ==> foo
foo                ;; ==> 0
(assign 3 to foo)  ;; ==> #t
foo                ;; ==> 3  ;; Yippee!!

e::macro?

Type:

Procedure.

Operation:

Test whether a Scheme object is a Wraith Scheme low-level macro.

Rationale, Explanation, Excuses:

The macros referred to are Wraith Scheme's low-level implementation, not the kind defined in the R5 report.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a Wraith Scheme low-level macro. Otherwise, returns #f.

For Example:

(e::macro? define)  ;; ==> #t
(e::macro? cons)    ;; ==> #f

e::main

Type:

Wraith Scheme does not define a value for "e::main"; the intent is, that the symbol "e::main" may be bound to a lambda expression of your choice.

Operation:

Whatever you like.

Rationale, Explanation, Excuses:

The procedure "e::main" is not defined by Wraith Scheme; indeed, the symbol "e::main" does not even exist in the distributed version of Wraith Scheme! It is you who may, if you wish, define "e::main". You may make it be any lambda expression of no arguments that you like.

If you save a world in which "e::main" is a lambda expression of no arguments, then whenever that world is loaded into a Wraith Scheme process, "e::main" will be executed immediately after the world has loaded. If you are running parallel Wraith Scheme processes -- more than one kitten -- only the MomCat will execute "e::main".

Use of "e::main" makes it possible to start something happening automatically in a newly-loaded world.

If Wraith Scheme loads a world in which "e::main" is bound to a Wraith Scheme object that is not a lambda expression, it will do nothing with the bound value; in particular, it will not evaluate or print out that value. The world load will then be ready for use.

Arguments:

None. Wraith Scheme will report an error if it loads a world in which "e::main" is bound to a lambda expression that requires one or more arguments. The error will be reported after the world load has completed, and the loaded world will then be ready for use.

Side Effects:

Whatever you like.

Returned Value:

Whatever you like.

For Example:

(define (e::main) (display "Hello, world!\n"))
    ;; ==> e::main

    ;; If you now save a world, and then reload it at some other
    ;; time, the Wraith Scheme Momcat will run "e::main"
    ;; immediately after loading the world, and will print
    ;; "Hello, world!" in the Wraith Scheme Main Display Panel.

e::make-float-matrix

Type:

Procedure.

Operation:

Create a new float matrix, optionally with all elements set to a given value.

Rationale, Explanation, Excuses:

Constructor for float matrices.

Arguments:

Two or three: The first two, exact integers which are respectively the number of rows and the number of columns in the desired float matrix; The optional third, a real number to be used as the value of all elements of the matrix created. If there is no third argument, all matrix elements will be zero.

Side Effects:

Creates a new float matrix, optionally with all elements set to a given value.

Returned Value:

A new instance of float matrix, optionally with all elements set to a given value.

For Example:

(e::make-float-matrix 2 2)  ;; ==>
                            ;; 0. 0.
                            ;; 0. 0.
(e::make-float-matrix 2 2 42)  ;; ==>
                               ;; 42. 42.
                               ;; 42. 42.

e::make-float-matrix-from-vector

Type:

Procedure.

Operation:

Create a new float matrix with elements loaded in row-major order from the given Scheme vector.

Rationale, Explanation, Excuses:

Useful constructor for float matrices.

Arguments:

One Scheme vector.

Side Effects:

Creates a new float matrix.

Returned Value:

A new instance of float matrix, with elements loaded in row-major order from the given Scheme vector.

For Example:

(e::make-float-matrix-from-vector 2 2 '#(1 2 3 4)))  ;; ==>
                                                     ;; 1. 2.
                                                     ;; 3. 4.

e::make-float-matrix-identity

Type:

Procedure.

Operation:

Create a new identity float matrix.

Rationale, Explanation, Excuses:

Useful constructor for float matrices.

Arguments:

One exact integer: The side of the matrix to be created.

Side Effects:

Creates a new identity float matrix of the specified side.

Returned Value:

A new instance of an identity float matrix.

For Example:

(e::make-float-matrix-identity 4) ;; ==>
                                  ;; 1. 0. 0. 0.
                                  ;; 0. 1. 0. 0.
                                  ;; 0. 0. 1. 0.
                                  ;; 0. 0. 0. 1.

e::make-forgettable

Type:

Procedure.

Operation:

Create a new instance of an unexpired forgettable object.

Rationale, Explanation, Excuses:

Constructor for forgettable objects.

Arguments:

Three: The first may be any Scheme object. The second to be an integer representing a "Unix time" (a number of seconds presumed to have elapsed since the start of calendar year 1970, common era), taken as the "expiration time" of the forgettable object being created. The third to be a real number between zero and one (inclusive), taken as the probability that the forgettable object shall be remembered after its expiration time has passed.

Side Effects:

Creates a new forgettable object.

Returned Value:

The new instance of forgettable object created.

For Example:

(e::make-forgettable (cons 1 2) 1247692518 0.75)
    ;; ==> #<Forgettable Object Pointer, unexpired, expiration time 1247692518 (GMT 2009.07.15 21:15:18)>

e::make-integer-range

Type:

Procedure.

Operation:

Create a list of evenly-spaced exact integers.

Rationale, Explanation, Excuses:

Uses include iteration, as with "map" or "for-each".

Arguments:

Three integers: The first is the start of the range; the second is the next integer past the end of the range; the third is the spacing between adjacent integers in the range.

Side Effects:

None.

Returned Value:

A list of exact integers that starts at the first argument and advances toward the second argument, but not to or past it, in steps of the third argument. If the third argument has sign different from the sign of (second argument minus first argument), the result is the empty list. If the first argument equals the second argument, the result is the empty list.

For Example:

(e::make-integer-range 0 10 1)    ;; ==> (0 1 2 3 4 5 6 7 8 9)
(e::make-integer-range 0 -10 -1)  ;; ==> (0 -1 -2 -3 -4 -5 -6 -7 -8 -9)
(e::make-integer-range 3 10 3)    ;; ==> (3 6 9)

(e::make-integer-range 0 0 1)     ;; ==> ()
(e::make-integer-range 0 10 -1)   ;; ==> ()

e::make-long-ratnum

Type:

Procedure.

Operation:

Create a rational number in which the numerator and denominator are stored separately.

Rationale, Explanation, Excuses:

Useful for dealing with Wraith Scheme's internal representation of rational numbers, in which the numerator and denominator are stored separately, as 64-bit signed integers.

Arguments:

Two integers.

Side Effects:

None.

Returned Value:

A rational number obtained from the arguments by treating the first as the numerator and the second as the denominator, and reducing the resulting fraction to lowest terms. The numerator will bear the appropriate sign, regardless whether the first or second argument was signed. If both arguments are exact, the stored numerator and denominator will be exact and the overall result will be exact. Otherwise, the stored numerator and denominator will both be inexact and the overall result will be inexact.

For Example:

(e::make-long-ratnum 1 3)   ;; ==> 1/3
(e::make-long-ratnum 1. 3)  ;; ==> #i1/3
(e::make-long-ratnum 1 -3)  ;; ==> -1/3

e::make-memory-mapped-block

Type:

Procedure.

Operation:

Allocate a memory-mapped area of memory to share with other processes, mapped into the address space of the Wraith Scheme process in which this procedure is executed. Create a file and associate it with that area. (Unlinks any preexisting file at the same path.) Fill the file with zeros. Return a Wraith Scheme object encapsulating details of the memory-mapped area, and containing a pointer to it.

Rationale, Explanation, Excuses:

Constructor for memory-mapped blocks.

Arguments:

Two: The first, a nonnegative integer representing the desired size in bytes of the memory-mapped block, the second a string containing the path -- relative or absolute -- to the file to be created and associated with the block.

Side Effects:

Creates a new memory-mapped area and also creates a file associated with it.

Returned Value:

A Wraith Scheme "memory-mapped block" object describing and locating the new memory-mapped area.

For Example:

;; Executed in the MomCat

(e::make-memory-mapped-block 1000 "/tmp/foo")
    ;; ==> #<Memory-Mapped Block, size 1000, path "/tmp/foo", memory mapped for kitten 0>

e::make-offsets

Type:

Procedure.

Operation:

Assist in defining variables which are the offsets within a memory-mapped-block of particular variables stored in that block.

Rationale, Explanation, Excuses:

Useful for dealing systematically with the locations of variables in a memory-mapped block; Subsumes some of the uses of a C or C++ structure definition.

Arguments:

Two: The first, an integer representing the offset of the first variable whose offset is to be calculated, the second a list of lists of variable names and sizes.

Side Effects:

For each variable in the second argument -- e.g., "my-variable" -- defines a new variable whose name is created by appending "-offset" to the name of the given variable (e.g., "my-variable-offset"), and whose value is the running total of the first argument plus the sizes of all previous variables in the second argument.

Technical Note: C and C++ structure definitions often insert padding between variables, to maintain correct alignment for memory access. This procedure offers no ability to insert padding in the offset definitions: You will have to create and use your own dummy variables where necessary, or locate your variables in such a way that padding is not necessary, or both.

The procedure actually executes "define" statements; the new variables thereby created will thereby be local to the environment in which "e::make-offsets" is executed. It is perhaps most useful if that environment is the top-level environment.

Note that executing this procedure does not create any memory-mapped area, or attempt to dereference any of the pointers thereby created. Rather, "e::make-offsets" merely sets up and names pointers for subsequent use.

Returned Value:

The sum of all the variable sizes in the second argument; that is, the total size of the block of variables declared.

For Example:

(define size-of-long-long 8)  ;; ==> size-of-long-long
(define size-of-char 1)       ;; ==> size-of-char
(define size-of-word 4)       ;; ==> size-of-word
(define initial-offset 42)    ;; ==> initial-offset

(define size-of-block
  (e::make-offsets initial-offset
   `(
     (my-first-char        ,size-of-char)
     (my-second-char       ,size-of-char)
     (my-first-word        ,size-of-word)
     (my-first-long-long   ,size-of-long-long)
     (my-second-word       ,size-of-word)
    )))        
  ;; ==> size-of-block

size-of-block
  ;; ==> 18 (18 is in fact the sum of the byte
  ;;         lengths of two 8-bit chars, two
  ;;         32-bit words, and a 64-bit long long)

;;  Executing "e::make-offsets" has created some
;;  brand new variables that show where in the 
;;  block the given variables are located (byte
;;  offsets), as follows:

my-first-char-offset        ;; ==> 42
my-second-char-offset       ;; ==> 43
my-first-word-offset        ;; ==> 44
my-first-long-long-offset   ;; ==> 48
my-second-word-offset       ;; ==> 56

e::make-simple-class

Type:

Procedure.

Operation:

Create a class in the Wraith Scheme class system. See the section of the Wraith Scheme Help File titled "Class System" for details of what this system is and how to use it.

Rationale, Explanation, Excuses:

The fundamental primitive for access to the Wraith Scheme class system

Arguments:

Four. The first a symbol that identifies the class, the second a list of classes from which the new class inherits, the third a list of lists of symbols and their bindings, representing the class variables of the new class and their default values, and the fourth a list of lists of symbols and their bindings, representing the instance variables of the new class and their default values.

Side Effects:

None.

Returned Value:

A class in the Wraith Scheme class system.

For Example:

(define bar (e::make-simple-class 'bar '() '() '()))
;; ==> bar      
(define baz (e::make-simple-class 'baz `(,bar) '((c 1)) '((a 1) (b 2))))
;; ==> baz

e::memory-map-block-in-current-kitten

Type:

Procedure.

Operation:

Use the details of a memory-mapped block representing an area of memory that has already been memory-mapped into the address space of one or more Wraith Scheme processes, to map the same area -- same address and associated file -- into the address space of an additional Wraith Scheme process, which thereby gains access to the shared memory. Does not alter the associated file. Has no effect if the block has already been mapped by that Wraith Scheme process.

Rationale, Explanation, Excuses:

Allows more than one Wraith Scheme process to share the same memory-mapped area.

Arguments:

A Wraith Scheme memory-mapped block object.

Side Effects:

Memory-maps the given block -- same address and same associated file -- into the address space of the Wraith Scheme process that executes this procedure. Has no effect if the block has already been mapped by that Wraith Scheme process.

Returned Value:

For Example:

;; Executed in the MomCat:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a

;; Executed in kitten 1:

(e::memory-map-block-in-current-kitten a)
#t

e::memory-mappable-space-size

Type:

Procedure.

Operation:

At startup, Wraith Scheme reserves a region of memory for memory-mapped blocks; this procedure returns the size in bytes of the portion of that area that is yet unused.

Rationale, Explanation, Excuses:

Provide administrative information for dealing with memory-mapped blocks.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer, representing the size in bytes of the portion of Wraith Scheme's address space reserved for memory-mapped blocks, that is yet unused.

For Example:

(e::memory-mappable-space-size)  ;; ==> 15663104

e::memory-mapped-block?

Type:

Procedure.

Operation:

Test whether a Scheme object is a memory-mapped block.

Rationale, Explanation, Excuses:

Predicate to identify objects of this type.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a memory-mapped block. Otherwise, returns #f.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::memory-mapped-block? a)   ;; ==> #t
(e::memory-mapped-block? 42)  ;; ==> #f

e::merge

Type:

Procedure.

Operation:

Merges two previously sorted lists into one list sorted in the same way. This procedure is stable when used with comparison predicates that return #f when applied to identical arguments.

Rationale, Explanation, Excuses:

Widely useful.

Arguments:

Three or four. The first two, the lists to be merged. The role of the third depends on whether the fourth, optional argument is present. If there is no fourth argument, then the third argument should be a procedure that accepts two arguments of the kind in the lists to be merged, and returns a boolean indicating whether its first argument is to be considered "less than" its second argument.

If the fourth argument is present, then it must be a procedure accepting one argument of the kind in the lists being merged. The fourth argument is applied to each element of the lists being merged in turn, and the arguments passed to the third argument are what the fourth argument returns. Thus if the elements of the lists being merged are some sort of structure, such as lists or vectors, the fourth argument might be used to extract one particular item from such a structure for use in the comparison. See the examples below.

Side Effects:

None.

Returned Value:

A new list, whose elements are the elements of the two given lists, in sort order.

For Example:

(e::merge (list 1 3 5) (list 2 4) <)  ;; ==> (1 2 3 4 5)
(e::merge (list '(a 1) '(b 3) '(c 5)) (list '(d 2) '(e 4)) < cadr)
  ;; ==> ((a 1) (d 2) (b 3) (e 4) (c 5))

e::merge!

Type:

Procedure.

Operation:

Merges two previously sorted lists into one list sorted in the same way, in the process destroying the structure of the original lists. Merging lists this way reduces the amount of Scheme main memory used in the merge operation. This procedure is stable when used with comparison predicates that return #f when applied to identical arguments.

Rationale, Explanation, Excuses:

Widely useful.

Arguments:

Side Effects:

Destroys the structure of the original lists.

Returned Value:

A list, whose elements are the elements of the two given lists, in sort order. The returned list will not be entirely new: It will contain some of the cons cells of the original list, in such a way that the list structure of the original lists is destroyed.

For Example:

(e::merge! (list 1 3 5) (list 2 4) <)  ;; ==> (1 2 3 4 5)
(e::merge! (list '(a 1) '(b 3) '(c 5)) (list '(d 2) '(e 4)) < cadr)
  ;; ==> ((a 1) (d 2) (b 3) (e 4) (c 5))

e::momcat?

Type:

Procedure.

Operation:

Returns whether or not the Wraith Scheme process in which it was called is the MomCat.

Rationale, Explanation, Excuses:

Provides elementary information about parallel instances of Wraith Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean. Returns #t if, and only if, called in the MomCat. Otherwise, returns #f

For Example:

(e::momcat?)  ;; ==> #t  ;; In MomCat
(e::momcat?)  ;; ==> #f  ;; In kittens 1 through 7

e::money->string

Type:

Procedure.

Operation:

Construct a Wraith Scheme string containing a number formatted with two digits to the right of the decimal point.

Rationale, Explanation, Excuses:

Standard R5 Scheme procedures offer little immediate capability for formatting numbers in many ways.

Arguments:

One real number:

Side Effects:

None.

Returned Value:

A string: Returns the first argument formatted with two digits to the right of the decimal point.

For Example:

(e::money->string 29.95)  ;; ==> "29.95"

e::multiple-values?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "multiple-values return" -- a special type of Scheme object used by Wraith Scheme as an intermediary between "values" and "call-with-values".

Rationale, Explanation, Excuses:

"Multiple-values returns" are a class of object peculiar to Wraith Scheme, whose existence and use is a low-level implementation detail that might become visible to users, and that might be of interest to some. This predicate provides a way to distinguish these objects.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a multiple-values return. Otherwise, returns #f

For Example:

(e::multiple-values? (values 1 2 3))  ;; ==> #t
(e::multiple-values? #t)              ;; ==> #f
(e::multiple-values? 42)              ;; ==> #f

e::nan?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "nan" -- a special flonum value used to represent the result of a mathematical calculation that could not produce a numerical result. If the object in question is a complex number, returns #t if one or both of its real and imaginary parts are nans. Also returns #t if the object is a rational whose numerator and denominator are stored separately and are both zero.

Rationale, Explanation, Excuses:

Wraith Scheme uses IEEE floating-point numbers, which have infs and nans, so it is useful to be able to test for their presence.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a nan, or if it is a rational whose numerator and denominator are stored separately and are both zero. Otherwise, returns #f.

For Example:

(e::nan? #t)                            ;; ==> #f
(e::nan? 3)                             ;; ==> #f
(e::nan? (- 1.e10000 1.e10000))         ;; ==> #t  ;; Two infs.
(e::nan? (- 1.e10000i 1.e10000i))       ;; ==> #t  ;; Two infs.
(e::nan? (make-rectangular 1 (/ 0 0)))  ;; ==> #t
(e::nan? 0/0)                           ;; ==> #t

e::ninety-percent-used?

Type:

Procedure.

Operation:

Test whether the amount of Wraith Scheme main memory in use equals or exceeds ninety percent of the amount available.

Rationale, Explanation, Excuses:

It may occasionally be useful to know when Wraith Scheme is about to garbage-collect. A user could easily write this procedure, but it is faster as a built-in.

Arguments:

None.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the amount of Wraith Scheme main memory in use equals or exceeds ninety percent of the amount available. Otherwise, returns #f

For Example:

(e::ninety-percent-used?)  ;; ==> #f

e::non-printing-object?

Type:

Procedure.

Operation:

Test whether a Scheme object is a "non-printing object"; that is, whether it is #n.

Rationale, Explanation, Excuses:

I added non-printing objects primarily as a value to return from interrupt handlers. In a project I was working on, I had some interrupts that were called frequently but mostly did nothing; I wanted to have them print nothing at all so as not to clutter up log files with repetitive meaningless output. An interrupt handler has to return something to the top-level read-eval-print loop of the kitten which handles it, so a non-printing object was just the thing to use for a returned value from such handlers.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is #n. Otherwise, returns #f.

For Example:

(e::non-printing-object? #t)  ;; ==> #f
(e::non-printing-object? #n)  ;; ==> #t

e::not-null?

Type:

Procedure.

Operation:

Test whether a Scheme object is different from the empty list.

Rationale, Explanation, Excuses:

This operation is marginally faster than the composition of "not" and "null?", and allowed rapid modification of code when I converted my Scheme system from one that used the empty list to represent falsehood to one that didn't.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is not the empty list. Otherwise, returns #f.

For Example:

(e::not-null? #t)   ;; ==> #t
(e::not-null? #f)   ;; ==> #t
(e::not-null? '())  ;; ==> #f

e::number-of-kittens

Type:

Procedure.

Operation:

Return the number of kittens running in parallel that were present when the current group of parallel Wraith Scheme processes was started. That is, this number does not change if a kitten exits for some reason, or if you cause it to exit -- for example, by means of the "Quit" command.

The MomCat is not included in this count.

Rationale, Explanation, Excuses:

Provides elementary information about parallel instances of Wraith Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: The number of kittens running in parallel, not including the MomCat.

For Example:

(e::number-of-kittens)  ;; ==> 0  ;; If just the MomCat.
(e::number-of-kittens)  ;; ==> 7  ;; With the MomCat and 7 kittens.

e::number->string-with-n-decimals

Type:

Procedure.

Operation:

Construct a Wraith Scheme string containing a real number formatted with a given number of digits to the right of the decimal point.

Rationale, Explanation, Excuses:

Standard R5 Scheme procedures offer little immediate capability for formatting numbers in many ways.

Arguments:

Two: The first is a real number to be formatted; the second an integer in the range [0..10], indicating the number of digits to appear to the right of the decimal point.

Side Effects:

None.

Returned Value:

A string: Returns the first argument formatted with n digits to the right of the decimal point, where n is the second argument. The value of n must be in the range [0 .. 10].

For Example:

(e::number->string-with-n-decimals 1/3 3)
;; ==> "0.333"

(e::number->string-with-n-decimals (- (/ 1000 3)) 6)
;; ==> "333.333333"

e::original-cwcc

Type:

Procedure.

Operation:

A version of call-with-current-continuation that does not support dynamic-wind.

Rationale, Explanation, Excuses:

Wraith Scheme implements dynamic-wind generally along the lines of the implementation demonstrated by Jonathan Rees (1992) in "The Scheme of Things: The June Meeting", published in Lisp Pointers V(4), October-December 1992. That implementation involves modifying call-with-current-continuation. The unmodified version is "e::original-cwcc".

Arguments:

One argument, which must be a procedure that itself takes one argument.

Side Effects:

Saves the current state of Scheme in such a way that it can subsequently be restored at will. See call-with-current-continuation for details.

Returned Value:

See call-with-current-continuation for details.

For Example:

e::peek-poke-atomic

Type:

Procedure.

Operation:

Perform an atomic test-and-set (with memory barrier) of the least-significant bit of a given 64-bit integer in a memory-mapped block, and return whether the bit was originally zero.

The operation performed is a "locked" bit-test-and-set operation, accomplished by assembly language embedded within Wraith Scheme's C++ code.

Rationale, Explanation, Excuses:

Provide for critical-section locking in memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Two: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the datum that is to be the subject of the atomic test-and-set operation, within that area of memory. The offset must be an integral multiple of eight, and must indicate an area within the range of the memory-mapped block.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the bit tested-and-set was originally 0. Otherwise, returns #f.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))  ;; ==> a
(e::peek64 a 120)                                         ;; ==> 0
(e::peek-poke-atomic a 120)                               ;; ==> #t
(e::peek-poke-atomic a 120)                               ;; ==> #f
(e::peek64 a 120)                                         ;; ==> 1

e::peek8

e::peek16

e::peek32

e::peek64

Type:

Procedure. (All of them)

Operation:

Read from a memory-mapped area of memory represented by a memory-mapped block. The four procedures allow reads of quantities that are respectively 8, 16, 32 and 64 bits long; that is, one, two, four and eight bytes long.

Note that there is no requirement that the content addressed actually be an integer; Wraith Scheme has no idea of what other programs may have stored at the location indicated. Furthermore, even if the quantities are integers, Wraith Scheme has no idea of whether they are supposed to be exact or not. Wraith scheme resolves this ambiguity by returning exact integers.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Two: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the datum to be read within that area of memory. The offset must be an integral multiple of the size of the datum in bytes, and must indicate an area within the range of the memory-mapped block.

Side Effects:

None.

Returned Value:

A Wraith Scheme exact signed integer representing the data read. The returned values are not sign-extended; thus for example, a peek8 of a byte with all bits set would return the 64-bit signed integer 255.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke8 a 0 1)   ;; ==> #t
(e::poke16 a 2 2)  ;; ==> #t
(e::poke32 a 4 3)  ;; ==> #t
(e::poke64 a 8 4)  ;; ==> #t
(e::peek8 a 0)     ;; ==> 1
(e::peek16 a 2)    ;; ==> 2
(e::peek32 a 4)    ;; ==> 3 
(e::peek64 a 8)    ;; ==> 4

e::peek64-float

Type:

Procedure.

Operation:

Read a floating-point number from a memory-mapped area of memory represented by a memory-mapped block.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Two: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the datum to be read within that area of memory. The offset must be a multiple of eight, and must indicate an area within the range of the memory-mapped block.

Side Effects:

None.

Returned Value:

A Wraith Scheme inexact floating-point number that is numerically equal to the floating point number just read. If the remotely-stored value is not a floating-point number in IEEE 64-bit floating-point format, the returned value is undefined and almost certainly nonsense.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke64-float a 0 1.25)  ;; ==> #t
(e::peek64-float a 0)       ;; ==> 1.25

e::peek64-float-set-vector!

Type:

Procedure.

Operation:

Read a vector of floating-point numbers from a memory-mapped area of memory represented by a memory-mapped block.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the first datum to be read from that area of memory. The offset must be a multiple of eight, and must indicate an area within the range of the memory-mapped block. The third, a vector into which the data read are to be loaded. The length of the vector is the number of data elements to be read.

Side Effects:

Writes data to the given Scheme vector.

Returned Value:

Returns the vector provided as the third argument, as modified. The values loaded into the vector are Wraith Scheme inexact floating-point numbers that are numerically equal to the floating point numbers just read. If any remotely-stored value is not a floating-point number in IEEE 64-bit floating-point format, the corresponding returned value is undefined and almost certainly nonsense.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(define b '#(1 1.25 1.5))            ;; ==> b
(define c (make-vector 3))           ;; ==> c
(e::poke64-float-vector a 0 b)       ;; ==> #t
(e::peek64-float-set-vector! a 0 c)  ;; ==> #(1 1.25 1.5)
c                                    ;; ==> #(1 1.25 1.5)

e::peek8-set-vector!

e::peek16-set-vector!

e::peek32-set-vector!

e::peek64-set-vector!

Type:

Procedure. (All of them)

Operation:

Load a vector from a memory-mapped area of memory represented by a memory-mapped block. The area of the block from which the data are taken is assumed to be a one-dimensional array of data elements that are all the same length. The four procedures allow loads of quantities that are respectively 8, 16, 32 and 64 bits long; that is, one, two, four and eight bytes long.

Note that there is no requirement that the content addressed actually be integers; Wraith Scheme has no idea of what other programs may have stored at the locations indicated. Furthermore, even if the quantities are integers, Wraith Scheme has no idea of whether they are supposed to be exact or not. Wraith scheme resolves this ambiguity by returning exact integers.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the first datum to be read within that area of memory. The offset must be an integral multiple of the size of the data in bytes, and must indicate an area within the range of the memory-mapped block. The third a vector, whose length indicates the number of consecutive data elements to be retrieved from the memory-mapped block.

Side Effects:

Writes data to the given Scheme vector.

Returned Value:

Returns the vector provided as the third argument, as modified.

Returned Value:

Each of these procedures returns the vector which is passed in as its third argument, after modification. The contents of the vector will be Wraith Scheme exact signed integers representing the data read. The returned values are not sign-extended; thus for example, a peek8-set-vector! that encountered a byte with all bits set would load the exact 64-bit signed integer 255 into the appropriate place in its vector.

For Example:

(define z (make-vector 4))    ;; ==> z
(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))  ;; ==> a
(e::poke8 a 0 1)              ;; ==> #t
(e::poke8 a 1 2)              ;; ==> #t
(e::poke8 a 2 4)              ;; ==> #t
(e::poke8 a 3 8)              ;; ==> #t
(e::peek8-set-vector! a 0 z)  ;; ==> #(1 2 4 8)
z                             ;; ==> #(1 2 4 8)

e::peek8-set-vector-sign-extend!

e::peek16-set-vector-sign-extend!

e::peek32-set-vector-sign-extend!

Type:

Procedure. (All of them)

Operation:

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Side Effects:

Writes data to the given Scheme vector.

Returned Value:

Returns the vector provided as the third argument, as modified.

Returned Value:

Each of these procedures returns the vector which is passed in as its third argument, after modification. The contents of the vector will be Wraith Scheme exact 64-bit signed integers representing the data read. The returned values are sign-extended; thus for example, a peek8-set-vector-sign-extend! that encountered a byte with all bits set would load the exact 64-bit signed integer -1 into the appropriate place in its vector.

For Example:

(define z (make-vector 4))  ;; ==> z
(define y (e::make-memory-mapped-block 1000 "/tmp/bar"))  ;; ==> y
(e::poke16 y 0 #xffff)      ;; ==> #t
(e::poke16 y 2 2)           ;; ==> #t
(e::poke16 y 4 4)           ;; ==> #t
(e::poke16 y 6 #x8000)      ;; ==> #t
(e::peek16-set-vector-sign-extend! y 0 z)  ;; ==> #(-1 2 4 -32768)
z                           ;; ==> #(-1 2 4 -32768)

e::peek8-sign-extend

e::peek16-sign-extend

e::peek32-sign-extend

Type:

Procedure. (All of them)

Operation:

Read and sign-extend from a memory-mapped area of memory represented by a memory-mapped block. The three procedures allow reads of quantities that are respectively 8, 16 and 32 bits long; that is, one, two and four bytes long.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Side Effects:

None.

Returned Value:

A Wraith Scheme exact 64-bit signed integer representing the data read. The returned values are sign-extended; thus for example, a peek8-sign-extend of a byte with all bits set would return the Wraith Scheme exact 64-bit signed integer -1.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke8 a 0 #xff)            ;; ==> #t
(e::poke16 a 2 #xffff)         ;; ==> #t
(e::poke32 a 4 #xffffffff)     ;; ==> #t
(e::peek8-sign-extend a 0)     ;; ==> -1
(e::peek16-sign-extend a 2)    ;; ==> -1
(e::peek32-sign-extend a 4)    ;; ==> -1

;; But ...

(e::peek8 a 0)                 ;; ==> 255
(e::peek16 a 2)                ;; ==> 65535
(e::peek32 a 4)                ;; ==> 4294967295

e::peek-c-string

Type:

Procedure.

Operation:

Read a null-terminated series of bytes -- a "C string" -- from a memory-mapped area of memory represented by a memory-mapped block, and return what was read in the form of a Scheme string.

Rationale, Explanation, Excuses:

Provide read access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Two: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the start location of the string to be read, within that area of memory. The offset must indicate an area within the range of the memory-mapped block.

Side Effects:

None.

Returned Value:

A copy of the string read, in the form of a Scheme string. If no null occurs between the given offset and the end of the memory-mapped block, Wraith Scheme will report an error.

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke-c-string a 23 "Hello, world\n")  ;; ==> #t
(e::peek-c-string a 23)                   ;; ==> "Hello, world\n"
(display (e::peek-c-string a 23))

;; Wraith Scheme displays the following:

Hello, world
#t

e::perform-applicative

Type:

Procedure.

Operation:

Perform a block of code in a referentially transparent manner.

Rationale, Explanation, Excuses:

Referentially transparent programming has many enthusiasts and is theoretically interesting; this primitive provides support for it.

Arguments:

One procedure of no arguments.

Side Effects:

The interpretation of referential transparency used by this procedure allows the block of code invoked to perform input and output, and to access memory-mapped blocks, which many may consider as allowing side effects, but that block is not allowed to use public Wraith Scheme procedures that change Wraith Scheme internal state; any attempt to use them is treated as an error. The procedures so treated are:

set!
set-car!
set-cdr!
string-fill!
string-set!
vector-fill!
vector-set!
e::clear-permanent!
e::disable-big-red-button!
e::disable-pushbutton!
e::enable-big-red-button!
e::enable-pushbutton!
e::load-world!
e::set-current-directory!
e::set-input-port!
e::set-level-indicator!
e::set-list-print-depth!
e::set-list-print-length!
e::set-permanent!
e::set-tag!
e::set-vector-print-depth!
e::set-vector-print-length!
c::set-blocked-binding!

Returned Value:

Whatever is returned by the block of code that is the passed argument.

For Example:

(e::perform-applicative (lambda () (+ 2 2)))  ;; ==> 4

but

(define a 3)
(e::perform-applicative (lambda () (set! a 42)))

produces the error message:

In built-in routine "set!":
Problem: Attempt to use a non-applicative procedure or special form during applicative programming.
  Last lambda called (which may have returned) was recently named:
    thunk
  Recent names of non-tail-recursive stacked lambda expressions:
    e::perform-applicative
  (Resetting)
Top-level loop ...

e::permanent?

Type:

Procedure.

Operation:

Test whether the value or binding of a variable is "permanent", in the sense that an attempt to change it with, for example, "set!", is an error.

Rationale, Explanation, Excuses:

Arguments:

One symbol.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the given symbol has a value or binding that is permanent, in the sense described above. Otherwise, returns #f.

For Example:

(e::clear-permanent! 'cons)  ;; ==> #t
(e::permanent? 'cons)        ;; ==> #f
(e::set-permanent! 'cons)    ;; ==> #t
(e::permanent? 'cons)        ;; ==> #t

e::poke8

e::poke16

e::poke32

e::poke64

Type:

Procedure. (All of them)

Operation:

Write to a memory-mapped area of memory represented by a memory-mapped block. The four procedures allow writes of quantities that are respectively 8, 16, 32 and 64 bits long; that is, one, two, four and eight bytes long.

If any datum provided should happen to be stored in the internal format that Wraith Scheme uses for floating-point numbers, but is nevertheless an integer in the appropriate range, Wraith Scheme will write that quantity in the format appropriate to an integer.

Rationale, Explanation, Excuses:

Provide write access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the location of the write within that area of memory. The offset must be an integral multiple of the size of the datum in bytes, and must indicate an area within the range of the memory-mapped block. The third argument is the datum to be written, which must be an integer in the range appropriate for a 64-bit fixnum. That datum will silently have sufficient high-order bits excised that what remains fits in the space available.

Side Effects:

Writes data in a memory-mapped area of memory.

Returned Value:

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke8 a 0 1)   ;; ==> #t
(e::poke16 a 2 2)  ;; ==> #t
(e::poke32 a 4 3)  ;; ==> #t
(e::poke64 a 8 4)  ;; ==> #t
(e::peek8 a 0)     ;; ==> 1
(e::peek16 a 2)    ;; ==> 2
(e::peek32 a 4)    ;; ==> 3 
(e::peek64 a 8)    ;; ==> 4

e::poke64-float

Type:

Procedure.

Operation:

Store a floating-point number into a memory-mapped area of memory represented by a memory-mapped block.

Rationale, Explanation, Excuses:

Provide write access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the location of the write within that area of memory. The offset must be a multiple of eight, and must indicate an area within the range of the memory-mapped block. The third, a real number, which Wraith Scheme will convert to a floating point format -- if necessary -- before performing the store.

Side Effects:

Writes data in a memory-mapped area of memory.

Returned Value:

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke64-float a 0 1.25)  ;; ==> #t
(e::peek64-float a 0)       ;; ==> 1.25

e::poke64-float-vector

Type:

Procedure.

Operation:

Store a vector of floating-point numbers into a memory-mapped area of memory represented by a memory-mapped block.

Rationale, Explanation, Excuses:

Provide write access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the location where the write is to begin, within that area of memory. The offset must be a multiple of eight, and must indicate an area within the range of the memory-mapped block. The third, a vector from which the real numbers to be stored are taken. The length of the vector is the number of data elements to be written. If necessary, Wraith Scheme will convert numbers to floating-point format before storing them.

Side Effects:

Writes data in a memory-mapped area of memory.

Returned Value:

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(define b '#(1 1.25 1.5))            ;; ==> b
(define c (make-vector 3))           ;; ==> c
(e::poke64-float-vector a 0 b)       ;; ==> #t
(e::peek64-float-set-vector! a 0 c)  ;; ==> #(1 1.25 1.5)
c                                    ;; ==> #(1 1.25 1.5)

e::poke8-vector

e::poke16-vector

e::poke32-vector

e::poke64-vector

Type:

Procedure. (All of them)

Operation:

Write the contents of a vector to a memory-mapped area of memory represented by a memory-mapped block. The four procedures allow writes of quantities that are respectively 8, 16, 32 and 64 bits long; that is, one, two, four and eight bytes long.

If any datum provided should happen to be stored in the internal format that Wraith Scheme uses for fixnums, Wraith Scheme will write that datum as an IEEE 64-bit floating-point number. That conversion may result in loss of precision of the number in question. These conversions do not change the Scheme vector provided as an argument, they are entirely internal to the procedure itself.

Rationale, Explanation, Excuses:

Provide write access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the location where the write is to begin, within that area of memory. The offset must be an integral multiple of the size of the datum in bytes, and must indicate an area within the range of the memory-mapped block. The third argument is a vector containing the data to be written. Each data element must be an integer in the range appropriate for a 64-bit fixnum. That datum will silently have sufficient high-order bits excised that what remains fits in the space available. The length of the vector is the number of data elements to be written.

Side Effects:

Writes data in a memory-mapped area of memory.

Returned Value:

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(define b '#(1 2 3 4))         ;; ==> b
(define c (make-vector 4))     ;; ==> c
(e::poke8-vector a 0 b)        ;; ==> #t
(e::peek8-set-vector! a 0 c)   ;; ==> #(1 2 3 4)
c                              ;; ==> #(1 2 3 4)

e::poke-c-string

Type:

Procedure.

Operation:

Write the content of a Scheme string into a memory-mapped area of memory represented by a memory-mapped block, in the form of a null-terminated string of ASCII characters -- a "C string".

Rationale, Explanation, Excuses:

Provide write access to memory-mapped areas of memory represented by memory-mapped blocks.

Arguments:

Three: The first a Wraith Scheme memory-mapped block object, the second a nonnegative integer representing the offset of the location where the write is to begin, within that area of memory, and the third a string. The offset must indicate an area within the range of the memory-mapped block. There must be sufficient room in the given memory-mapped block, beyond the given offset, for the string to fit, including the final null.

Side Effects:

Writes data in a memory-mapped area of memory.

Returned Value:

For Example:

(define a (e::make-memory-mapped-block 1000 "/tmp/foo"))
    ;; ==> a
(e::poke-c-string a 23 "Hello, world\n")  ;; ==> #t
(e::peek-c-string a 23)                   ;; ==> "Hello, world\n"
(display (e::peek-c-string a 23))

;; Wraith Scheme displays the following:

Hello, world
#t

e::process-id

Type:

Procedure.

Operation:

Return the Unix process identification number of the process in which the procedure was called.

Note that the procedure e::show-kittens provides (among other things) the process ids of all members of a group of cooperating Wraith Scheme processes.

Rationale, Explanation, Excuses:

Unix process identification numbers are valuable for examining and controlling Wraith Scheme processes from the Unix command line -- perhaps from the Macintosh "Terminal" application. For example, they might be useful in interpreting output from the Unix "ps" program, or as arguments to the Unix "kill" program.

Arguments:

None.

Side Effects:

None.

Returned Value:

An integer: The Unix process identification number of the Wraith Scheme process in which the procedure was called.

For Example:

;; Process ids are nonnegative integers of up to five digits.

(e::process-id)  ;; ==> 22316 ;; e.g.,

e::program-directory

Type:

Procedure.

Operation:

Find the Wraith Scheme application's directory; that is, the directory of "Wraith Scheme.app".

Rationale, Explanation, Excuses:

Users often organize directories so that files related to a program are in directories only a short pathname from the program itself. Thus a simple means to find the program's directory seems useful.

Arguments:

None.

Side Effects:

None.

Returned Value:

A string: Returns a string containing the absolute Unix path to the directory containing "Wraith Scheme.app". The returned string will end in a '/'.

For Example:

;; Perhaps
(e::program-directory)  ;; ==> "/Users/JayFreeman/Scheme"

e::promise?

Type:

Procedure.

Operation:

Test whether a Scheme object is a promise.

Rationale, Explanation, Excuses:

In Wraith Scheme, promises are a distinct type; it seemed useful to have a simple way to test for them.

Arguments:

One Scheme object.

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the argument is a promise. Otherwise, returns #f.

For Example:

(e::promise? '())           ;; ==> #f

(define a (delay (+ 2 2)))  ;; ==> a
(e::promise? a)             ;; ==> #t
(force a)                   ;; ==> 4
(e::promise? a)             ;; ==> #t

e::push-list-into-continuation

Type:

Procedure.

Operation:

Push the elements of the proper list which is its argument, into the Wraith Scheme continuation, cdr end first. Those elements will thus be evaluated, in the same order as they appear in the given list, as soon as "e::push-list-into-continuation" has returned, in the environment in which "e::push-list-into-continuation" was called.

Rationale, Explanation, Excuses:

This procedure is useful in low-level manipulation of the Wraith Scheme continuation.

Arguments:

One proper list.

Side Effects:

Evaluates the items of the list, in the order in which they appear in that list, as soon as "e::push-list-into-continuation" has returned, in the environment in which "e::cons-with-continuation" is called.

Returned Value:

Any Scheme object or objects. Strictly, "e::push-list-into-continuation" does not return: Where you would have expected a return value to appear, what appears instead is the result of evaluating the elements of its argument.

For Example:

(define form-to-be-pushed
  (list 
    '(display "Hello from the continuation!\n")
    '(display "Hello again from the continuation!\n")
    '(display "Hello a third time from the continuation!\n")
    )
  )

(e::push-list-into-continuation form-to-be-pushed)
    ;; ==>
    ;; Hello from the continuation!
    ;; Hello again from the continuation!
    ;; Hello a third time from the continuation!
    ;; #t

e::pushbutton-enabled?

Type:

Procedure.

Operation:

Tests whether a pushbutton (in the Wraith Scheme Sensory Devices Drawer) is enabled. Applies only to pushbuttons of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Required for checking pushbutton state from Wraith Scheme.

Arguments:

One integer in the range [0..3].

Side Effects:

None.

Returned Value:

A boolean: Returns #t if, and only if, the given pushbutton is enabled. Otherwise, returns #f. Ignores the exactness of the arguments.

For Example:

(e::pushbutton-enabled? 0)  ;; ==> #t -- Pushbutton 0 is enabled.

e::pushbutton-interrupt-number

Type:

Procedure.

Operation:

Return the interrupt number associated with a given pushbutton (in the Wraith Scheme Sensory Devices Drawer). Reports an error if that pushbutton is not enabled. Applies only to pushbuttons of the Wraith Scheme process where the procedure was called.

Rationale, Explanation, Excuses:

Required for checking pushbutton state from Wraith Scheme.

Arguments:

One integer in the range [0..3].

Side Effects:

None.

Returned Value:

An exact integer in the range [0..1023], that is the interrupt number presently associated with the pushbutton whose number is passed as the argument.

For Example:

(e::pushbutton-interrupt-number 3)  :: ==> 42 -- Means that pushbutton 3
                                    ;;     is set to trigger interrupt 42.

e::rpi-gpio-connect

Type:

Procedure.

Operation:

Advise Weasel Scheme of the location in the Raspberry Pi hardware memory map, of the registers used to control the Raspberry Pi general-purpose input/output pins (gpio pins), and initialize Weasel Scheme to use those registers.

This procedure neither reads nor writes any of the control registers: It does not "touch hardware", it merely sets up for other procedures subsequently to do so.

Note:

Rationale, Explanation, Excuses:

Required to enable access of Raspberry Pi general-purpose input/output pins from Weasel Scheme.

Arguments:

None.

Side Effects:

None.

Returned Value:

For Example:

(e::rpi-gpio-connect)  ;; ==> #t

e::rpi-gpio-display-control-registers

Type:

Procedure.

Operation:

Display a human-readable display of the content of all of the general-purpose input/output (gpio) control registers that the Raspberry Pi uses. (The processor of the Raspberry Pi has the ability to address more gpio pins than the Raspberry Pi uses, so not all of the control registers are shown in the display.)

Note:

For interpretation of the display, see (e.g.) this link.

Rationale, Explanation, Excuses:

provide

Arguments:

None.

Side Effects:

None.

Returned Value:

For Example:

(e::rpi-gpio-display-control-registers)  ;; ==> (e.g.)
    ;; Base address is 0x7e200000, registers are four bytes wide.
    ;; gpfsel0: 0x0
    ;; gpfsel1: 0x0
    ;; gpfsel2: 0x12000000
    ;; gpset0: 0x6770696f
    ;; gpclr0: 0x6770696f
    ;; gplev0: 0x1000c1ff
    ;; gpeds0: 0x0
    ;; gpren0: 0x0
    ;; gpfen0: 0x0
    ;; gphen0: 0x0
    ;; gplen0: 0x0
    ;; gparen0: 0x0
    ;; gpafen0: 0x0
    ;; gpio_pup_pdn_cntrl_reg0: 0x4aa95555
    ;; gpio_pup_pdn_cntrl_reg1: 0x19aaaaaa
    ;; #t

e::rpi-gpio-display-pin

Type:

Procedure.

Operation:

Display the value and function-select field of a given Raspberry Pi general-purpose I/O pin (gpio pin). If the pin to be displayed is pin n, then the value displayed is bit n of control register gplev0. The least-significant bit of that register is bit zero, and so on.

Note:

Rationale, Explanation, Excuses:

Basic primitive for displaying logic-level data read by input gpio pins of the Raspberry Pi, and which also returns the most recent value written to any output gpio pin.

Arguments:

One gpio pin number; that is, an integer in the range [0..26].

Side Effects:

None.

Returned Value:

For Example:

(e::rpi-gpio-display-pin 25)
    ;; ==> Raspberry Pi GPIO pin 25 has value 0, function select field 0x1  ;; (or whatever)

e::rpi-gpio-display-pins

Type:

Procedure.

Operation:

Display the value and function-select field of all Raspberry Pi general-purpose I/O pins (gpio pins). In the display for pin n, the value displayed is bit n of control register gplev0. The least-significant bit of that register is bit zero, and so on.

Note:

Rationale, Explanation, Excuses:

Basic primitive for displaying logic-level data read by input gpio pins of the Raspberry Pi, and which also returns the most recent values written to output gpio pins.

Arguments:

None.

Side Effects:

None.

Returned Value:

For Example:

(e::rpi-gpio-display-pins)  ;; ==>
    ;; Raspberry Pi GPIO pin 0 has value 1, function select field 0x0
    ;; Raspberry Pi GPIO pin 1 has value 1, function select field 0x0
    ;; Raspberry Pi GPIO pin 2 has value 1, function select field 0x0
    ;; 
    ;;     [ ... ]
    ;; 
    ;; Raspberry Pi GPIO pin 24 has value 0, function select field 0x0
    ;; Raspberry Pi GPIO pin 25 has value 0, function select field 0x0
    ;; Raspberry Pi GPIO pin 26 has value 0, function select field 0x0

e::rpi-gpio-pin-select-field

Type:

Procedure.

Operation:

Returns the three-bit content of the select-field setting of a specified Raspberry Pi general-purpose input/output pin (gpio pin). That value indicates the configuration of the indicated gpio pin; that is, the purpose for which it is configured. Configurations include, but are not limited to, use as a logic-level input, which is indicated by a zero, and use as a logic-level output, which is indicated by a one.

Note:

Rationale, Explanation, Excuses:

Determine the purpose for which a given Raspberry Pi gpio pin is intended to be used.

Arguments:

One gpio pin number; that is, an integer in the range [0..26].

Side Effects:

None.

Returned Value:

A three-bit integer indicating the hardware configuration of the specified Raspberry Pi gpio pin; that is, indicating the purpose for which the pin is set up.

For Example:

(e::rpi-gpio-pin-select-field 25)  ;; ==> 5  ;; or whatever

e::rpi-gpio-read-pin

Type:

Procedure.

Operation:

Reads the logic level from a specified Raspberry Pi general-purpose input/output pin (gpio pin), provided that the direction of that pin has been set to "input", perhaps by procedure e::rpi-gpio-set-pin-for-output.

Note:

Rationale, Explanation, Excuses:

Read logic-level data from a Raspberry Pi gpio pin.

Arguments:

One gpio pin number; that is, an integer in the range [0..26].

Side Effects:

None.

Returned Value:

An integer, either zero or one, corresponding to the logic level of the specified pin.

For Example:

(e::rpi-gpio-read-pin 25)  ;; ==> 0  ;; or whatever

e::rpi-gpio-set-pin-for-output

Type:

Procedure.

Operation:

Set the direction of a given Raspberry Pi general-purpose input/output pin (gpio pin) to either "input" or "output". As the procedure name may suggest, the "output" direction is specified by an argument of #t, and the "input" direction by #f.

Note:

Rationale, Explanation, Excuses:

Fundamental routine for operation of Raspberry Pi gpio pins.

Arguments:

Two: The first a gpio pin number -- that is, an integer in the range [0..26], and the second a boolean -- #t indicating that the direction is indeed to be set to output, and #f indicating that it is not; that is, that the direction is to be set to input.

Side Effects:

None.

Returned Value:

For Example:

(e::rpi-gpio-set-pin-for-output 25 #f)  ;; ==> #t  ;; Sets the direction to "input".

e::rpi-gpio-write-pin

Type:

Procedure.

Operation:

Sets the logic level of a specified Raspberry Pi general-purpose input/output pin (gpio pin), provided that the direction of that pin has been set to "output", perhaps by procedure e::rpi-gpio-set-pin-for-output.

Note: