I/O Operations in Scheme

Scheme is a mostly functional language, and input/output is where its pragmatic side shows: I/O operations are side effects, performed for their consequences rather than their return values. Scheme makes no attempt to hide this behind a monad the way Haskell does — instead, it organizes all I/O around a single elegant abstraction: the port. A port is a first-class value representing a source or sink of data. The console, a file, even an in-memory string can all be ports, and the same display, write, and read procedures work uniformly on any of them.

That last procedure hints at something uniquely Lisp. Because Scheme code and Scheme data share the same S-expression syntax, read doesn’t just read characters — it reads an entire datum: a number, a string, or a whole nested list in one call. Pair it with write, which prints data in machine-readable form, and you get structured data persistence with no serialization library at all. This write/read round-trip has been Lisp’s native “file format” since the 1960s.

In this tutorial you’ll direct output to specific ports (including standard error and in-memory string ports), read lines and numbers from standard input, write and append to files, read them back line by line, round-trip a Scheme data structure through a file, and handle a missing file gracefully. The examples run on GNU Guile, the Scheme implementation in our Docker image.

Output and Ports

You met display and newline in Hello World. What that page didn’t show is that every output procedure accepts an optional final argument: the port to write to. When you omit it, output goes to (current-output-port) — but you can just as easily target (current-error-port) to keep diagnostics out of piped output, or a string port to build text in memory.

Guile’s built-in format covers the everyday directives: ~a inserts a value in human-readable form (like display), ~s in machine-readable form (like write), and ~% emits a newline. The first argument #t means “write to the current output port.”

Create a file named output_ports.scm:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

;; Output procedures take an optional port argument
(display "to standard output" (current-output-port))
(newline)

;; Standard error is just another port
(display "diagnostics go to standard error\n" (current-error-port))

