Wile

R7RS Scheme in pure Go. No CGo, no C toolchain, no cross-compilation pain.

Full hygienic macros, first-class continuations, numeric tower, and sandboxing. go get and it just works.

Embed Scheme in 4 lines of Go

engine, _ := wile.NewEngine(ctx)
engine.Define("width", wile.NewInteger(800))
engine.Define("height", wile.NewInteger(600))
result, _ := engine.Eval(ctx, "(* width height)")  // => 480000

Why Wile?

Embedding a Lisp in Go means tradeoffs:

Approach	Problem
Chibi-Scheme, S7 via CGo	Slow builds, broken cross-compilation, platform toolchain pain
Lisp subsets (Zygomys, etc.)	No R7RS compliance, limited ecosystem
Lua via go-lua	Not a Lisp, no macros, different semantics
JavaScript via goja	Heavy runtime, no hygiene, async complexity

Wile solves this: Full R7RS Scheme in pure Go. Scheme values are Go heap objects, collected by Go's GC. No custom allocator, no FFI tax, no surprises.

Feature	Wile	Chibi/S7 (CGo)	Goja (JS)	Starlark	Lua
Pure Go	✓	✗	✓	✓	✗
Hygienic macros	✓	✓	✗	✗	✗
R7RS compliance	✓	✓	N/A	N/A	N/A
First-class continuations	✓	✓	✗	✗	✗
Cross-compilation	✓	✗	✓	✓	✗
Go GC integration	✓	✗	✓	✓	✗

Performance

Gabriel benchmarks (16 programs), showing gains from allocation and dispatch optimizations:

Benchmark	v1.3.0	v1.4.0	Change
tak	0.381s	0.274s	-28%
fib	1.262s	0.920s	-27%
sumfp	4.271s	3.204s	-25%
peval	0.168s	0.134s	-20%
Geo-mean (all 16)			-15%

Full results and methodology in examples/benchmarks/.

Embedding in Go

The wile package provides the public API for embedding Scheme in Go.

Basic Usage

import "github.com/aalpar/wile"

