Page Numbers: Yes X: 306 Y: 1.0" First Page: 54
Margins: Top: 1.0" Bottom: 1.3"
Heading:
STANDARD PROCEDURES3-LISP REFERENCE MANUAL March 17, 1984
————————————————————————————————————————————
4.c.9. CONTROL
————————————————————————————————————————————
(EF PREMISE C1 C2)
(IF PREMISE C1 C2)
Both (IF PREMISE C1 C2) and (EF PREMISE C1 C2) designate the referent of C1 or C2 depending on whether PREMISE designates true or false, respectively. In the case of IF, C1 (C2) is normalised only if PREMISE designates true (false), whereas EF is fully (procedurally) extensional, in the sense that all three arguments are normalised.
F-Type: [ TRUTH-VALUES X OBJECTS X OBJECTS ] ← OBJECTS
Properties: Primitive (EF only); kernel; abnormal (IF only).
Examples:1> (IF (= 1 1) ’A ’B)
1= ’A
1> (IF (= 1 2) ’A ’B)
1= ’B
1> (EF (= 1 2)
(PRINT ps "Hello ")
(PRINT ps "Good-bye")) Hello Good-bye
1= ’OK
1> (IF (= 1 2)
(PRINT ps "Hello ")
(PRINT ps "Good-bye")) Good-bye
1= ’OK
1> (EF [] ’A ’B)
{Error: Truth value expected}
(COND [P1 C1] ... [Pk Ck])
Designates Ci for the least i such that Pi designates truth. Only P1, P2, ... , Pi and Ci are normalised. Error if no Pi designates truth, or some Pi doesn’t designate a truth value.
Properties: Kernel; abnormal.
Examples:1> (COND [(= 1 2) 10]
[(= 1 3) 20]
[(= 1 1) 30]
[$TRUE 40])
1= ’30
1> (COND [(= 1 2) (PRINT ps "Once upon a time ")]
[(= 1 3) (PRINT ps "in a far away city ")]
[(= 1 1) (PRINT ps "lived a tiny little man ")]
[$TRUE (PRINT ps "in a great big house.")]) lived a tiny little man
1= ’OK
(BEGIN S1 ... Sk)
The results of normalising S1 through Sk-1 are discarded, and the result of normalising Sk is returned. Note that Sk is normalised tail-recursively with respect to the BEGIN.
F-Type: [ {OBJECTS}* X OBJECTS ] ← OBJECTS
Examples:1> (BEGIN 1 2 3)
1= 3
1> (BEGIN (PRINT ps "Once upon a time ")
(PRINT ps "in a far away city ")
(PRINT ps "lived a tiny little man ")
’DONE) Once upon a time in a far away city lived a tiny little man
1= ’DONE
(CATCH TAG BODY)
Normalising (CATCH TAG BODY) normalises BODY in the current environment extended by binding the atom TAG to a procedure which, if called, returns its argument as the result of BODY.
F-Type: [ OBJECTS ] ← OBJECTS Properties: (Hairy).
Examples:1> (CATCH FOO (+ 2 2))
1= 4
1> (CATCH TOSS (+ 2 (TOSS 3)))
1= 3
1> (CATCH TOSS
(BEGIN (TOSS (+ 3 3))
100))
1= 6
1> (CATCH THROW
(BEGIN (PRINT ps "Once upon a time ")
(PRINT ps "in a far away city ")
(THROW ’BLAST-OFF)
(PRINT ps "lived a tiny little man ")
(PRINT ps "in a great big house."))) Once upon a time in a far away city
1= ’BLAST-OFF
1> (CATCH Tag1 (+ 100 (CATCH Tag2 (* 5 (Tag2 3)))))
1= 103
1> (CATCH Tag1 (+ 100 (CATCH Tag2 (* 5 (Tag1 3)))))
1= 3
1> (CATCH Tag1
(+ 100
(CATCH Tag2
(* (Tag2 (* 6 (Tag1 4)))))))
1= 4
1> (CATCH Tag1
(+ 100
(CATCH Tag2
(* (Tag1 (* 6 (Tag2 4)))))))
2= 104
Definition:(DEFINE CATCH
(RLAMBDA [CALL CATCH-ENV CATCH-ESC CATCH-CONT]
(LET [[TAG (ARG 1 CALL)]
[BODY (ARG 2 CALL)]]
(NORMALISE BODY
(BIND TAG
↑(RLAMBDA [THROW-CALL THROW-ENV THROW-ESC THROW-CONT]
(NORMALISE (ARG 1 THROW-CALL)
THROW-ENV
THROW-ESC
CATCH-CONT))
CATCH-ENV)
CATCH-ESC
CATCH-CONT))))
(DELAY C)
Defers the normalisation of C by embedding it in a LAMBDA expression.
Properties: Abnormal.
Macro:(DELAY C)W>(LAMBDA [] C)
Examples:1> (SET X (DELAY (* Y Y)))
1= {Closure}
1> (SET Y 7)
1= 7
1> (FORCE X)
1= 49
1> (SET Y 9)
1= 9
1> (FORCE X)
1= 81
1> (DEFINE IF-EQUIVALENT
(MLAMBDA [P C1 C2]
’(FORCE (EF ,P (DELAY ,C1) (DELAY ,C2)))))
1= ’IF-EQUIVALENT
1> (IF-EQUIVALENT (= (+ 2 2) 4)
(PRINT ps "Once upon a time ")
(PRINT ps "in a far away city ")) Once upon a time
1= ’OK
(FORCE C)
Causes the normalisation of the DELAYed expression designated by C.
Examples:1> (SET X (DELAY (PRINT ps GREETING)))
1= {Closure}
1> (SET GREETING "Hi there")
1= "Hi there"
1> (FORCE X) Hi there
1= ’OK
1> (SET GREETING "Goodbye")
1= "Goodbye"
1> (FORCE X) Goodbye
1= ’OK
(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 Mi are tested from left to right, stopping as soon as a clause is selected. If Mi is an atom, the I’th clause will be selected if the selector designates this atom; if Mi is a rail, the I’th clause will be selected if the selector is a member of this rail; otherwise, Mi should be the boolean $TRUE which will always be selected, if given half a chance. Error if no clause is selected. SELECT is similar except that the selection is based on the designation of Mi instead of the unnormalised structure.
Properties: Abnormal.
Macro : E.g.(SELECTQ INDEX
[A C1]
[[A1 ... AN] C2]
...
[$TRUE Ck])
W>
(LET [[{Atom 103} INDEX]]
(COND [(= {Atom 103} ’A) C1]
[(MEMBER {Atom 103} ’[A1 ... AN]) C2]
...
[$TRUE Ck]))
Example:1> (DEFINE ACTIVITY
(LAMBDA [DAY]
(SELECTQ DAY
[SUNDAY ’SLEEP]
[[MONDAY THURSDAY] ’WORK]
[$TRUE ’RUMINATE])))
1= ’ACTIVITY
1> (ACTIVITY ’SUNDAY)
1= ’SLEEP
1> (DEFINE CURIO
(LAMBDA [VALUE]
(SELECT (* VALUE VALUE)
[(+ VALUE VALUE) ’ZERO-OR-TWO]
[$TRUE ’SOMETHING-ELSE])))
1= ’CURIO
1> (CURIO (LENGTH [1 2 3]))
1= ’SOMETHING-ELSE
(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>
(LETREC
[[{loop}
(LAMBDA [VAR1 ... VARk]
(COND [EXIT-TEST1 RETURN1]
...
[EXIT-TESTj RETURNj]
[$TRUE (BEGIN BODY ({loop} NEXT1 ... NEXTk))]))]]
({loop} INIT1 ... INITk))
Example:1> (DEFINE STRING-REVERSE
(LAMBDA [STRING]
(DO [[V VEC (STRING-REST V)]
[R "" (STRING-CONS (1ST V) R)]]
[[(STRING-EMPTY V) R]])))
1= ’STRING-REVERSE
1> (STRING-REVERSE "This is a Test")
1= "tseT a si sihT"
1> (STRING-REVERSE "Able was I ere I saw Elba")
1= "ablE was I ere I saw elbA"
————————————————————————————————————————————
4.c.10. TRUTH VALUES and BOOLEANS
————————————————————————————————————————————
(NOT E)
True if E designates false, and false if E designates true.
F-Type: [ TRUTH-VALUES ] ← TRUTH-VALUES
Examples:(NOT $F)g$TRUE
(NOT (EVEN 102))g$FALSE
(NOT 1)g{ERROR: Truth value expected.}
(AND E1 E2 ... Ek)
(OR E1 E2 ... Ek)
(AND E1 E2 ... Ek) is true just in case all the Ei 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 ($FALSE for AND; $TRUE for OR); thus they may be able to return even if some of their arguments are non-terminating. k may be 0; (AND) returns $T; (OR) returns $F.
F-Type: [ {TRUTH-VALUES}* ] ← TRUTH-VALUES Properties: Kernel (AND only); abnormal.
Examples:(AND (= 1 1) (= 1 2))g$FALSE
(OR (= 1 0) (= 1 2) (= 1 1))g$TRUE
(AND)g$TRUE
(OR)g$FALSE
(LET [[X 3]]
(BEGIN (AND (= 1 2)
(BEGIN (SET X 4) $T))
X))g3
————————————————————————————————————————————
4.c.11. LEVEL CROSSING OPERATORS
————————————————————————————————————————————
(UP S)
↑S
Designates the form to which S normalises. ‘↑S’ 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).
F-Type: [ OBJECTS ] ← STRUCTURES Properties: Primitive; kernel.
Examples:↑5g’5
↑(+ 2 3)g’5
↑(LAMBDA [X] X)g’{closure}
[’(= 2 3) ↑(= 2 3)]g[’(= 2 3) ’$FALSE]
(LET [[X [2 3]]] (= X [2 3]))g$TRUE
(LET [[X [2 3]]] (= ↑X ↑[2 3]))g$FALSE
(DOWN S)
↑S
If S designates a normal-form designator R, then (DOWN EXP) designates the designation of R, and therefore normalises to R. ‘↑S’ expands to ‘(DOWN S)’ in the standard notation.
F-Type: [ STRUCTURES ] ← OBJECTS Properties: Primitive; kernel.
Examples:↑’4g4
↑(NTH 2 ’[10 20 30])g20
↑3g{ERROR: Structure expected.}
↑↑$TRUEg$TRUE
↑’Xg{ERROR: Normal form structure expected.}
(REFERENT EXP ENV)
If EXP designates R and R normalises to R’ in the environment designated by ENV, then (REFERENT EXP ENV) will return R’. Thus REFERENT can obtain the referent of any structure, whereas DOWN is restructed to normal-form structures.
F-Type: [ STRUCTURES X ENVIRONMENTS ] ← OBJECTS
Properties: (Arbitrary effects due to sub-normalisation).
Examples:(REFERENT ’1 GLOBAL)g1
(LET [[X ’1]
[Y ’X]]
(REFERENT Y (CURRENT-ENVIRONMENT)))g1
————————————————————————————————————————————
4.c.13. SYSTEM UTILITIES
————————————————————————————————————————————
!!!!!!!!!!!!! NEEDS REVISION !!!!!!!!!!!!!
————————————————————————————————————————————
(VERSION)
Designates a character string that identifies the 3-LISP implementation.
F-Type: [ ] ← SEQUENCES
Example:1> (VERSION)
1= "3-LISP version A00. May 1, 1983"
(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 interim mechanism; work is under way in providing a more reasonable means of saving and loading input files.)
F-Type: [ ATOMS ] ← ATOMS Properties: Primitive; I/O.
Example:1> (LOADFILE ’MY-FILE)
1= ’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)
1= ’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. Note that the code for the standard procedures can be accessed in this manner. (This too is an interim mechanism; work is under way in providing a more reasonable means of editing 3-LISP code.)
F-Type: [ ATOMS ] ← ATOMS Properties: Primitive; I/O.
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 NORMALISE)
(... the text string definition of NORMALISE is displayed for editing.)
————————————————————————————————————————————
4.c.14. STRINGS and CHARACTERS
————————————————————————————————————————————
(STRING S)
(STRINGER S)
True just in case S designates a string or normal-form string designator, respectively.
F-Types:[ OBJECTS ] ← TRUTH-VALUESProperties: Primitive.
Examples:(STRING "Is this one?")g$TRUE
(STRINGER "Is this one?")g$FALSE
(STRINGER ↑"")g$TRUE
(CHARACTER)
(CHARAT)
True just in case S designates a character or normal-form character designator, respectively.
F-Type:[ OBJECTS ] ← TRUTH-VALUESProperties: Primitive.
Examples:(CHARACTER #$)g$TRUE
(CHARACTER (STRING-NTH 3 "This"))g$TRUE
(CHARAT ’#e)g$TRUE
(STRING-APPEND ST1 ... STk)
Designates the string consisting of the strings designated by ST1 ... STk, respectively, concatenated together.
F-Type:[ {STRINGS}* ] ← STRINGSProperties: Primitive.
Examples:(LET [[X "OK "]]
(STRING-APPEND X X X "Already"))g"OK OK OK Already"
(STRING-APPEND)g""
(STRING-APPEND "" "1" "" "")g"1"
(STRING-CONS CH ST)
Designates the string whose first chartacter is the character designated by CH and second through last characters are the string designated by ST.
F-Type:[ CHARACTERS X STRINGS ] ← STRINGSProperties: Primitive.
Examples:(LET [[X "OK "]]
(STRING-APPEND X X X "Already"))g"OK OK OK Already"
(STRING-APPENDgxxxx
(NTH-CHAR N STRING)
Designates the Nth character in the string designated by STRING. Characters are number from 1 through the length of the string.
F-Type:[ NUMBERS X STRINGS ] ← STRINGSProperties: Primitive.
Examples:(NTH-CHAR 3 "Hello")g#l
(NTH-CHAR 0 "Hello")g{Error: String index out of bounds}
(LET [[LAST-CHARACTER
(LAMBDA [S]
(NTH-CHAR (LENGTH S) S))]]
(LAST-CHARACTER "Pleasing"))g#g
(STRING-LENGTH STRING)
Designates the number of characters in the string designated by STRING.
F-Type:[ STRINGS ] ← NUMBERSProperties: Primitive.
Examples:xxxxgxxxx
xxxxgxxxx
(SUBSTRING S N1 N2)
Designates that string that starts at the N1th character of the string designated by S, and ending with the N2th character. Errors if N2 is less than N1.
F-Type:[ STRINGS X NUMBERS X NUMBERS] ← STRINGSProperties: Primitive.
Examples:(SUBSTRING "Lets get to the middle of this" 13 19)g"the mid"
(LET [[X "Test string"]]
(= X
(SUBSTRING X 1 (LENGTH X)))g$TRUE
(SUBSTRING "This" 2 2)g""
(SUBSTRING "This" 3 2)g{Error: String index out of bounds}
(CHARACTER-PRIOR S1 S2)
(STRING-PRIOR CH1 CH2)
True in case the character (string) designated by S1 is alphabetically prior to the character (string) designated by S2; false otherwise.
F-Types:[ STRINGS X STRINGS ] ← TRUTH-VALUESProperties: Primitive
[ CHARACTERS X CHARACTERS ] ← TRUTH-VALUES
Examples:(CHARACTER-PRIOR #e #F)g$TRUE
(CHARACTER-PRIOR #a #A)g$???
(STRING-PRIOR "Zoo" "Aardvark")g$FALSE
(STRING-PRIOR "McNeil" "McNeilly")g$TRUE
(STRING-PRIOR "" "Anything")g$TRUE
(STRING-SEARCH S1 S2)
Designates the index (character position) of the first occurence of the string designated by S1 in the string designated by S2, or zero if there is no such occurence.
F-Type:[ STRINGS X STRINGS ] ← NUMBERSProperties: Primitive.
Examples:(STRING-SEARCH "ace" "Facetious")g2
(STRING-SEARCH "no-chance" "Hello There")g0
(STRING-SEARCH "luck" "PLUCKY")g0; case matters
————————————————————————————————————————————
4.c.14. INPUT and OUTPUT
————————————————————————————————————————————
PS
Designates the primary input-output character stream through which all communication with the user is typically carried on. Only characters can be read from or written to this stream.
F-Type: STREAMS Properties: Variable.
Examples:PSg{streamer}
(TYPE PS)g’STREAM
(CHAR-IN STREAM)
Designates the next character in the stream designated by S, removing that character from the stream.
F-Type: [ STREAMS ] ← CHARACTERS Properties: Primitive; I/O.
Examples:1> (CHAR-IN PS) ?
1= #?
1> (STRING-APPEND (CHAR-IN PS) (CHAR-IN PS)) Oz
1= "Oz"
(CHAR-OUT STREAM CH)
Puts the character designated by CH into the stream designated by STREAM. Returns ’OK. STREAM is side-effected by this operation.
F-Type: [ CHARACTERS X STREAMS ] ← ATOMSProperties: Primitive; I/O.
Examples:1> (CHAR-OUT #? PRIMARY-STREAM) ?
1= ’OK
1> [(CHAR-OUT PS #O) (CHAR-OUT PS #z)] Oz
1= [’OK ’OK]
1> (DEFINE TEST
(LAMBDA [STRING]
(DO [[I 1 (1+ I)]
[CH (NTH I STRING) (NTH I STRING)]
[STRING STRING (STRING-REST STRING)]]
[[(NULL STRING) ’OK]]
(CHAR-OUT PS CH))))
1= ’TEST
1> (TEST "This is a test of TEST") This is a test of TEST
1= ’OK
(NEWLINE STREAM)
Outputs a carriage return character to the stream designated by STREAM. Returns ’OK.
F-Type: [ STREAMS ] ← ATOMS Properties: I/O.
Examples:1> (BEGIN (NEWLINE PS)
(CHAR-OUT PS #?))
?
1= ’OK
(PRINT-STRING STREAM STRING)
OUTPUTs the characters in the string designated by STRING to the stream designated by STREAM. Returns ’OK.
F-Type: [ SEQUENCES X STREAMS ] ← ATOMS Properties: I/O.
Examples:1> (PRINT-STRING PS "Hello there") Hello there
1= ’OK
(CHAR-PEEK STREAM)
Designates the next character in the stream designated by S, but does not remove that character from the stream (i.e., like CHAR-IN but without the side-effect).
F-Type: [ STREAMS ] ← CHARACTERSProperties: Primitive.
Example:1> (DEFINE READ
(COND [(= #$ (CHAR-PEEK PS)) (READ-BOOLEAN)]
[(= #’ (CHAR-PEEK PS)) (READ-HANDLE)]
... ))
(CHAR-STUFF STREAM CH)
Puts the character designated by CH back into the beginning the stream designated by STREAM. STREAM should designate a stream capable of input. Returns ’OK. STREAM is side-effected by this operation. Rarely used, but extremely valuable for programs recovering from over-anticipation.
F-Type: [ STREAMS X CHARACTERS ] ← ATOMSProperties: Primitive; I/O.
Example:1> (BEGIN (CHAR-STUFF PS #()
(CHAR-STUFF PS #+)
(CHAR-STUFF PS # )
(CHAR-STUFF PS #1)
(CHAR-STUFF PS # )
(PARGS (READ))) 2)
1= ’[1 2]
(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. All pairs, rails, and closures returned are otherwise completely inaccessible.
F-Type: [ STREAMS ] ← STRUCTURESProperties: I/O; cons.
Examples:1> (READ PS) (A . B)
1= ’(A . B)
1> (READ PS) ’$TRUE
1= ’’$TRUE
(PRINT STREAM S)
PRINT externalises the structures designated by S and sends the sequence of character to the stream designated by STREAM. Returns ’OK.
F-Type: [ STREAMS X STRUCTURES ] ← ATOMSProperties: I/O; cons.
Examples:1> (PRINT PS ’(A . B)) (A . B)
1= ’OK
1> (PRINT PS ’$TRUE) $TRUE
1= ’OK
1> (PRINT PS (+ 1 2))
1= {Error: Structure expected}
1> (PRINT (READ)) (+ . [1 2]) (+ 1 2)
1= ’OK
(INTERNALISE STRING)
Returns a handle to the structure notated by the character string designated by STRING. All pairs, closures, and rails returned are otherwise completely inaccessible.
F-Type: [ STRINGS ] ← STRUCTURESProperties: Cons.
Examples:1> (INTERNALISE "(A . B)")
1= ’(A . B)
1> (INTERNALISE (STRING-CONS #’ "$TRUE"))
1= ’’$TRUE
(EXTERNALISE S)
Designates the character string that notates the structure designated by S.
F-Type: [ STRUCTURES ] ← STRINGSProperties: Cons.
Examples:1> (EXTERNALISE ’(A . B))
1= "(A . B)"
1> (STRING-NTH 2 (EXTERNALISE ↑(= 1 2)))
1= "F"
(PRESENT STREAM E)
Presents a designator of the entity E designated by S on the stream designated by STREAM, by printing the character string that notates the normal-form designator of E to which S normalises. Returns ’OK.
F-Type: [ STREAMS X OBJECTS ] ← ATOMSProperties: I/O.
Definition:(DEFINE PRESENT
(LAMBDA [STREAM E] (PRINT STREAM ↑E)))
Examples:1> (PRESENT PS (+ 2 3)) 5
1= ’OK
(OBTAIN STREAM)
Designates that entity "designated" by the next full expression in the stream designated by STREAM.
F-Type: [ STREAMS ] ← OBJECTSProperties: I/O.
Definition:(DEFINE OBTAIN
(LAMBDA [STREAM] ↑(READ STREAM)))
Examples:1> (+ (OBTAIN PS) (OBTAIN PS)) 3 4
1= 7