wile

README

Wile

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

Full hygienic macros, first-class continuations, and numeric tower. 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 has always required 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	✓	✗	✓	✓	✗

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(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(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

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.Null	Empty list '()
wile.Void	Void value

Additional constructors (e.g., NewRationalFromBigInt, NewComplexFromParts) are available in the values package.

Engine Options

Option	Description
wile.WithRegistry(r)	Use a custom registry instead of the default core primitives
wile.WithExtension(ext)	Add a single extension
wile.WithExtensions(exts...)	Add multiple extensions

Quick Start

# Install as a command-line tool
go install github.com/aalpar/wile/cmd/scheme@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:

• 72 Examples — Basics, macros, concurrency, numeric tower, and more
• Gabriel Benchmarks — 21 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}/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 ,:

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 18)	Multithreading (threads, mutexes, condition variables)
(chibi test)	Minimal test framework (for R7RS test compatibility)

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

Package	Purpose
wile (root)	Public embedding API
machine/	Virtual machine, compiler, macro expander
values/	Scheme value types (numbers, pairs, ports, threads, etc.)
environment/	Variable binding, scope chains, phase hierarchy
registry/	Extension registration and primitives
registry/core/	Essential primitives and bootstrap macros
registry/helpers/	Shared utilities for primitive implementations
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/	Extension packages (io, files, math, threads, etc.)

API Stability

The following 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
• registry — Registry, Extension, PrimitiveSpec, phase constants

All other packages (machine/, environment/, internal/) are implementation details and may change without notice. The machine package is technically importable but is not covered by 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

Documentation

Document	Description
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! We're actively looking for help with:

• Documentation — Examples, guides, tutorials
• Standard library — R7RS-small features, SRFI implementations
• Test coverage — Improving test 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.

Documentation

Overview

Package wile provides the public API for embedding the Wile Scheme interpreter.

Basic usage:

engine, err := wile.NewEngine(ctx)
if err != nil {
    log.Fatal(err)
}
result, err := engine.Eval(ctx, "(+ 1 2 3)")
fmt.Println(result) // 6

With extensions:

engine, err := wile.NewEngine(ctx,
    wile.WithExtension(io.Extension),
    wile.WithExtension(system.Extension),
)

Custom primitives:

engine, _ := wile.NewEngine(ctx)
engine.RegisterPrimitive(wile.PrimitiveSpec{
    Name:       "my-func",
    ParamCount: 1,
    Impl:       myFuncImpl,
})

Index

• Variables
• func IsBoolean(v Value) bool
• func IsList(v Value) bool
• func IsNull(v Value) bool
• func IsNumber(v Value) bool
• func IsPair(v Value) bool
• func IsProcedure(v Value) bool
• func IsString(v Value) bool
• func IsSymbol(v Value) bool
• func ToGoBool(v Value) (bool, bool)
• func ToGoFloat(v Value) (float64, bool)
• func ToGoInt(v Value) (int64, bool)
• func ToGoString(v Value) (string, bool)
• type CompilationError
  • func (p *CompilationError) Error() string
  • func (p *CompilationError) Unwrap() error
• type CompiledCode
  • func (p *CompiledCode) String() string
• type Engine
  • func NewEngine(ctx context.Context, opts ...EngineOption) (*Engine, error)
  • func (p *Engine) Call(ctx context.Context, proc Value, args ...Value) (Value, error)
  • func (p *Engine) Close() error
  • func (p *Engine) Compile(ctx context.Context, code string) (*CompiledCode, error)
  • func (p *Engine) CompileWithSource(ctx context.Context, code string, source string) (*CompiledCode, error)
  • func (p *Engine) CurrentLoadDirectory() string
  • func (p *Engine) CurrentLoadPath() string
  • func (p *Engine) Define(name string, value Value) error
  • func (p *Engine) Environment() *environment.EnvironmentFrame
  • func (p *Engine) Eval(ctx context.Context, code string) (Value, error)
  • func (p *Engine) EvalMultiple(ctx context.Context, code string) (Value, error)
  • func (p *Engine) EvalMultipleWithSource(ctx context.Context, code string, source string) (Value, error)
  • func (p *Engine) EvalWithSource(ctx context.Context, code string, source string) (Value, error)
  • func (p *Engine) Get(name string) (Value, bool)
  • func (p *Engine) LastCounters() machine.VMCounters
  • func (p *Engine) PopLoadPath()
  • func (p *Engine) PushLoadPath(absPath string) error
  • func (p *Engine) RegisterFunc(name string, fn any) error
  • func (p *Engine) RegisterFuncs(funcs map[string]any) error
  • func (p *Engine) RegisterPrimitive(spec PrimitiveSpec) error
  • func (p *Engine) Run(ctx context.Context, cc *CompiledCode) (Value, error)
  • func (p *Engine) TopLevelEnvironment() *environment.TopLevelEnvironment
  • func (p *Engine) WithLoadPath(absPath string, fn func() error) error
