Page Numbers: Yes X: 306 Y: 1.0" First Page: 41
Margins: Top: 1.0" Bottom: 1.3"
Heading:

STANDARD PROCEDURE GUIDE 3-LISP REFERENCE MANUAL April 16, 1984

————————————————————————————————————————————

2.c. NOTATION and COMMUNICATION

————————————————————————————————————————————

2.c.1. NOTATION, STRINGS, and CHARACTERS

————————————————————————————————————————————

(STRING E)
(STRINGER E)

True just in case E designates a string or a stringer (a 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 E)
(CHARAT E)

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 (NTH-CHAR 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:(STRING-CONS #s "cant")g"scant"
(LET [[X "ENY"]]
(STRING-CONS #D X))g"DENY"
(STRING-CONS #I (STRING-APPEND))g"I"

(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 (STRING-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:(STRING-LENGTH "Hello There")g11
(STRING-LENGTH "")g0
(LET [[X "Testing"]]
(NTH-CHAR (STRING-LENGTH X) X))g#g

(SUBSTRING N1 N2 S)

Designates that string that beings with the N1th character of the string designated by S, and ends with with the N2th character. Designates the null string if N2 is more than one less than N1.

F-Type:[ NUMBERS X NUMBERS X STRINGS] ← STRINGSProperties: Primitive.

Examples:(SUBSTRING 3 8 "Lets get to the middle of this" 3 8)g"ts get"

(LET [[X "Test string"]]
(= X
(SUBSTRING 1
(STRING-LENGTH X)
X))g$TRUE
(SUBSTRING 2 2 "This")g"h"
(SUBSTRING 3 2 "This")g""
(SUBSTRING 4 2 "This")g""

(CHARACTER-ORDERED S1 S2)
(STRING-ORDERED 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-ORDERED #e #F)g$TRUE
(CHARACTER-ORDERED #a #A)g$FALSE
(STRING-ORDERED "Zoo" "Aardvark")g$FALSE
(STRING-ORDERED "McNeil" "McNeilly")g$TRUE
(STRING-ORDERED "" "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

————————————————————————————————————————————

2.c.2. INPUT and OUTPUT

————————————————————————————————————————————

(STREAM E)
(STREAMER E)

True just in case E designates a stream or a streamer (a normal-form stream designator), respectively.

F-Types:[ OBJECTS ] ← TRUTH-VALUESProperties: Primitive.

Examples:(STREAM PRIMARY-STREAM)g$TRUE
(STREAMER PRIMARY-STREAM)g$FALSE
(STREAMER ↑PRIMARY-STREAM)g$TRUE

PRIMARY-STREAM
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{stream}...
(TYPE PS)g’STREAM

CARRIAGE-RETURN
CR

Designates the carriage-return character. Provided for convenience.

F-Type: CHARACTERS Properties: Variable.

Examples:1> CR
1= #

1> (PRINT PS "Hello" CR "There") Hello
There
1= ’ok

(CHAR-IN STREAM)
(CHAR-OUT STREAM CH)

(CHAR-IN STREAM) designates the next character in the stream designated by S, removing that character from the stream. (CHAR-OUT STREAM CH) puts the character designated by CH into the stream designated by STREAM, returning ’OK. STREAM is side-effected by both of these operations.

F-Types: [ STREAMS ] ← CHARACTERSProperties: Primitive; I/O.
[ STREAMS X CHARACTERS ] ← ATOMS

Examples:1> (CHAR-IN PS) ?
1= #?
1> (STRING-APPEND (CHAR-IN PS) (CHAR-IN PS)) Oz
1= "Oz"

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 [[STRING STRING (SUBSTRING 2 (STRING-LENGTH STRING) STRING)]]
[[(= STRING "") ’OK]]
(CHAR-OUT PS (NTH-CHAR 1 STRING)))))
1= ’TEST
1> (TEST "This is a test of TEST") This is a test of TEST
1= ’OK

(STRING-IN STREAM DELIMITER-CH)
(STRING-OUT STREAM STRING)

(STRING-IN STREAM) designates the next string of characters in the stream designated by S up to (but not including) the character designated by DELIMITER-CH, removing all of the characters in the string and the delimiter character from the stream. (STRING-OUT STREAM CH) puts the string of characters designated by STRING into the stream designated by STREAM, returning ’OK. STREAM is side-effected by both of these operations.

F-Types: [ STREAMS X CHARACTERS ] ← STRINGSProperties: Primitive; I/O.
[ STREAMS X STRINGS ] ← ATOMS

Examples:1> (STRING-IN PS #/)
This is an input ending in/
1= "This is an input ending in"
1> (STRING-IN PS #?)?
1= ""

1> (STRING-OUT PS "This will be output")
This will be output
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-STRUCTURE STREAM)

READ-STRUCTURE parses and internalises a character sequence notating a 3-LISP structure 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-STRUCTURE PS) (A . B)
1= ’(A . B)
1> (READ-STRUCTURE PS) ’$TRUE
1= ’’$TRUE

(PRINT-STRUCTURE STREAM S)

PRINT-STRUCTURE externalises the structures designated by S and sends the sequence of characters to the stream designated by STREAM. Returns ’OK.

F-Type: [ STREAMS X STRUCTURES ] ← ATOMSProperties: I/O; cons.

Examples:1> (PRINT-STRUCTURE PS ’(A . B)) (A . B)
1= ’OK
1> (PRINT-STRUCTURE PS ’$TRUE) $TRUE
1= ’OK
1> (PRINT-STRUCTURE PS (+ 1 2))
1= {Error: Structure expected}
1> (PRINT-STRUCTURE PS (STRUCTURE-READ PS)) (+ . [1 2]) (+ 1 2)
1= ’OK

(INTERNALIZE 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; Primitive.

Examples:1> (INTERNALIZE "(A . B)")
1= ’(A . B)
1> (INTERNALIZE (STRING-CONS #’ "$TRUE"))
1= ’’$TRUE
1> (INTERNALIZE "(Unparseable]")
{Error: Malformed Notation}

(EXTERNALIZE S)

Designates the character string that notates the structure designated by S.

F-Type: [ STRUCTURES ] ← STRINGSProperties: Cons.

Examples:1> (EXTERNALIZE ’(A . B))
1= "(A . B)"
1> (STRING-NTH 2 (EXTERNALIZE ↑(= 1 2)))
1= "F"

(PRINT STREAM E1 E2 ... Ek)

PRINT is 3-LISP’s general-purpose output operation. Each of the arguments to PRINT (following the stream) is considered in turn; how they are treated depends on the type of object designated. Strings and characters are output to the stream directly (a la STRING-OUT and CHAR-OUT, respectively); structures are printed with PRINT-STRUCTURE; all other objects are coerced (via UP) to the structure that designates them. Note that because of this level-crossing coercion, care must be taken when the designational level of the object being printed isn’t perfectly clear from the context. Provided for user convenience; when being careful it is good programming practice to use stricter printing routines. Returns ’OK.

F-Type: [ STREAMS X {OBJECTS}* ] ← ATOMSProperties: I/O.

Examples:1> (PRINT PS 10)10
1= ’ok
1> (PRINT PS ’10)10 ; Note the ugly crossing of semantic levels.
1= ’ok
1> (PRINT PS "10")10 ; Ditto
1= ’ok
1> (PRINT PS "Good" "bye")Goodbye
1= ’ok
1> (PRINT PS #a #b #c)abc
1= ’ok
1> (PRINT PS ’#a)a
1= ’ok
1> (PRINT PS ’(+ 2 2))(+ 2 2)
1= ’ok
1> (PRINT PS ’ineluctable)ineluctable
1= ’ok
1> (PRINT PS ’’10)’10
1= ’ok
1> (PRINT PS)
1= ’ok
1> (PRINT PS 10 20)1020
1= ’ok
1> (PRINT PS 10 " " 20)10 20
1= ’ok

(READ STREAM)

READ obtains one object from the stream designated by STREAM. The incoming expression must notate a structure that is in normal form. READ is essentially equivalent to DOWN o INTERNALIZE o STRING-IN, defined over a string notating exactly one structure.

F-Type: [ STREAMS ] ← OBJECTSProperties: I/O.

Examples:1> (READ PS)
[1 2 3] ;typed by user
1= [1 2 3]
1> (READ PS)
’a
1= ’a

(OPEN-STREAM STRING)

OPEN-STREAM returns a streamer (a stream designator) that is connected to the file whose name is the string designated by STRING. (At present, only input streams are supported.)

F-Type: [ STRINGS ] ← STREAMSProperties: I/O.

(EMPTY-STREAM STREAM)

True (returns $TRUE) iff STREAM designates a stream from which no further characters (strings, or structures) can be obtained.

F-Type: [ STREAMS ] ← TRUTH-VALUESProperties: I/O.

(CLOSE-STREAM STREAM)

Breaks the connection between the stream designated by STREAM and the external file to which it was previously tied. Once a stream is closed, it is not possible either to acquire input from or to direct output to that stream. Returns ’OK.

F-Type: [ STREAMS ] ← STRUCTURESProperties: I/O.

(CLOSE-ALL-STREAMS)

Performs a CLOSE-STREAM on all open streams. Returns ’OK.

F-Type: [ ] ← STRUCTURESProperties: I/O.