wile

Wile

A R7RS Scheme interpreter/compiler in Go with hygienic macros.

The name is a play on "scheme" (as in "wiles" - cunning stratagems) and a nod to Wile E. Coyote, the cartoon schemer.

Overview

Wile compiles Scheme source code to bytecode and executes it on a stack-based virtual machine. It implements R7RS-style syntax-rules and syntax-case macros with a "sets of scopes" hygiene model (Flatt 2016).

Wile is designed as a Scheme scripting layer that feels native to Go. It provides what Go intentionally lacks — hygienic macros, first-class continuations, symbolic computation — without requiring CGo, a C toolchain, or cross-compilation headaches. Add it with go get and it just works.

Background

Wile was originally a Lisp interpreter (compiler and VM) used for scripting block-based storage systems (databases, pipelines, search, etc.). It's been recently expanded to the Scheme R7RS standard in the hopes that it will be of use to someone who wants to use Lisp/Scheme in Go.

Why Another Scheme Implementation?

Existing Scheme-in-Go implementations are typically toys or subsets. Embedding a production Scheme like Chibi-Scheme or S7 requires CGo, which means slow builds, broken cross-compilation, and platform-specific toolchain pain. Wile is pure Go: Scheme values are Go heap objects collected by Go's GC, so there's no custom allocator to maintain and the GC improves for free with each Go release.

Use of AI

Anthropic's Claude Code was used to help document, fill out the primitive library, and diagnose bugs. The CLAUDE.md file is committed to help others get started.

Features

Core Language

• R7RS-small compliance — Full conformance with all standard libraries
• Hygienic macros — syntax-rules and syntax-case with the "sets of scopes" model (Flatt 2016)
• First-class continuations — call/cc and dynamic-wind with proper semantics
• Delimited continuations — call-with-continuation-prompt, abort-current-continuation, and composable continuations
• Full numeric tower — Integers, rationals, floats, complex numbers with exact/inexact distinction
• Arbitrary precision — BigInteger and BigFloat with automatic overflow promotion
• Library system — define-library, import, export with configurable search paths
• Records — define-record-type (SRFI-9 style)
• Promises — delay, force, and lazy evaluation

Runtime

• Bytecode compilation — Scheme code compiles to an efficient bytecode representation
• Stack-based VM — Proper tail-call optimization
• SRFI-18 threading — Threads, mutexes, and condition variables
• Go concurrency interop — Channels, WaitGroups, RWMutex, Once, Atomic values
• Exception handling — guard, with-exception-handler, raise

Tooling

• Interactive REPL — Readline support with history and multi-line input
• Source-level debugger — Breakpoints, stepping, stack traces
• Pure Go — No CGo, no C dependencies, works with go get
• Go embedding API — Clean API for evaluating Scheme from Go and registering Go functions as primitives

Installation

Requires Go 1.23 or later.

As a library

go get github.com/aalpar/wile@latest

As a standalone interpreter

Download a prebuilt binary from Releases, or build from source:

git clone https://github.com/aalpar/wile.git
cd wile
make build

The binary is built to ./dist/{os}/{arch}/scheme.

Usage

# Start REPL
scheme

# Run a Scheme file
scheme example.scm
scheme --file example.scm
scheme -f example.scm

# With library search path
scheme -L /path/to/libs example.scm

# Enter REPL after loading file
scheme -f example.scm -i

# Print version
scheme --version

The SCHEME_LIBRARY_PATH environment variable provides additional library search paths (colon-separated).

REPL Debugger

The REPL includes an integrated debugger. Commands start with ,:

Examples

Hygienic Macros

(define-syntax swap!
  (syntax-rules ()
    ((swap! x y)
     (let ((tmp x))
       (set! x y)
       (set! y tmp)))))

(let ((a 1) (b 2))
  (swap! a b)
  (list a b))
;; => (2 1)

First-Class Continuations