• type EngineOption
  • func WithExtension(ext registry.Extension) EngineOption
  • func WithExtensions(exts ...registry.Extension) EngineOption
  • func WithLibraryPaths(paths ...string) EngineOption
  • func WithMaxCallDepth(n uint64) EngineOption
  • func WithRegistry(r *registry.Registry) EngineOption
• type Error
  • func (p *Error) Error() string
  • func (p *Error) Unwrap() error
• type ForeignFunction
• type MachineContext
• type PrimitiveSpec
• type RuntimeError
  • func (p *RuntimeError) Error() string
  • func (p *RuntimeError) IsSchemeException() bool
  • func (p *RuntimeError) Unwrap() error
• type Value
  • func Car(v Value) (Value, bool)
  • func Cdr(v Value) (Value, bool)
  • func NewBigFloat(f *big.Float) Value
  • func NewBigFloatFromFloat64(f float64) Value
  • func NewBigFloatFromString(s string) Value
  • func NewBigInteger(n *big.Int) Value
  • func NewBigIntegerFromInt64(n int64) Value
  • func NewBigIntegerFromString(s string, base int) Value
  • func NewBoolean(b bool) Value
  • func NewComplex(v complex128) Value
  • func NewComplexFromParts(realPart, imagPart float64) Value
  • func NewFloat(f float64) Value
  • func NewInteger(n int64) Value
  • func NewList(vals ...Value) Value
  • func NewRational(num, denom int64) Value
  • func NewRationalFromBigInt(num, denom *big.Int) Value
  • func NewString(s string) Value
  • func NewSymbol(s string) Value
  • func NewVector(vals ...Value) Value
  • func ToSlice(ctx context.Context, v Value) ([]Value, bool)

Examples

• Engine.Call
• Engine.Compile
• Engine.Define
• Engine.EvalMultiple
• Engine.RegisterFunc
• Engine.RegisterPrimitive
• NewEngine
• NewEngine (WithExtension)

Variables

var EmptyList = wrapValue(values.EmptyList)

EmptyList is the empty list.

var ErrEngineClosed = values.NewStaticError("engine is closed")

ErrEngineClosed is returned when Close is called on an already-closed engine.

var False = wrapValue(values.FalseValue)

False is the #f value.

var True = wrapValue(values.TrueValue)

True is the #t value.

var Void = wrapValue(values.Void)

Void is the void value.

Functions

func IsBoolean

func IsBoolean(v Value) bool

IsBoolean returns true if v is a boolean.

func IsList

func IsList(v Value) bool

IsList returns true if v is a proper list (including the empty list).

func IsNull

func IsNull(v Value) bool

IsNull returns true if v is the empty list.

func IsNumber

func IsNumber(v Value) bool

IsNumber returns true if v is a number.

func IsPair

func IsPair(v Value) bool