// Create an engine
engine, err := wile.NewEngine(ctx)
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(ctx, "(+ 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(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

Constructor	Creates
`wile.NewInteger(n)`	Exact integer
`wile.NewBigInteger(n)`	Exact arbitrary-precision integer (`*big.Int`)
`wile.NewFloat(f)`	Inexact real
`wile.NewBigFloat(f)`	Inexact arbitrary-precision float (`*big.Float`)
`wile.NewRational(num, den)`	Exact rational
`wile.NewComplex(v)`	Complex number (`complex128`)
`wile.NewString(s)`	String
`wile.NewSymbol(s)`	Symbol
`wile.NewBoolean(b)`	`#t` / `#f`
`wile.True` / `wile.False`	Boolean constants
`wile.NewVector(vals...)`	Vector
`wile.NewList(vals...)`	Proper list
`wile.EmptyList`	Empty list `'()`
`wile.Void`	Void value

The values package provides additional constructors (e.g., NewRationalFromBigInt, NewComplexFromParts).

Engine Options

Option	Description
`wile.WithExtension(ext)`	Add a single extension
`wile.WithExtensions(exts...)`	Add multiple extensions
`wile.WithSafeExtensions()`	Add safe extension set (no filesystem, eval, system, threads)
`wile.WithoutCore()`	Skip core primitives — bare engine with only explicit extensions
`wile.WithLibraryPaths(paths...)`	Enable R7RS library system with search paths
`wile.WithMaxCallDepth(n)`	Set maximum VM recursion depth
`wile.WithAuthorizer(auth)`	Set fine-grained runtime authorization policy
`wile.WithRegistry(r)`	Use a custom registry instead of the default core primitives

Quick Start

# Install as a command-line tool
go install github.com/aalpar/wile/cmd/wile@latest

# Or download a prebuilt binary from releases
# https://github.com/aalpar/wile/releases

# Run the REPL
scheme

# Try an example
scheme --file examples/basics/hello.scm

# See all examples
ls examples/

Explore:

76 Examples — Basics, macros, concurrency, numeric tower, and more
Gabriel Benchmarks — Scheme benchmarks for performance testing
Schelog — Full Prolog-style logic programming embedded in Scheme
Embedding Guide — How to use Wile from Go

Key Features in Action

Logic Programming — Full Prolog embedded in Scheme

(load "examples/logic/schelog/schelog.scm")

(%rel (append xs ys zs)
  ((append () ?ys ?ys))
  ((append (?x . ?xs) ?ys (?x . ?zs))
   (append ?xs ?ys ?zs)))

(%which (zs)
  (append '(1 2) '(3 4) zs))
;; ⇒ ((zs 1 2 3 4))

See examples/logic/schelog/ for a self-contained Prolog implementation in Scheme.

Numeric Tower — Exact rationals, complex numbers, and arbitrary precision

(/ 1 3)              ; ⇒ 1/3 (exact rational, not 0.333...)
(* 1/3 3)            ; ⇒ 1 (exact)
(make-rectangular 0 1) ; ⇒ 0+1i (exact complex)
(expt 2 1000)        ; ⇒ 10715086071862673209484250490...

Hygienic Macros — Build DSLs without variable capture

(load "examples/macros/state-machine.scm")

(define-state-machine traffic-light
  (states: red yellow green)
  (initial: red)
  (transitions:
   (red -> green)
   (green -> yellow)
   (yellow -> red)))

Go-Native Concurrency — Goroutines and channels from Scheme

(let ((ch (make-channel)))
  (thread-start!
   (make-thread
    (lambda () (channel-send! ch 42))))
  (channel-receive ch))  ; ⇒ 42

First-Class Continuations — Non-local control flow

;; Early return
(call/cc (lambda (return)
  (for-each (lambda (x)
              (if (negative? x)
                  (return x)))
            '(1 2 -3 4))
  'not-found))  ; ⇒ -3

;; See examples/control/ for generators, coroutines, and backtracking

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}/wile.

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 a debugger. Commands start with ,:

Command	Description
`,break FILE:LINE`	Set breakpoint
`,delete ID`	Delete breakpoint
`,list`	List breakpoints
`,step`	Step into next expression
`,next`	Step over (same frame)
`,finish`	Step out (return from function)
`,continue`	Continue execution
`,backtrace`	Show stack trace
`,where`	Show current source location

R7RS Standard Libraries

Library	Description
`(scheme base)`	Core language: arithmetic, pairs, lists, strings, vectors, control
`(scheme case-lambda)`	`case-lambda` form
`(scheme char)`	Character predicates and case conversion
`(scheme complex)`	Complex number operations
`(scheme cxr)`	Compositions of `car` and `cdr`
`(scheme eval)`	`eval` and `environment`
`(scheme file)`	File I/O
`(scheme inexact)`	Transcendental functions (`sin`, `cos`, `exp`, `log`, `sqrt`, etc.)
`(scheme lazy)`	Promises (`delay`, `force`, `make-promise`)
`(scheme load)`	`load`
`(scheme read)`	`read`
`(scheme write)`	`write`, `display`
`(scheme repl)`	`interaction-environment`
`(scheme process-context)`	`command-line`, `exit`, `get-environment-variable`
`(scheme time)`	`current-second`, `current-jiffy`, `jiffies-per-second`
`(scheme r5rs)`	R5RS compatibility

Additional Libraries

Library	Description
`(srfi 1)`	List library (constructors, predicates, fold, search, set operations)
`(chibi test)`	Minimal test framework (for R7RS test compatibility)
`(chibi diff)`	Diff utilities
`(chibi optional)`	Optional value handling
`(chibi term ansi)`	ANSI terminal escape codes

Extension Libraries

With the library system enabled (WithLibraryPaths), Go extensions import as (wile <name>):

Library	Description
`(wile math)`	Transcendental functions, numeric utilities
`(wile files)`	File I/O
`(wile threads)`	SRFI-18 multithreading (threads, mutexes, condition variables)
`(wile system)`	System interaction (environment, process)
`(wile exceptions)`	Exception handling
`(wile gointerop)`	Go interop primitives
`(wile introspection)`	Reflection and introspection

See docs/EXTENSION_LIBRARIES.md for import syntax and modifiers.

Architecture

Source → Tokenizer → Parser → Expander → Compiler → VM

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

Package Structure

Package	Purpose
`wile` (root)	Public embedding API
`machine/`	Virtual machine, compiler, macro expander
`values/`	Scheme value types (numbers, pairs, ports, threads, etc.)
`werr/`	Error infrastructure (sentinel errors, contextual wrapping)
`environment/`	Variable binding, scope chains, phase hierarchy
`registry/`	Extension registration and primitives
`registry/core/`	Essential primitives and bootstrap macros
`security/`	Fine-grained runtime authorization
`registry/helpers/`	Shared utilities for primitive implementations
`extensions/`	Public extension packages (files, math, threads, system, etc.)
`runtime/`	Compile/Run API for embedding
`internal/syntax/`	First-class syntax objects with scope sets
`internal/match/`	Pattern matching engine for macros
`internal/parser/`	Scheme parser
`internal/tokenizer/`	Lexer
`internal/validate/`	Syntax validation
`internal/forms/`	Compiled form definitions
`internal/schemeutil/`	Scheme utility functions
`internal/repl/`	Interactive REPL with debugger
`internal/bootstrap/`	Environment initialization
`internal/extensions/`	Internal extension wiring (io, eval, aggregate registration)

API Stability

These packages form the public API and follow Go module versioning:

wile (root) — Engine, RegisterFunc, Eval/Compile/Run, error types
values — Scheme value types, Value interface, numeric tower
werr — Sentinel errors, WrapForeignErrorf, error infrastructure
registry — Registry, Extension, PrimitiveSpec, phase constants
security — Authorizer, AccessRequest, built-in authorizers
extensions/* — Public extensions (files, math, threads, system, etc.)

All other packages (machine/, environment/, internal/) are implementation details and may change without notice. The machine package is importable but carries no compatibility guarantees.

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

Type	Description	Example
Integer	Exact 64-bit signed	`42`, `-17`
BigInteger	Exact arbitrary precision	`#z12345678901234567890`
Rational	Exact fraction	`3/4`, `-1/2`
Float	Inexact IEEE 754 double	`3.14`, `1e10`
BigFloat	Inexact arbitrary precision	`#m3.14159265358979323846`
Complex	Complex number	`1+2i`, `3@1.57` (polar)

Concurrency Types

Type	Description
Thread	SRFI-18 thread
Mutex	SRFI-18 mutex
Condition Variable	SRFI-18 condition variable
Channel	Go channel wrapper
WaitGroup	Go sync.WaitGroup wrapper
RWMutex	Go sync.RWMutex wrapper
Atomic	Thread-safe mutable value

Sandboxing

Wile sandboxes embedded engines with two independent, composable layers.

Layer 1: Extension-based (compile-time)

Primitives not loaded into the engine don't exist. Attempts to use them produce compile-time errors — there are no runtime checks to bypass.

// Safe sandbox: no filesystem, eval, system, or threading
engine, err := wile.NewEngine(ctx, wile.WithSafeExtensions())

Compose with specific privileged extensions:

engine, err := wile.NewEngine(ctx,
    append(wile.SafeExtensions(),
        wile.WithExtension(files.Extension),
    )...,
)

Library environments inherit the engine's registry, so restrictions propagate transitively to loaded libraries.

Layer 2: Fine-grained authorization (runtime)

The security.Authorizer interface gates privileged operations with K8s-style resource+action vocabulary:

engine, err := wile.NewEngine(ctx,
    wile.WithSafeExtensions(),
    wile.WithExtension(files.Extension),
    wile.WithAuthorizer(security.All(
        security.ReadOnly(),
        security.FilesystemRoot("/app/data"),
    )),
)
// Can read files under /app/data, nothing else

Built-in authorizers: DenyAll(), ReadOnly(), FilesystemRoot(path), All(authorizers...) (AND-composition).

See docs/SANDBOXING.md for the full security model, extension classification, known gaps, and custom authorizer examples.

Documentation

Document	Description
`docs/SCHEME_REFERENCE.md`	Complete Scheme language reference
`docs/SANDBOXING.md`	Sandboxing and security model
`docs/EXTENSIONS.md`	Extension system architecture and authoring guide
`docs/EXTENSION_LIBRARIES.md`	R7RS library integration for extensions
`PRIMITIVES.md`	Complete reference of types and primitives
`docs/design/DESIGN.md`	Macro system design
`docs/design/EMBEDDING.md`	Embedding API design
`docs/design/DELIMITED_CONTINUATIONS.md`	Delimited continuation implementation
`docs/dev/NUMERIC_TOWER.md`	Numeric tower architecture
`docs/dev/ENVIRONMENT_SYSTEM.md`	Environment system architecture
`docs/dev/R7RS_SEMANTIC_DIFFERENCES.md`	Documented differences from R7RS
`BIBLIOGRAPHY.md`	Academic references
`CHANGELOG.md`	Release history

References

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

Contributing

Wile welcomes contributions. Help wanted:

Documentation — Examples, guides, tutorials
Standard library — R7RS-small features, SRFI implementations
Test coverage — Broader coverage across packages
Performance — Allocation reduction, targeted optimizations
Tooling — REPL improvements, debugging tools, IDE integration

Get started:

Browse issues labeled good-first-issue
Check help wanted for high-priority items
Read CONTRIBUTING.md for guidelines and workflow

License

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

Name		Name	Last commit message	Last commit date
Latest commit History 1,196 Commits
.github		.github
benchmarks/larceny		benchmarks/larceny
cmd		cmd
docker		docker
docs		docs
environment		environment
examples		examples
extensions		extensions
integration		integration
internal		internal
lib		lib
machine		machine
plans		plans
registry		registry
ruleguard		ruleguard
runtime		runtime
scm		scm
scripts		scripts
security		security
test		test
tools/sh		tools/sh
values		values
werr		werr
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
BIBLIOGRAPHY.md		BIBLIOGRAPHY.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODING_STYLE.md		CODING_STYLE.md
CONTRIBUTING.md		CONTRIBUTING.md
COPYRIGHT_HEADER		COPYRIGHT_HEADER
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
PACKAGE		PACKAGE
PLAN_ISSUES_TEMPLATE.md		PLAN_ISSUES_TEMPLATE.md
PLAN_TODO_TEMPLATE.md		PLAN_TODO_TEMPLATE.md
PRIMITIVES.md		PRIMITIVES.md
README.md		README.md
TODO.md		TODO.md
TODO_ISSUES_TEMPLATE.md		TODO_ISSUES_TEMPLATE.md
VERSION		VERSION
compiled.go		compiled.go
crossbuild_test.go		crossbuild_test.go
doc.go		doc.go
engine.go		engine.go
engine_error_chain_test.go		engine_error_chain_test.go
engine_library_test.go		engine_library_test.go
engine_sandbox_test.go		engine_sandbox_test.go
error.go		error.go
example_test.go		example_test.go
ffi.go		ffi.go
ffi_test.go		ffi_test.go
go.mod		go.mod
go.sum		go.sum
library_test.go		library_test.go
opcode_fusion_test.go		opcode_fusion_test.go
options.go		options.go
peephole_census_test.go		peephole_census_test.go
primitive.go		primitive.go
readme_test.go		readme_test.go
value.go		value.go
value_helpers.go		value_helpers.go
wile_bench_test.go		wile_bench_test.go
wile_test.go		wile_test.go
with_source_test.go		with_source_test.go

Folders and files

Latest commit

History

Repository files navigation

Wile

Embed Scheme in 4 lines of Go

Table of Contents

Why Wile?

Performance

Embedding in Go

Basic Usage

Compile Once, Run Many Times

Bridging Go and Scheme

Value Constructors

Engine Options

Quick Start

Key Features in Action

Installation

As a library

As a standalone interpreter

Usage

REPL Debugger

R7RS Standard Libraries

Additional Libraries

Extension Libraries

Architecture

Package Structure

API Stability

Hygiene Model

Types

Numeric Tower

Concurrency Types

Sandboxing

Layer 1: Extension-based (compile-time)

Layer 2: Fine-grained authorization (runtime)

Documentation

References

Contributing

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages