SCM file format: I/O ports

Scheme does its input and output through ports: objects that deliver data (input ports) or accept it (output ports). This page follows R7RS-small section 6.13 and then describes how R6RS differs.

Port types

Implementations must support textual ports, which read and write characters (read-char, write-char, read, write), and binary ports, which read and write bytes (read-u8, write-u8). Whether the two types are disjoint, and whether input and output ports are disjoint, is left to the implementation. A port can be backed by a file, a device, a string or a bytevector.

Procedure	Meaning
`port?` `input-port?` `output-port?` `textual-port?` `binary-port?`	Predicates on any object
`input-port-open?` `output-port-open?`	Whether the port is still open (R7RS)
`current-input-port` `current-output-port` `current-error-port`	Parameter objects holding the default ports; rebind them with `parameterize`
`close-port` `close-input-port` `close-output-port`	`close-port` closes the resource and, for a port with both sides, both of them; `close-input-port` and `close-output-port` close one side of such a port (and are errors on a port that is not an input or output port). Closing a closed port has no effect
`call-with-port port proc`	Calls `proc` with the port, and closes the port if `proc` returns
`eof-object` `eof-object?`	The end-of-file object that input procedures return at the end, and its test
`flush-output-port`	Forces buffered output out

Files (scheme file)

Procedure	Meaning
`open-input-file name`, `open-output-file name`	Textual file ports. The input file must exist. An output file is a new file; if one with that name exists, the effect is unspecified. If the file cannot be opened an error that satisfies `file-error?` is signalled
`open-binary-input-file name`, `open-binary-output-file name`	Binary file ports
`call-with-input-file name proc`, `call-with-output-file name proc`	Open, call `proc` with the port, close when it returns
`with-input-from-file name thunk`, `with-output-to-file name thunk`	Rebind the current port for the call of `thunk`
`file-exists? name`, `delete-file name`	Test for and remove a file; an error is raised that `file-error?` detects when the operation fails

String and bytevector ports

Procedure	Meaning
`open-input-string string`	A textual input port that reads the characters of the string
`open-output-string`, `get-output-string port`	A textual output port that collects characters; `get-output-string` returns what has been written as a string
`open-input-bytevector bytevector`	A binary input port
`open-output-bytevector`, `get-output-bytevector port`	A binary output port and the bytes written

String ports are those of SRFI 6 (R7RS) rather than the R6RS open-string-input-port and open-string-output-port.

Input

Procedure	Meaning
`(read [port])` (read library)	Reads the external representation of one datum and returns it, or the end-of-file object. A syntax error satisfies `read-error?`
`(read-char [port])`, `(peek-char [port])`	The next character, consumed or not; `peek-char` leaves it
`(read-line [port])`	The next line without its ending (a linefeed, a carriage return, or both; others may be recognised), the characters read if the file ends mid-line, or the end-of-file object (R7RS)
`(read-string k [port])`	The next `k` characters, or as many as there are before the end of file, as a new string; the end-of-file object if none. (Some implementations take the arguments in the other order, `(read-string port k)`.)
`(char-ready? [port])`	Whether a character can be read without waiting
`(read-u8 [port])`, `(peek-u8 [port])`, `(u8-ready? [port])`	Bytes from a binary port
`(read-bytevector k [port])`, `(read-bytevector! bytevector [port start end])`	A bytevector of up to `k` bytes; or fill part of a bytevector and return the count

Output

Procedure	Meaning
`(write obj [port])` (write library)	Writes the external representation: strings in quotes with escapes, characters as `#\a`. Uses datum labels (`#0=`) for circular structure only
`(write-shared obj [port])`, `(write-simple obj [port])`	With labels for all shared structure; without ever using labels (may not terminate on circular data)
`(display obj [port])`	Writes for people: strings and characters appear without quotes or `#\`. Must terminate on circular data
`(newline [port])`	Writes the line ending
`(write-char char [port])`, `(write-string string [port start end])`	Characters and strings
`(write-u8 byte [port])`, `(write-bytevector bytevector [port start end])`	Bytes to a binary port

(import (scheme base) (scheme write) (scheme file))

(define (copy-lines in-name out-name)
  (call-with-input-file in-name
    (lambda (in)
      (call-with-output-file out-name
        (lambda (out)
          (let loop ((line (read-line in)))
            (unless (eof-object? line)
              (write-string line out)
              (newline out)
              (loop (read-line in)))))))))

(let ((p (open-output-string)))
  (write '(a "b" #\c) p)
  (get-output-string p))     ; "(a \"b\" #\\c)"

Copying a file by lines, and writing into a string port.

Other libraries of R7RS-small

(scheme load) – (load filename [environment]) reads and evaluates the forms of a file in the environment.
(scheme process-context) – command-line, exit, emergency-exit, get-environment-variable, get-environment-variables.
(scheme time) – current-second, current-jiffy, jiffies-per-second.
(scheme repl) – interaction-environment.
features (base library) – the list of feature identifiers.

(exit [obj]) runs the outstanding after thunks of dynamic-wind, ends the program, and passes an exit value to the operating system: normal exit with no argument or #t, abnormal with #f, otherwise obj translated if possible. It never returns or signals. emergency-exit ends the program without running those thunks (it is _exit of POSIX and Windows).

R6RS ports

R6RS replaced the R5RS procedures with two libraries. (rnrs io simple) holds the simple procedures R5RS had (display write newline read read-char peek-char write-char eof-object eof-object? open-input-file open-output-file call-with-input-file call-with-output-file with-input-from-file with-output-to-file close-input-port close-output-port input-port? output-port? current-input-port current-output-port current-error-port). (rnrs io ports) is the full system:

Port kinds – textual and binary; port? textual-port? binary-port? transcoded-port port-transcoder port-has-port-position? port-position port-has-set-port-position!? set-port-position! port-eof? close-port call-with-port.
Transcoders – a transcoder is made from a codec, an end-of-line style and an error-handling mode: make-transcoder native-transcoder transcoder-codec transcoder-eol-style transcoder-error-handling-mode, with latin-1-codec utf-8-codec utf-16-codec native-eol-style and the syntax (eol-style lf) and (error-handling-mode replace). bytevector->string and string->bytevector convert with a transcoder.
Opening – open-file-input-port open-file-output-port open-file-input/output-port (with file-options and buffer-mode), open-bytevector-input-port open-bytevector-output-port call-with-bytevector-output-port open-string-input-port open-string-output-port call-with-string-output-port, standard-input-port standard-output-port standard-error-port, and custom ports made from procedures: make-custom-binary-input-port and the five like it.
Input and output – get-u8 lookahead-u8 get-bytevector-n get-bytevector-n! get-bytevector-some get-bytevector-all get-char lookahead-char get-string-n get-string-n! get-string-all get-line get-datum; put-u8 put-bytevector put-char put-string put-datum; flush-output-port output-port-buffer-mode.
Conditions – &i/o and its subtypes (see Error handling) such as &i/o-file-does-not-exist.

(rnrs files) adds file-exists? and delete-file, and (rnrs programs) adds command-line and exit.

Not described

Known, not yet covered

Reference: the exact behaviour of read-line on different line endings, of write for symbols that need bars, and of char-ready? are in the report and not described.
Reference: the I/O SRFIs (6 string ports, 181 custom ports, 106 sockets, 193 command line) are named only; see SRFI.
Reference: the formatting of format (SRFI 28, and the larger directives of Guile, Chez, Gauche and others) is only touched on Lexical structure.

.SCM File Format – I/O ports