(call-with-current-continuation
  (lambda (exit)
    (for-each (lambda (x)
                (if (negative? x) (exit x)))
              '(54 0 37 -3 245 19))
    #t))
;; => -3

Delimited Continuations

(define tag (make-continuation-prompt-tag 'example))

(call-with-continuation-prompt
  (lambda ()
    (+ 1 (abort-current-continuation tag 42)))
  tag
  (lambda (v) (* v 2)))
;; => 84

Threads (SRFI-18)

(import (srfi 18))

(define counter 0)
(define mtx (make-mutex))

(define (increment!)
  (mutex-lock! mtx)
  (set! counter (+ counter 1))
  (mutex-unlock! mtx))

(define threads
  (map (lambda (_)
         (make-thread increment!))
       (iota 10)))

(for-each thread-start! threads)
(for-each thread-join! threads)
counter
;; => 10

Go Channels

(define ch (make-channel 10))  ; buffered channel

(channel-send! ch 42)
(channel-receive ch)
;; => 42

Embedding in Go

Wile provides a public API for embedding Scheme in Go programs via the wile package.

Basic Usage

import "github.com/aalpar/wile"

// Create an engine
engine, err := wile.NewEngine()
if err != nil {
    log.Fatal(err)
}

// Evaluate a single expression
result, err := engine.Eval(ctx, "(+ 1 2 3)")
fmt.Println(result.SchemeString()) // "6"

// Evaluate multiple expressions (returns last result)
result, err = engine.EvalMultiple(ctx, `
  (define x 10)
  (define y 20)
  (+ x y)
`)

Compile Once, Run Many Times

compiled, err := engine.Compile("(+ x 1)")
result, err := engine.Run(ctx, compiled)

Bridging Go and Scheme

Define Go values in Scheme's environment:

engine.Define("my-var", wile.NewInteger(100))
val, ok := engine.Get("my-var")

Register a Go function as a Scheme primitive:

import "github.com/aalpar/wile/values"

engine.RegisterPrimitive(wile.PrimitiveSpec{
    Name:       "go-add",
    ParamCount: 2,
    Impl: func(ctx context.Context, mc *wile.MachineContext) error {
        a := mc.Arg(0).(*values.Integer).Value
        b := mc.Arg(1).(*values.Integer).Value
        mc.SetValue(values.NewInteger(a + b))
        return nil
    },
})
// Now callable from Scheme: (go-add 3 4) => 7

Call a Scheme procedure from Go:

proc, _ := engine.Get("my-scheme-function")
result, err := engine.Call(ctx, proc, wile.NewInteger(42))

Value Constructors

Engine Options

R7RS Standard Libraries

Additional Libraries

Architecture

Source → Tokenizer → Parser → Expander → Compiler → VM

1. Tokenizer — Lexical analysis with comprehensive R7RS token support
2. Parser — Builds syntax tree with source location tracking
3. Expander — Macro expansion using syntax-rules/syntax-case with scope sets
4. Compiler — Generates bytecode operations
5. VM — Executes bytecode with stack-based evaluation

Package Structure

Hygiene Model

Wile uses the "sets of scopes" approach from Flatt's 2016 paper. Each identifier carries a set of scopes, and variable resolution checks that the binding's scopes are a subset of the use site's scopes:

bindingScopes ⊆ useScopes

This prevents unintended variable capture in macros:

(define-syntax swap!
  (syntax-rules ()
    ((swap! x y)
     (let ((tmp x))    ; tmp gets macro's scope
       (set! x y)
       (set! y tmp)))))

(let ((tmp 5) (a 1) (b 2))  ; this tmp has different scope
  (swap! a b)
  tmp)  ; => 5, not captured by macro's tmp

Types

Numeric Tower

Concurrency Types

Documentation

References

• Binding as Sets of Scopes — Flatt (2016)
• R7RS Scheme — Language specification
• SRFI-18 — Multithreading

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.