IsPair returns true if v is a non-empty pair (cons cell). EmptyList is not a *Pair (it's a separate type), so the type assertion handles the distinction without an explicit IsEmptyList check.

func IsProcedure

func IsProcedure(v Value) bool

IsProcedure returns true if v is a callable procedure (lambda, case-lambda, or parameter).

func IsString

func IsString(v Value) bool

IsString returns true if v is a string.

func IsSymbol

func IsSymbol(v Value) bool

IsSymbol returns true if v is a symbol.

func ToGoBool

func ToGoBool(v Value) (bool, bool)

ToGoBool extracts a Go bool from a Scheme boolean value. Returns (false, false) if v is not a boolean.

func ToGoFloat

func ToGoFloat(v Value) (float64, bool)

ToGoFloat extracts a float64 from an inexact real value. Returns (0, false) if v is not a Float.

func ToGoInt

func ToGoInt(v Value) (int64, bool)

ToGoInt extracts an int64 from an exact integer value. Returns (0, false) if v is not an exact integer or does not fit in int64.

func ToGoString

func ToGoString(v Value) (string, bool)

ToGoString extracts the Go string from a Scheme string value. Returns ("", false) if v is not a string.

Types

type CompilationError

type CompilationError struct {
	Message string
	Cause   error
}

CompilationError wraps errors from parsing, expanding, or compiling Scheme code.

func (*CompilationError) Error

func (p *CompilationError) Error() string

func (*CompilationError) Unwrap

func (p *CompilationError) Unwrap() error

type CompiledCode

type CompiledCode struct {
	// contains filtered or unexported fields
}

CompiledCode represents compiled Scheme code ready for execution.

CompiledCode captures the environment from the Engine that compiled it and always executes using that captured environment, regardless of which Engine is used to run it. Using a different Engine instance affects only that Engine's own bookkeeping (for example, evaluation counters), not the environment bindings or symbol interning.

CompiledCode can be run multiple times. It is not safe for concurrent execution (the underlying Engine is not goroutine-safe).

func (*CompiledCode) String

func (p *CompiledCode) String() string

String returns a string representation of the compiled code.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is the main entry point for embedding Wile.

An Engine is NOT safe for concurrent use from multiple goroutines. The underlying environment's global bindings use a RWMutex (concurrent reads are safe), but Eval, Compile, and Run mutate the environment. Each goroutine should use its own Engine, or synchronize externally.

SRFI-18 threads within a single Engine are safe — the VM handles thread coordination internally.

func NewEngine

func NewEngine(ctx context.Context, opts ...EngineOption) (*Engine, error)

NewEngine creates a new Wile engine. By default, only core primitives are included. Use WithExtension to add optional extensions.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	result, err := engine.Eval(ctx, "(+ 1 2 3)")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

6

Example (WithExtension)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
	"github.com/aalpar/wile/internal/extensions/io"
)

func main() {
	_, err := wile.NewEngine(context.Background(),
		wile.WithExtension(io.Extension),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("engine created with I/O extension")
}

Output:

engine created with I/O extension

func (*Engine) Call

func (p *Engine) Call(ctx context.Context, proc Value, args ...Value) (Value, error)

Call invokes a Scheme procedure with arguments. Supports all callable types: lambdas, case-lambdas, and parameters. Composable continuations cannot be called from Go (they require the VM winding stack) and return an error.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Define a Scheme function.
	ctx := context.Background()
	_, err = engine.EvalMultiple(ctx, `
		(define (square x) (* x x))
	`)
	if err != nil {
		log.Fatal(err)
	}

	// Retrieve and call it from Go.
	proc, ok := engine.Get("square")
	if !ok {
		log.Fatal("square not found")
	}

	result, err := engine.Call(ctx, proc, wile.NewInteger(12))
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

144

func (*Engine) Close

func (p *Engine) Close() error

Close releases resources held by closeable extensions. Extensions that implement registry.Closeable have their Close method called. Errors from individual closers are collected and returned via errors.Join. Calling Close on an already-closed engine returns ErrEngineClosed.

func (*Engine) Compile

func (p *Engine) Compile(ctx context.Context, code string) (*CompiledCode, error)

Compile parses and compiles code without executing.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Define a variable, then compile an expression that uses it.
	ctx := context.Background()
	_, err = engine.Eval(ctx, "(define x 0)")
	if err != nil {
		log.Fatal(err)
	}

	compiled, err := engine.Compile(context.Background(), "(* x x)")
	if err != nil {
		log.Fatal(err)
	}

	// Run the same compiled code with different values of x.
	for _, n := range []int64{3, 5, 7} {
		err = engine.Define("x", wile.NewInteger(n))
		if err != nil {
			log.Fatal(err)
		}

		result, err := engine.Run(ctx, compiled)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Println(result.SchemeString())
	}
}

Output:

9
25
49

func (*Engine) CompileWithSource

func (p *Engine) CompileWithSource(ctx context.Context, code string, source string) (*CompiledCode, error)

CompileWithSource parses and compiles code without executing. The source parameter identifies where the code came from (e.g. a filename) and appears in error messages and stack traces.

func (*Engine) CurrentLoadDirectory

func (p *Engine) CurrentLoadDirectory() string

