write(3scm) Scheme Programmer's Manual write(3scm)

write, write-shared, write-simple - write an object's external representation to a port 

(import (rnrs))                     ;R6RS
(import (rnrs io ports))            ;R6RS, put-datum
(import (rnrs io simple))           ;R6RS
(import (scheme write))             ;R7RS
(import (scheme r5rs))              ;R7RS


(write obj)
(write obj textual-output-port)
; (rnrs io ports)
(put-datum textual-output-port obj)
; R7RS only:
(write-shared obj)
(write-shared obj textual-output-port)
(write-simple obj)
(write-simple obj textual-output-port)

Writes the external representation of obj to textual-output-port. There is no trailing delimiter.

If several subsequent external representations are written to an output port, care should be taken to delimit them properly so they can be read back in by subsequent calls to get-datum(3scm).

Any object can be written to a port, but only datums are expected to have an external representation that can be read back the same with get-datum(3scm).

Default output port
If textual-output-port is omitted, it defaults to the value returned by current-output-port(3scm).
R7RS
Symbols that contain non-ASCII characters are escaped with vertical lines.
The write uses datum labels in some situations. If obj contains cycles which would cause an infinite loop using the normal written representation, then at least the objects that form part of the cycle must be represented using datum labels. Datum labels must not be used if there are no cycles.
The write-shared procedure is the same as write, except that shared structure must be represented using datum labels for all pairs and vectors that appear more than once in the output.
The write-simple procedure is the same as write, except that shared structure is never represented using datum labels. This can cause write-simple not to terminate if obj contains circular structure.

The specific external representation is implementation-dependent. However, whenever possible, an implementation should produce a representation for which get-datum(3scm), when reading the representation, will return an object equal, in the sense of equal?(3scm), to datum.

Not all datums may allow producing an external representation for which get-datum(3scm) will produce an object that is equal to the original. Specifically, NaNs contained in obj may make this impossible.

Chez Scheme
Cycles in the output are detected even in the R6RS variant of write. The print-graph parameter can be used to enable datum labels even for non-cyclic datums.
Loko Scheme
Cycles in the output are detected even in the R6RS variant of write.

R6RS
Returns unspecified values.
R7RS
Returns an unspecified value.

(call-with-string-output-port
  (lambda (p)
    (write '(lambda (x) x) p)))
    =>  "(lambda (x) x)"
(define x (list 1))
(set-cdr! x x)
(write x)
  -> #0=(1 . #0#)
(define quux "quux")
(define x (list quux quux))
(write-shared x)
  -> (#0="quux" #0#)

Writing and reading external representations of datums is used for data interchange and as an alternative to formats such as JSON and XML.

The external representations of datums vary subtly between RnRS revisions. Some differences: R6RS does not support datum labels, does not support vertical bars around symbols and uses the #vu8( prefix for bytevectors instead of #u8( as in R7RS.

Records have no standard representation in RnRS. SRFI-237 suggests are way to solve this.

This procedure can raise exceptions with the following condition types:
&assertion (R6RS)
The wrong number of arguments was passed or an argument was outside its domain. In particular, textual-output-port must be an open textual output port.
&i/o-encoding (R6RS)
The port's transcoder is in raise mode and it encountered a character that could not be translated into bytes. The untranslated character can be retrieved from the condition.
&i/o-write (R6RS)
There was an I/O error during the write operation.
&i/o-port (R6RS)
If this is included as part of an I/O condition then the port related to the I/O error can be retrieved with i/o-error-port(3scm).
R7RS
The assertions described above are errors. Implementations may signal an error, extend the procedure's domain of definition to include such arguments, or fail catastrophically.

read(3scm), display(3scm)

R4RS, IEEE Scheme, R5RS, R6RS, R7RS

The write procedure first appeared in R2RS. The write-shared and write-simple procedures are new in R7RS.

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://weinholt.se/scheme/manpages/.

2023-08-12