;; format: ~a = display-style, ~s = write-style, ~% = newline
(format #t "~a is ~a years old~%" "Scheme" (- 2026 1975))
(format #t "display-style: ~a, write-style: ~s~%" "text" "text")

;; A string port collects output in memory instead of a device
(define greeting
  (call-with-output-string
    (lambda (port)
      (display "Hello from a " port)
      (display "string port" port))))
(display greeting)
(newline)

Notice that redirecting output required no new procedures — display writes to whatever port you hand it. For the full set of Common Lisp-style directives (padding, number bases, iteration), Guile offers (use-modules (ice-9 format)), which upgrades format in place.

Reading from Standard Input

Input mirrors output: read-line pulls one line from (current-input-port), returning the line without its trailing newline. In Guile, read-line lives in the (ice-9 rdelim) module, so scripts start with a use-modules form. Converting text to a number is a separate, explicit step — string->number returns the number, or #f if the string isn’t one, so bad input announces itself as a false value rather than a mysterious crash later.

Note the let* rather than let: Scheme deliberately leaves the evaluation order of plain let bindings unspecified, and when each binding performs a side effect like reading a line, the sequential guarantee of let* matters.

Create a file named read_input.scm:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

(use-modules (ice-9 rdelim))

(display "What is your name?")
(newline)

(let ((name (read-line)))
  (format #t "Hello, ~a! Enter two numbers, one per line.~%" name)
  (let* ((a (string->number (read-line)))
         (b (string->number (read-line))))
    (format #t "Their sum is ~a~%" (+ a b))))

When input runs out, read-line returns a special sentinel called the end-of-file object, which you detect with eof-object? — the next example uses exactly that to know when a file is finished.

File I/O: Lines, Data, and Errors

The idiomatic way to touch a file in Scheme is call-with-output-file and call-with-input-file. Each opens the file, passes the port to a procedure you supply, and closes the port when that procedure returns — the functional answer to forgetting to close a file handle. For modes the R7RS procedures don’t cover, such as appending, Guile provides open-file with a mode string, paired with an explicit close-port.

The middle of this example is the payoff of homoiconicity: write saves an association list to a file as literal S-expression text, and one call to read later reconstructs the entire structure. The ending shows Guile’s catch, which runs a thunk and hands any system-error (like a missing file) to a handler instead of aborting the program.

Create a file named file_io.scm:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

(use-modules (ice-9 rdelim))

;; Write a file: the port is closed automatically when the lambda returns
(call-with-output-file "journal.txt"
  (lambda (port)
    (display "day 1: learned display\n" port)
    (display "day 2: learned lambda\n" port)))

;; Append using an explicit port opened in "a" mode
(let ((port (open-file "journal.txt" "a")))
  (display "day 3: learned ports\n" port)
  (close-port port))

;; Read back line by line until the end-of-file object appears
(call-with-input-file "journal.txt"
  (lambda (port)
    (let loop ((line (read-line port))
               (n 1))
      (unless (eof-object? line)
        (format #t "~a: ~a~%" n line)
        (loop (read-line port) (+ n 1))))))

;; write and read round-trip whole Scheme data structures
(call-with-output-file "config.scm"
  (lambda (port)
    (write '((name . "archive") (retries . 3)) port)))

(let ((config (call-with-input-file "config.scm" read)))
  (format #t "retries: ~a~%" (cdr (assq 'retries config))))

;; Handle a missing file instead of crashing
(catch 'system-error
  (lambda ()
    (call-with-input-file "missing.txt" read-line))
  (lambda (key . args)
    (display "could not read missing.txt")
    (newline)))

;; Clean up
(delete-file "journal.txt")
(delete-file "config.scm")

The line-reading loop is a named let — the same tail-recursive pattern Scheme uses everywhere iteration is needed, here driven by the end-of-file object as its stopping condition. No special “read loop” construct exists because none is needed.

Running with Docker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Pull the Guile Scheme image
docker pull weinholt/guile:latest

# Run the output and ports example
docker run --rm -v $(pwd):/app -w /app weinholt/guile:latest guile --no-auto-compile output_ports.scm

# Run the stdin example, piping in three lines of input
printf 'Ada\n2\n40\n' | docker run --rm -i -v $(pwd):/app -w /app weinholt/guile:latest guile --no-auto-compile read_input.scm

# Run the file I/O example
docker run --rm -v $(pwd):/app -w /app weinholt/guile:latest guile --no-auto-compile file_io.scm

The stdin example needs Docker’s -i flag so the piped input reaches the program; without it, read-line immediately sees the end-of-file object.

Expected Output

Running output_ports.scm (in a terminal, the stderr line appears interleaved with stdout):

to standard output
diagnostics go to standard error
Scheme is 51 years old
display-style: text, write-style: "text"
Hello from a string port

Running read_input.scm with the piped input Ada, 2, 40:

What is your name?
Hello, Ada! Enter two numbers, one per line.
Their sum is 42

Running file_io.scm:

1: day 1: learned display
2: day 2: learned lambda
3: day 3: learned ports
retries: 3
could not read missing.txt

Key Concepts

• Ports unify all I/O — the console, files, and in-memory strings are all ports, and the same display, write, read, and read-line procedures work on any of them
• Output procedures take an optional port — omit it for standard output, pass (current-error-port) for diagnostics, or a string port to build text in memory
• read parses a whole datum — combined with write, Scheme data structures round-trip through files with no serialization library; the S-expression is the file format
• call-with-input-file and call-with-output-file close the port for you — the port lives exactly as long as the procedure you pass in, even if it exits early
• The end-of-file object signals exhausted input — test for it with eof-object?; it drives the named-let loops that replace imperative read loops
• string->number returns #f on bad input — parsing failures surface as an ordinary false value you can test, not an exception
• let* guarantees order, let does not — when bindings perform I/O side effects, sequential let* is the correct choice
• Guile fills the standard’s gaps — read-line comes from (ice-9 rdelim), append mode from open-file, and error handling from catch, all layered on the portable core