CurrentLoadDirectory returns the directory of the file currently being loaded, or empty string if no file is being loaded.

func (*Engine) CurrentLoadPath

func (p *Engine) CurrentLoadPath() string

CurrentLoadPath returns the absolute path of the file currently being loaded, or empty string if no file is being loaded.

func (*Engine) Define

func (p *Engine) Define(name string, value Value) error

Define binds a value to a name in the top-level environment.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	err = engine.Define("width", wile.NewInteger(800))
	if err != nil {
		log.Fatal(err)
	}

	err = engine.Define("height", wile.NewInteger(600))
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	result, err := engine.Eval(ctx, "(* width height)")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

480000

func (*Engine) Environment

func (p *Engine) Environment() *environment.EnvironmentFrame

Environment returns the underlying environment for advanced use.

func (*Engine) Eval

func (p *Engine) Eval(ctx context.Context, code string) (Value, error)

Eval parses, compiles, and executes Scheme code, returning the result.

func (*Engine) EvalMultiple

func (p *Engine) EvalMultiple(ctx context.Context, code string) (Value, error)

EvalMultiple evaluates multiple expressions, returning the last result.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	result, err := engine.EvalMultiple(ctx, `
		(define x 10)
		(define y 20)
		(+ x y)
	`)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

30

func (*Engine) EvalMultipleWithSource

func (p *Engine) EvalMultipleWithSource(ctx context.Context, code string, source string) (Value, error)

EvalMultipleWithSource evaluates multiple expressions, returning the last result. The source parameter identifies where the code came from (e.g. a filename) and appears in error messages and stack traces.

func (*Engine) EvalWithSource

func (p *Engine) EvalWithSource(ctx context.Context, code string, source string) (Value, error)

EvalWithSource parses, compiles, and executes Scheme code, returning the result. The source parameter identifies where the code came from (e.g. a filename) and appears in error messages and stack traces.

func (*Engine) Get

func (p *Engine) Get(name string) (Value, bool)

Get retrieves a value by name from the environment.

func (*Engine) LastCounters

func (p *Engine) LastCounters() machine.VMCounters

LastCounters returns the VM performance counters from the most recent Run or Eval call. Sub-context counters are not aggregated.

func (*Engine) PopLoadPath

func (p *Engine) PopLoadPath()

PopLoadPath removes the top path from the load path stack. Does nothing if the stack is empty.

Advanced embedders who need fine-grained control can use Push/Pop directly, but most should use WithLoadPath for automatic cleanup.

func (*Engine) PushLoadPath

func (p *Engine) PushLoadPath(absPath string) error

PushLoadPath pushes an absolute path onto the load path stack. Returns an error if absPath is not absolute.

Advanced embedders who need fine-grained control can use Push/Pop directly, but most should use WithLoadPath for automatic cleanup.

func (*Engine) RegisterFunc

func (p *Engine) RegisterFunc(name string, fn any) error

RegisterFunc registers a Go function as a Scheme primitive using natural Go signatures.

Reflection-based FFI bridging: pre-computes argument and return converters at registration time using Go's reflect package. Each call uses the cached converters to translate between Scheme values and Go types, avoiding per-call reflection overhead. See BIBLIOGRAPHY.md "Reflection-Based FFI Bridging".

Supported Types

Parameter types: int64, int, float64, string, bool, []byte, []T (typed slices), map[K]V, structs (exported fields), func(...) (callbacks), Value, and context.Context (first param only).

Return types: int64, int, float64, string, bool, []byte, []T, map[K]V, structs, Value, error (last return only), and void.

Variadic Functions

Variadic Go functions are supported. The variadic parameter receives all excess arguments from Scheme, converted element-by-element.

Context Forwarding

If the first parameter is context.Context, the VM's context is forwarded automatically and does not count toward the Scheme parameter count.

Callbacks

Callback parameters (func types) receive a Go closure that invokes a Scheme procedure through a VM sub-context. Callbacks must be called synchronously during the registered function's execution. Storing a callback for later invocation or calling it from another goroutine is unsafe — the closure captures VM state that is not goroutine-safe.

