Page Numbers: Yes X: 306 Y: 1.0" First Page: 69
Margins: Top: 1.0" Bottom: 1.3"
Heading:
STANDARD PROCEDURE GUIDE3-LISP REFERENCE MANUALJanuary 26, 1983
————————————————————————————————————————————
9.i. CONTROL
————————————————————————————————————————————
(EF PREM C1 C2)
(IF PREM C1 C2)
Both (IF PREM C1 C2) and (EF PREM C1 C2) designate the referent of C1 or C2 depending on whether PREM designates true or false, respectively. In the case of IF, C1 (C2) is normalised only if PREM designates true (false), whereas EF is fully (procedurally) extensional.
Properties:Primitive (EF only); Protected; kernel; abnormal (IF only).
F-Type:[ TRUTH-VALUES X OBJECTS X OBJECTS ] ← OBJECTS
Examples:1> (IF (= 1 1) ’A ’B)
=> ’A
1> (IF (= 1 2) ’A ’B)
=> ’B
1> (EF (= 1 2)
(PRINT-STRING "Hello" PRIMARY-STREAM)
(PRINT-STRING "Good-bye" PRIMARY-STREAM)) Hello Good-bye
=> ’OK
1> (IF (= 1 2)
(PRINT-STRING "Hello" PRIMARY-STREAM)
(PRINT-STRING "Good-bye" PRIMARY-STREAM)) Good-bye
=> ’OK
Semantics:S(E0("EF),E,F,C) = l ...
S(E0("IF),E,F,C) = l ...
———————————————————
(COND [P1 C1] ... [Pk Ck])
Designates Ci for the least i such that Pi designates true. Only P1, P2, ..., Pi and Ci are normalised. Error if no Pi designates true, or some Pi doesn’t designate a truth value.
Properties:Protected; kernel; abnormal.
Y-Type:[ ??? ] ← ???
Examples:1> (COND [(= 1 2) 10]
[(= 1 3) 20]
[(= 1 1) 30]
[$T 40])
=> ’30
1> (COND [(= 1 2) (PRINT ’10 PRIMARY-STREAM)]
[(= 1 3) (PRINT ’20 PRIMARY-STREAM)]
[(= 1 1) (PRINT ’30 PRIMARY-STREAM)]
[(BLOCK (PRINT ’$T PRIMARY STREAM) $T)
(PRINT ’40 PRIMARY-STREAM)]) 30
=> ’OK
Semantics:S(E0("COND),E,F,C) = l ...
———————————————————
(BLOCK C1 ... Ck)
The results of normalising C1 through Ck-1 are discarded, and the result of normalising Ck is returned. Note that Ck is normalised tail-recursively with respect to the BLOCK.
Properties:Protected.
F-Type:[ {OBJECTS}* X OBJECTS ] ← OBJECTS
Examples:1> (BLOCK 1 2 3)
=> 3
1> (BLOCK (PRINT-STRING "2 " PRIMARY-STREAM)
(PRINT-STRING "+ " PRIMARY-STREAM)
(PRINT-STRING "2 " PRIMARY-STREAM)
’DONE) 2 + 2
=> ’DONE
Semantics:S(E0("BLOCK),E,F,C) = l ...
———————————————————
(CATCH C)
Declaratively speaking, CATCH designates the identity function — it returns what C normalises to. However, if (THROW E) is normalised in the process of normalising C (and assuming that there are no intervening CATCHes) the result of normalising E is immediately returned as the result of the enclosing (CATCH C).
Properties:(Hairy).
F-Type:[ OBJECTS ] ← OBJECTS
Examples:1> (CATCH (+ 2 2))
=> 4
1> (CATCH (+ 2 (THROW 3)))
=> 3
1> (CATCH
(BLOCK (THROW (+ 3 3))
100))
=> 6
Semantics:S(E0("CATCH),E,F,C) = l ...
———————————————————
(THROW C)
Causes the result of normalising C to be returned immediately as the result of the most recently executed enclosing CATCH.
Properties:(Hairy).
Y-Type:[ ??? ] ← ???
Examples:1> (CATCH (BLOCK (PRINT-STRING "-2 " PRIMARY-STREAM)
(PRINT-STRING "-1 " PRIMARY-STREAM)
(THROW ’BLAST-OFF)
(PRINT-STRING "1 " PRIMARY-STREAM)
(PRINT-STRING "2 " PRIMARY-STREAM))) -2 -1
=> ’BLAST-OFF
1> (CATCH (+ (CATCH (* 5 3))
(THROW (* 6 (THROW 4)))))
=> 4
Semantics:S(E0("THROW),E,F,C) = l ...
———————————————————
(DELAY C)
Defers the normalisation of C by embedding it in a LAMBDA expression.
Properties:Abnormal.
Macro:(DELAY C)W>(LAMBDA SIMPLE [] C)
Examples:1> (SET X (DELAY (* Y Y)))
=> ’OK
1> (SET Y 7)
=> ’OK
1> (FORCE X)
=> 49
1> (SET Y 9)
=> ’OK
1> (FORCE X)
=> 81
Semantics:S(E0("DELAY),E,F,C) = l ...
———————————————————
(FORCE C)
Causes the normalisation of the DELAYed expression designated by C.
Macro:(FORCE C)W>(C)
Examples:1> (SET X (DELAY (PRINT-STRING GREETING PRIMARY-STREAM)))
=> ’OK
1> (SET GREETING "Hi there")
=> ’OK
1> (FORCE X) Hi there
=> ’OK
1> (SET GREETING "Goodbye")
=> ’OK
1> (FORCE X) Goodbye
=> ’OK
Semantics:S(E0("FORCE),E,F,C) = l ...
———————————————————
(SELECT INDEX [M1 C1] ... [Mk Ck])
(SELECTQ INDEX [M1 C1] ... [Mk Ck])
SELECTQ allows one of several clauses (the Ci) to the processed based upon the designation of INDEX. The Xi are tested from left to right, stopping as soon as a clause is selected. If Xi is an atom, the ith clause will be selected if the selector designates this atom; if Xi is a rail, the ith clause will be selected if the selector is a member of this rail; otherwise, Xi should be the boolean $T which will always be selected, if given half a chance. Error if no clauses id selected. SELECT is similar except that the selection is based on the designation of Xi instead of the unnormalised structure.
Properties:Abnormal.
Macro : E.g.(SELECTQ INDEX
[A C1]
[[A1 ... AN] C2]
...
[$T Ck])
W>
(LET [[{selector} INDEX]]
(COND [(= {selector} ’A) C1]
[(MEMBER {selector} ’[A1 ... AN]) C2]
...
[$T Ck]))
Example:1> (DEFINE ACTIVITY
(LAMBDA SIMPLE [DAY]
(SELECTQ DAY
[SUNDAY ’SLEEP]
[[TUESDAY THURSDAY] ’CLASS]
[$T ’RUMINATE])))
=> ’ACTIVITY
1> (ACTIVITY ’SUNDAY)
=> ’SLEEP
1> (DEFINE ACTIVITY-2
(LAMBDA SIMPLE [DAY]
(SELECT DAY
[’SUNDAY ’SLEEP]
[[’TUESDAY ’THURSDAY] ’CLASS]
[$T ’RUMINATE])))
=> ’ACTIVITY-2
1> (ACTIVITY-2 ’SUNDAY)
=> ’SLEEP
Semantics:S(E0("SELECTQ),E,F,C) = l ...
S(E0("SELECT),E,F,C) = l ...
———————————————————
(DO [[VAR1 INIT1 NEXT1] ... [VARk INITk NEXTk]]
[[EXIT-TEST1 RETURN1] ... [EXIT-TESTj RETURNj]]
BODY)
DO is a general-purpose iteration operator (taken from SCHEME, and generalised from MACLISP and ZETALISP). The variables VAR1 through VARk are initially bound to the results of normalising the expressions INIT1 through INITk (these "initialising" expressions are normalised sequentially, but all of them are normalised before any of the bindings are established). Then each of the EXIT-TESTi are processed in order; if any is true, the corresponding expression RETURNi is processed, with the result of that RETURNi being returned as the result of the entire DO form. If none of the tests are true, BODY is processed (result ignored), and the variables VAR1 through VARk are bound to the results of processing NEXT1 through NEXTk, and the process repeats. The NEXTi are normalised in an environment in which all of the VARi remain bound to their previous bindings. BODY may be omitted.
Properties:Abnormal; env.
Macro:(DO [[VAR1 INIT1 NEXT1] ... [VARk INITk NEXTk]]
[[EXIT-TEST1 RETURN1] ... [EXIT-TESTj RETURNj]]
BODY)
W>
(LABELS
[[{loop}
(LAMBDA SIMPLE [VAR1 ... VARk]
(COND [EXIT-TEST1 RETURN1]
...
[EXIT-TESTj RETURNj]
[$T (BLOCK BODY ({loop} NEXT1 ... NEXTk))]))]]
({loop} INIT1 ... INITk))
Example:1> (DEFINE BACKWARDS-PRINT
(LAMBDA SIMPLE [STRING STREAM]
(DO [[I (LENGTH STRING) (1- I)]]
[[(ZERO I) (NEWLINE STREAM)]]
(OUTPUT (NTH I STRING) STREAM))))
=> ’BACKWARDS-PRINT
1> (BACKWARDS-PRINT "Sydney" PRIMARY-OUTPUT) yendyS
=> ’OK
1> (DEFINE NEW-REVERSE
(LAMBDA SIMPLE [VEC]
(DO [[V VEC (REST V)]
[R ((VECTOR-CONSTRUCTOR VEC) (PREP (1ST V) R)]]
[[(EMPTY V) R]])))
=> ’NEW-REVERSE
1> (NEW-REVERSE "Rogatien")
=> "neitagoR"
Semantics:S(E0("DO),E,F,C) = l ...
————————————————————————————————————————————
9.j. TRUTH VALUE OPERATIONS
————————————————————————————————————————————
(NOT E)
True if E designates falsity, and false if E designates truth.
Properties:Protected; kernel.
F-Type:[ TRUTH-VALUES ] ← TRUTH-VALUES
Examples:(NOT $F)g$T
(NOT (EVEN 102))g$F
Semantics:S(E0("NOT),E,F,C) = l ...
———————————————————
(AND E1 E2 ... Ek)
(OR E1 E2 ... Ek)
(AND E1 E2 ... EVk) is true just in case all the TVi are true; (OR E1 E2 ... Ek) is true just in case at least one of the Ei is true. Procedurally, these forms normalise their arguments one-by-one only until a deciding case is found ($F for AND; $T for OR); thus they may be able to return $T or $F even if some of their arguments are non-terminating. k may be 0; (AND) is true; (OR) is false.
Properties:Protected; kernel; abnormal.
F-Type:[ {TRUTH-VALUES}* ] ← TRUTH-VALUES
Examples:(AND (= 1 1) (= 1 2))g$F
(OR (= 1 0) (= 1 2) (= 1 1))g$T
(AND)g$T
(OR)g$F
(LET [[X 3]]
(BLOCK (AND (= 1 2)
(BLOCK (SET X 4) $T))
X))g3
Semantics:S(E0("AND),E,F,C) = l ...
S(E0("OR),E,F,C) = l ...
————————————————————————————————————————————
9.k. STRUCTURAL SIDE EFFECTS
————————————————————————————————————————————
(REPLACE S1 S2)
Replaces the pair, rail, atom, or closure designated by S1 with the structure of the same type designated by S2. Returns ’OK (therefore it will typically be used only within the scope of a BLOCK); however, subsequent to its execution the field will be altered in such a way that every relationship in which the designation of S1 participated will be changed to have the designation of S2 as its participant (with the consequence that the designation of S1 becomes henceforth inaccessible). REPLACE is not defined over the other internal structure types: numerals, charats, streamers, or handles. REPLACE is a very dangerous operation that should be used with extreme caution.
Properties:Primitive; protected; smash.
F-Types:[ PAIRS X PAIRS ] ← ATOMS
[ RAILS X RAILS ] ← ATOMS
[ CLOSURES X CLOSURES ] ← ATOMS
[ ATOMS X ATOMS ] ← ATOMS
Examples:(LET [[X ’(+ 2 3)]]
(BLOCK (REPLACE (CDR X) ’[20 30])
X))g’(+ 20 30)
(LET [[X ’[]]]
(BLOCK (REPLACE X ’[NEW TAIL])
X))g’[NEW TAIL]
(LET [[X ’[A1 A2]]]
(BLOCK (REPLACE ’A1 ’A2 )
X))g’[A2 A2]
Semantics:S(E0("REPLACE),E,F,C) = l ...
———————————————————
(RPLACA PAIR NEW-CAR)
(RPLACD PAIR NEW-CDR)
RPLACA (RPLACD) alters the pair designated by PAIR, making its CAR (CDR) be the internal structure designated by NEW-CAR (NEW-CDR). Returns ’OK.
Properties:Smash.
F-Types:[ PAIRS X STRUCTURES ] ← ATOMS
Examples:1> (SET X ’(A . B))
=> ’OK
1> (SET Y X)
=> ’OK
1> (RPLACA X ’C)
=> ’OK
1> X
=> ’(C . B)
1> Y
=> ’(C . B)
Semantics:S(E0("RPLACA),E,F,C) = l ...
S(E0("RPLACD),E,F,C) = l ...
———————————————————
(RPLACN N RAIL NEW-ELEMENT)
RPLACN alters the rail designated by RAIL, making its Nth FIRST be the internal structure designated by NEW-ELEMENT. ’OK is returned.
Properties:Protected; smash.
F-Types:[ NUMBERS X RAILS X STRUCTURES ] ← ATOMS
Examples:1> (SET X ’[ONE TWO THREE])
=> ’OK
1> (SET Y (REST X))
=> ’OK
1> (RPLACN 2 X ’**)
=> ’OK
1> X
=> ’[ONE ** THREE]
1> Y
=> ’[** THREE]
Semantics:S(E0("RPLACN),E,F,C) = l ...
———————————————————
(RPLACT N RAIL NEW-TAIL)
(RPLACT N RAIL NEW-TAIL) replaces (using REPLACE) the Nth TAIL of the rail designated by RAIL with the rail designated by NEW-TAIL. Returns ’OK.
Properties:Protected; smash.
F-Types:[ NUMBERS X RAILS X RAILS ] ← ATOMS
Examples:1> (SET X ’[ONE TWO THREE])
=> ’OK
1> (SET Y (REST X))
=> ’OK
1> (SET Z (REST Y))
=> ’OK
1> (RPLACT 1 X ’[END])
=> ’OK
1> X
=> ’[ONE END]
1> Y
=> ’[END]
1> Z
=> ’[THREE]
Semantics:S(E0("RPLACT),E,F,C) = l ...
————————————————————————————————————————————
9.l. LEVEL CROSSING OPERATORS
————————————————————————————————————————————
(DOWN S!)
↑A
If R is the referent of S!, then (DOWN S!) designates the referent of R, providing that S! is a normal-form designator, and returns R. ‘↑EXP’ expands to ‘(DOWN EXP)’ in the standard notation.
Properties:Primitive; protected; kernel.
F-Type:[ STRUCTURES ] ← OBJECTS
Examples:↑’4g4
↑(NTH 2 ’[10 20 30])g20
↑3g{ERROR: Structure expected.}
↑↑$Tg$T
↑’Xg{ERROR: Not a normal form structure.}
Semantics:S(E0("DOWN),E,F,C) = l ...
———————————————————
(UP S)
↑A
Designates the form to which S normalises. ‘↑EXP’ expands to (UP S) in the standard notation. Note that UP, although it is not a reflective procedure, is nonetheless not strictly extensional, since what it designates is a function not only of its arguments’ designation, but also of its argument’s procedural consequence (what it returns).
Properties:Primitive; protected; kernel.
F-Type:[ OBJECTS ] ← STRUCTURES
Examples:↑(+ 2 3)g’5
↑(LAMBDA SIMPLE [X] X)g’{closure: SIMPLE {global} [X] X}
[’(= 2 3) ↑(= 2 3)]g[’(= 2 3) ’$F]
(LET [[X [2 3]]]
(= ↑X ’[2 3]))g$F
(LET [[X [2 3]]]
(= ↑X ↑X))g$T
Semantics:S(E0("UP),E,F,C) = l ...
————————————————————————————————————————————
9.m. SYSTEM UTILITIES
————————————————————————————————————————————
(VERSION)
Designates a character string that identifies the 3-LISP implementation.
Properties:Protected.
F-Type:[ ] ← SEQUENCES
Example:1> (VERSION)
=> "3-LISP kernel procedures as of Decemeber 20, 1982 12:42 AM"
———————————————————
(LOADFILE FILENAME)
Loads 3-LISP definitions from the file with the same spelling as the atom designated by FILENAME. These definitions, which are stored as character strings, are stuffed into the primary stream so that subsequent READs will see them. Returns ’OK. (This is an intrim mechanism; work is under way in providing a more reasonable means of saving and loading input files.)
Properties:Primitive; protected; I/O.
F-Type:[ ATOMS ] ← ATOMS
Example:1> (LOADFILE ’MY-FILE)
=> ’OK
(... contents of file MY-FILE are read in at this point.)
———————————————————
(LOAD FILENAME)
A variant of LOADFILE that does not normalise its argument.
Properties:Abnormal; I/O.
Macro:(LOAD FILENAME)W>(LOADFILE ’FILENAME)
Example:1> (LOAD MY-FILE)
=> ’OK
(... contents of file MY-FILE are read in at this point.)
———————————————————
(EDITDEF PROCNAME)
Every time a character string of the form ‘(DEFINE FOO FUM)’ or ‘(SET FOO FUM)’ are encountered by READ the string is remembered with the atom FOO. Anytime later, (EDITDEF ’FOO) will retrieve this string so that it can be edited (with INTERLISP-D’s TTYIN). Upon completion of editing, the string is queued for READ, just as is done when a file is LOADed. Returns ’OK. (This too is an intrim mechanism; work is under way in providing a more reasonable means of editing 3-LISP code..)
Properties:Primitive; protected; I/O.
Status:Primitive
F-Type:[ ATOMS ] ← ATOMS
Example:1> (EDITDEF ’FOO)
(... the text string definition of FOO is displayed for editing.)
———————————————————
(EDIT PROCNAME)
A variant of EDITDEF that does not normalise its argument.
Properties:Abnormal; I/O.
Macro:(EDIT PROCNAME)W>(EDITDEF ’PROCNAME)
Example:1> (EDIT FOO)
(... the text string definition of FOO is displayed for editing.)
————————————————————————————————————————————
9.n. INPUT and OUTPUT
————————————————————————————————————————————
PRIMARY-STREAM
Designates the primary input-output stream through which all communication is done. Note that only characters can be read from or written to this stream.
Properties:Protected variable.
F-Type:STREAMS
Examples:PRIMARY-STREAMg{streamer}
(TYPE PRIMARY-STREAM)g’STREAM
Semantics:S(E0("PRIMARY-STREAM),E,F,C) = l ...
———————————————————
(INPUT STREAM)
Designates the next item in the stream designated by S; returns its normal-form designator. It should be assumed that S is side-effected by this operation.
Properties:Primitive; protected; I/O.
F-Type:[ STREAMS ] ← OBJECTS
Examples:1> (INPUT PRIMARY-STREAM) ?
=> #?
1> [(INPUT PRIMARY-STREAM) (INPUT PRIMARY-STREAM)] Oz
=> "Oz"
Semantics:S(E0("INPUT),E,F,C) = l ...
———————————————————
(OUTPUT S STREAM)
Puts the structure designated by S into the stream designated by STREAM. Returns ’OK. It should be assumed that STREAM is side-effected by this operation.
Properties:Primitive; protected; I/O.
F-Type:[ OBJECTS X STREAMS ] ← ATOMS
Examples:1> (OUTPUT #? PRIMARY-STREAM) ?
=> ’OK
1> [(OUTPUT #O PRIMARY-STREAM) (OUTPUT #z PRIMARY-STREAM)] Oz
=> ’OK
Semantics:S(E0("OUTPUT),E,F,C) = l ...
———————————————————
(NEWLINE STREAM)
Outputs a carriage return character to the stream designated by STREAM. Returns ’OK.
Properties:Protected; I/O.
F-Type:[ STREAMS ] ← ATOMS
Examples:1> (BLOCK (NEWLINE PRIMARY-STREAM)
(OUTPUT #? PRIMARY-STREAM)
(NEWLINE PRIMARY-STREAM))
?
=> ’OK
Semantics:S(E0("NEWLINE),E,F,C) = l ...
———————————————————
(PROMPT N STREAM)
Outputs a level N prompt to the stream designated by STREAM. Returns ’OK.
Properties:Protected; I/O.
F-Type:[ NUMBERS X STREAMS ] ← ATOMS
Examples:1> (PROMPT 100 PRIMARY-STREAM)
100>
=> ’OK
Semantics:S(E0("PROMPT),E,F,C) = l ...
———————————————————
(REPLY ANSWER STREAM)
PRINTs the structures designated by ANSWER, preceded by ‘=> ’, to the stream designated by STREAM. Returns ’OK.
Properties:Protected; I/O.
F-Type:[ STRUCTURES X STREAMS ] ← ATOMS
Examples:1> (REPLY ’1000 PRIMARY-STREAM)
=> 1000
=> ’OK
1> (BLOCK (PROMPT 100 PRIMARY-STREAM)
(REPLY (READ PRIMARY-STREAM) PRIMARY-STREAM))
100> HELLO
=> HELLO
=> ’OK
Semantics:S(E0("REPLY),E,F,C) = l ...
———————————————————
(PRINT-STRING STRING STREAM)
OUTPUTs the character in the string designated by STRING to the stream designated by STREAM. Returns ’OK.
Properties:Protected; I/O.
F-Type:[ SEQUENCES X STREAMS ] ← ATOMS
Examples:1> (PRINT-STRING "Hello there" PRIMARY-STREAM) Hello there
=> ’OK
Semantics:S(E0("PRINT-STRING),E,F,C) = l ...
———————————————————
(READ STREAM)
READ parses and internalises a character sequence notating a 3-LISP structures and returns a handle to that structure. The sequence of characters is obtained from the stream designated by STREAM. Note that all pairs and rails accessible from the result were previously completely inaccessible.
Properties:Protected; I/O; cons. (Not currently explained.)
F-Type:[ STREAMS ] ← STRUCTURES
Examples:1> (READ PRIMARY-STREAM) (A . B)
=> ’(A . B)
1> (READ PRIMARY-STREAM) ’$T
=> ’’$T
Semantics:S(E0("READ),E,F,C) = l ...
———————————————————
(PRINT S STREAM)
PRINT externalises the structures designated by S and sends the sequence of character to the stream designated by STREAM. Returns ’OK.
Properties:Protected; I/O. (Not currently explained.)
F-Type:[ STRUCTURES X STREAMS ] ← ATOMS
Examples:1> (PRINT ’(A . B) PRIMARY-STREAM) (A . B)
=> ’OK
1> (PRINT ’’$T PRIMARY-STREAM) ’$T
=> ’OK
Semantics:S(E0("PRINT),E,F,C) = l ...
———————————————————
(INTERNALISE STRING)
STRING is taken as designating a character sequence that is taken as notating a 3-LISP structure. INTERNALISE returns a handle to this structure. Note that all pairs and rails accessible from the result were previously completely inaccessible.
Properties:Protected; cons. (Not currently implemented.)
F-Type:[ SEQUENCES ] ← STRUCTURES
Examples:1> (INTERNALISE "(A . B)")
=> ’(A . B)
1> (INTERNALISE (PREP #’ "$T"))
=> ’’$T
Semantics:S(E0("INTERNALISE),E,F,C) = l ...
———————————————————
(EXTERNALISE S)
The internal structure designated by S is converted a character string that would notate this structure (up to structure isomophism). The result designates this character sequence. Note that some structures, such as circular rails, will usually cause this procedure to loop indefinitely.
Properties:Protected; cons. (Not currently implemented.)
F-Type:[ STRUCTURES ] ← SEQUENCES
Examples:1> (EXTERNALISE ’(A . B))
=> "(A . B)"
1> (2ND (EXTERNALISE ’’$T))
=> "$"
Semantics:S(E0("EXTERNALISE),E,F,C) = l ...