Returns a *Error if fn is not a function or uses unsupported types.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/aalpar/wile"
)

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Register a Go function with a natural signature — no MachineContext needed.
	err = engine.RegisterFunc("double", func(n int64) int64 {
		return n * 2
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	result, err := engine.Eval(ctx, "(map double '(1 2 3 4 5))")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

(2 4 6 8 10)

func (*Engine) RegisterFuncs

func (p *Engine) RegisterFuncs(funcs map[string]any) error

RegisterFuncs registers multiple Go functions as Scheme primitives. Each key in the map is the Scheme name; each value must be a Go function with a signature supported by [RegisterFunc].

Registration stops on the first error. The error message includes the binding name that failed first. When multiple functions are invalid, the particular binding that fails first is non-deterministic because Go map iteration order is unspecified. Functions registered before the failure remain registered.

func (*Engine) RegisterPrimitive

func (p *Engine) RegisterPrimitive(spec PrimitiveSpec) error

RegisterPrimitive adds a Go function as a Scheme primitive.

Example

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	engine, err := wile.NewEngine(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Register a Go function that doubles an integer.
	err = engine.RegisterPrimitive(wile.PrimitiveSpec{
		Name:       "double",
		ParamCount: 1,
		Impl: func(_ context.Context, mc *wile.MachineContext) error {
			n := mc.Arg(0).(*values.Integer).Value
			mc.SetValue(values.NewInteger(n * 2))
			return nil
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	result, err := engine.Eval(ctx, "(double 21)")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.SchemeString())
}

Output:

42

func (*Engine) Run

func (p *Engine) Run(ctx context.Context, cc *CompiledCode) (Value, error)

Run executes previously compiled code.

func (*Engine) TopLevelEnvironment

func (p *Engine) TopLevelEnvironment() *environment.TopLevelEnvironment

TopLevelEnvironment returns the TopLevelEnvironment for advanced use. This provides access to per-instance symbol interning and phase management.

func (*Engine) WithLoadPath

func (p *Engine) WithLoadPath(absPath string, fn func() error) error

WithLoadPath executes fn with absPath pushed onto the load path stack. This is the recommended API for embedders - it guarantees balanced push/pop via defer even if fn panics or returns an error.

Returns an error if absPath is not an absolute path.

Example:

err := engine.WithLoadPath("/app/scripts/main.scm", func() error {
    _, err := engine.Eval(ctx, "(load \"helper.scm\")") // resolves relative to /app/scripts/
    return err
})

type EngineOption

type EngineOption func(*engineConfig)

EngineOption configures an Engine.

func WithExtension

func WithExtension(ext registry.Extension) EngineOption

WithExtension adds an extension to the engine.

func WithExtensions

func WithExtensions(exts ...registry.Extension) EngineOption

WithExtensions adds multiple extensions to the engine.

func WithLibraryPaths

func WithLibraryPaths(paths ...string) EngineOption

WithLibraryPaths enables the R7RS library system (define-library / import) and configures directories to search for .sld library files.

Without this option, (import ...) raises a configuration error.

Paths are searched in order: user-supplied paths first, then the defaults ("." and "./lib"). An empty call WithLibraryPaths() enables library support with defaults only.

Example:

eng, err := wile.NewEngine(ctx,
    wile.WithLibraryPaths("/app/libs", "./vendor"),
)
// search order: /app/libs, ./vendor, ., ./lib

func WithMaxCallDepth

func WithMaxCallDepth(n uint64) EngineOption

WithMaxCallDepth sets the maximum recursion depth for the VM. When the continuation stack exceeds this depth, ErrCallDepthExceeded is returned. A value of 0 means unlimited (the default).

func WithRegistry

func WithRegistry(r *registry.Registry) EngineOption

WithRegistry uses a custom registry instead of the default. When set, core primitives are NOT automatically added.

type Error

type Error struct {
	Message string
	Cause   error
}

Error represents a Wile engine error, including initialization failures.

func (*Error) Error

func (p *Error) Error() string

func (*Error) Unwrap

func (p *Error) Unwrap() error

type ForeignFunction

type ForeignFunction = machine.ForeignFunction

ForeignFunction is the signature for primitive implementations. This is a re-export of machine.ForeignFunction for convenience.

type MachineContext

type MachineContext = machine.MachineContext

MachineContext provides access to the VM during primitive execution. This is a re-export of machine.MachineContext for convenience.

type PrimitiveSpec

type PrimitiveSpec = registry.PrimitiveSpec

PrimitiveSpec defines a primitive to be registered. This is a re-export of registry.PrimitiveSpec for convenience.

type RuntimeError

type RuntimeError struct {
	Message    string
	Cause      error
	Condition  Value  // non-nil when Scheme raise produced the error; nil for VM/primitive errors
	Source     string // formatted source location ("file:line:col"), empty if unavailable
	StackTrace string // formatted VM stack trace, empty if unavailable
}

RuntimeError wraps errors from executing Scheme code.

Condition

When the error originated from a Scheme raise or raise-continuable, Condition holds the raised value and RuntimeError.IsSchemeException returns true. When the error originated from Go code (VM errors, primitive failures, type mismatches), Condition is nil.

Source and Stack Trace

Source and StackTrace provide the source location and VM stack trace at the point of the error. Both are empty strings when per-operation source tracking is unavailable.

Cause

Cause may contain internal machine types. Callers should treat it as an opaque error suitable for logging and errors.Is/errors.As matching, not for direct type inspection.

func (*RuntimeError) Error

func (p *RuntimeError) Error() string

func (*RuntimeError) IsSchemeException

func (p *RuntimeError) IsSchemeException() bool

IsSchemeException reports whether this error originated from a Scheme raise or raise-continuable expression. When true, Condition holds the raised value.

func (*RuntimeError) Unwrap

func (p *RuntimeError) Unwrap() error

type Value

type Value interface {
	// SchemeString returns the Scheme representation.
	SchemeString() string
	// IsVoid returns true if this is the void value.
	IsVoid() bool
	// Internal returns the underlying values.Value for advanced use.
	// This is exported for use by testing packages and advanced embedding scenarios.
	Internal() values.Value
	// contains filtered or unexported methods
}

Value represents a Scheme value in the public API.

func Car

func Car(v Value) (Value, bool)

Car returns the car of a pair or other Tuple type. Returns (value, true) on success, or (nil, false) if v is not a non-empty Tuple.

func Cdr

func Cdr(v Value) (Value, bool)

Cdr returns the cdr of a pair or other Tuple type. Returns (value, true) on success, or (nil, false) if v is not a non-empty Tuple.

func NewBigFloat

func NewBigFloat(f *big.Float) Value

NewBigFloat creates a big float value from a big.Float.

func NewBigFloatFromFloat64

func NewBigFloatFromFloat64(f float64) Value

NewBigFloatFromFloat64 creates a big float value from a float64.

func NewBigFloatFromString

func NewBigFloatFromString(s string) Value

NewBigFloatFromString creates a big float from a string. Returns nil if the string is not a valid float.

func NewBigInteger

func NewBigInteger(n *big.Int) Value

NewBigInteger creates a big integer value from a big.Int.

func NewBigIntegerFromInt64

func NewBigIntegerFromInt64(n int64) Value

NewBigIntegerFromInt64 creates a big integer value from an int64.

func NewBigIntegerFromString

func NewBigIntegerFromString(s string, base int) Value

NewBigIntegerFromString creates a big integer from a string in the given base. Returns nil if the string is not a valid integer.

func NewBoolean

func NewBoolean(b bool) Value

NewBoolean creates a Scheme boolean.

func NewComplex

func NewComplex(v complex128) Value

NewComplex creates a Scheme complex number from a Go complex128.

func NewComplexFromParts

func NewComplexFromParts(realPart, imagPart float64) Value

NewComplexFromParts creates a Scheme complex number from real and imaginary parts.

func NewFloat

func NewFloat(f float64) Value

NewFloat creates a Scheme inexact real.

func NewInteger

func NewInteger(n int64) Value

NewInteger creates a Scheme integer.

func NewList

func NewList(vals ...Value) Value

NewList creates a Scheme list from values.

func NewRational

func NewRational(num, denom int64) Value

NewRational creates a Scheme exact rational number.

func NewRationalFromBigInt

func NewRationalFromBigInt(num, denom *big.Int) Value

NewRationalFromBigInt creates a Scheme exact rational from big.Int numerator and denominator.

func NewString

func NewString(s string) Value

NewString creates a Scheme string.

func NewSymbol

func NewSymbol(s string) Value

NewSymbol creates a Scheme symbol.

func NewVector

func NewVector(vals ...Value) Value

NewVector creates a Scheme vector from values.

func ToSlice

func ToSlice(ctx context.Context, v Value) ([]Value, bool)

ToSlice converts a proper list to a Go slice. Returns (slice, true) on success, or (nil, false) if v is not a proper list.