wile

module
v1.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 17, 2026 License: Apache-2.0

README

Wile

CI Go Reference

Wile is an R7RS-small Scheme interpreter written in pure Go. It is built to be embedded: go get adds it to a Go project, and there is no CGo, no C toolchain, and no cross-compilation friction. Scheme values are ordinary Go heap objects collected by the Go garbage collector.

Wile targets a specific use case — adding a Lisp scripting layer to a Go application where the workload benefits from Lisp semantics. That includes configuration DSLs, policy evaluation, symbolic computation, and any application where hygienic macros, exact arithmetic, or first-class continuations are the right tool. It is not a replacement for Lua or JavaScript on performance-bound scripting workloads.

The interpreter implements the R7RS-small language: hygienic macros via Flatt's sets-of-scopes model, proper tail calls, first-class continuations, the full numeric tower (exact integers, rationals, IEEE floats, arbitrary precision, complex), and SRFI-18 threads. It can also be used as a standalone interpreter via the wile command.

Installation

Wile requires Go 1.24 or later.

As a library
go get github.com/aalpar/wile@latest

Then import and use the public API; see docs/embedding/api-design.md for the full embedding guide.

As a standalone interpreter

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

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

The binary is written to ./dist/{os}/{arch}/wile.

Running

wile                                  # Start the REPL
wile program.scm                      # Run a file and exit
wile -f program.scm -i                # Run a file, then enter the REPL
wile -e '(+ 1 2)'                     # Evaluate an expression
wile -L /path/to/libs program.scm     # Add a library search path
wile --version                        # Print the version

SCHEME_LIBRARY_PATH (colon-separated) supplies additional library search paths. The REPL supports readline-style editing, multi-line expressions, and a built-in debugger:

> (define (fib n)
    (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
> (fib 10)
55
> ,doc map
> ,break program.scm:42
> ,continue

Meta commands begin with ,. Use ,help for the full list, or see docs/reference/cli-and-repl.md for the complete CLI flag set, meta commands, and debugger commands.

Embedding

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

engine, _ := wile.NewEngine(ctx)
engine.Define("width", wile.NewInteger(800))
result, _ := engine.Eval(ctx, engine.MustParse(ctx, "(* width 600)"))
fmt.Println(result.SchemeString())   // 480000

The full embedding API — value constructors, engine options, primitive registration, profiles, sandboxing — is documented in docs/embedding/api-design.md and at pkg.go.dev/github.com/aalpar/wile/pkg/wile. Worked examples live in examples/embedding/.

Documentation

Topic Document
Scheme language reference docs/reference/scheme.md
CLI flags, REPL, debugger docs/reference/cli-and-repl.md
Differences from R7RS docs/reference/r7rs-differences.md
Embedding API docs/embedding/api-design.md
Embedded and virtual source loading docs/embedding/source-loading.md
Extension system docs/extensions/architecture.md
R7RS library integration docs/extensions/libraries.md
Macro system and hygiene docs/compiler/macro-system.md
Continuations docs/continuations/concepts.md, delimited.md
Numeric tower docs/numeric/tower.md
Sandboxing and authorization docs/security/sandboxing.md
Algebra library docs/algebra/overview.md
All documentation docs/INDEX.md, docs/TOC.md
Primitives reference PRIMITIVES.md
Academic references BIBLIOGRAPHY.md
Release history CHANGELOG.md

Self-contained examples — basics, macros, numeric tower, concurrency, control flow, logic programming, and embedding — live in examples/. Go static analysis extensions (AST, SSA, CFG, call graph, lint) have been extracted to wile-goast.

References

Contributing

Contributions are welcome. Useful areas:

  • Documentation, examples, tutorials
  • R7RS-small completeness and SRFI implementations
  • Test coverage
  • Targeted performance work and allocation reduction
  • REPL, debugger, and tooling improvements

Browse issues labeled good-first-issue or help wanted. See CONTRIBUTING.md for the workflow.

License

Apache License 2.0 — see LICENSE.

Directories

Path Synopsis
algebra
graph
Package graph provides Go-side fast paths for graph algorithms used by the (wile algebra graph) Scheme library.
 Package graph provides Go-side fast paths for graph algorithms used by the (wile algebra graph) Scheme library.
cmd
singlelinefunclint command
Command singlelinefunclint enforces the project's no-single-line-function rule (CODING_STYLE.md: "Never write single-line functions.
 Command singlelinefunclint enforces the project's no-single-line-function rule (CODING_STYLE.md: "Never write single-line functions.
typeswitchlint command
Command typeswitchlint checks that type switches over values.Value are exhaustive — but only the ones that opt in with an //exhaustive marker.
 Command typeswitchlint checks that type switches over values.Value are exhaustive — but only the ones that opt in with an //exhaustive marker.
wile command
Package main provides the entry point for the Wile Scheme interpreter binary.
 Package main provides the entry point for the Wile Scheme interpreter binary.
Package coverage collects per-s-expression coverage data from executing Wile Scheme code.
 Package coverage collects per-s-expression coverage data from executing Wile Scheme code.
Package docparse parses structured metadata from Guile-style docstrings.
 Package docparse parses structured metadata from Guile-style docstrings.
Package environment provides variable binding and scoping for the Scheme compiler.
 Package environment provides variable binding and scoping for the Scheme compiler.
examples
embedding command
basic demonstrates embedding the Wile Scheme interpreter in a Go program.
 basic demonstrates embedding the Wile Scheme interpreter in a Go program.
embedding/source-tracking command
source-tracking demonstrates the ParseWithSource/MustParseWithSource API for embedding Wile with per-operation source location tracking.
 source-tracking demonstrates the ParseWithSource/MustParseWithSource API for embedding Wile with per-operation source location tracking.
embedding/stack-trace command
stack-trace demonstrates the VM stack trace captured when a runtime error escapes to the embedder, with emphasis on the sub-context spanning added in CaptureStackTrace (the "<foreign-call boundary>" frame).
 stack-trace demonstrates the VM stack trace captured when a runtime error escapes to the embedder, with emphasis on the sub-context spanning added in CaptureStackTrace (the "<foreign-call boundary>" frame).
extensions
algebragraph
Package algebragraph exposes the Go-side graph kernels in algebra/graph as Scheme primitives.
 Package algebragraph exposes the Go-side graph kernels in algebra/graph as Scheme primitives.
charsets
Package charsets implements the SRFI-14 Character-Set Library FFI surface.
 Package charsets implements the SRFI-14 Character-Set Library FFI surface.
eval
Package eval provides evaluation and environment primitives.
 Package eval provides evaluation and environment primitives.
files
Package files provides file I/O primitives.
 Package files provides file I/O primitives.
gointerop
Package gointerop provides Go concurrency primitive wrappers.
 Package gointerop provides Go concurrency primitive wrappers.
introspection
Package introspection provides read-only environment introspection primitives.
 Package introspection provides read-only environment introspection primitives.
math
Package math provides transcendental and advanced mathematical primitives.
 Package math provides transcendental and advanced mathematical primitives.
process
Package process provides subprocess execution primitives.
 Package process provides subprocess execution primitives.
sat
Package sat ships a CDCL SAT solver as a Wile extension.
 Package sat ships a CDCL SAT solver as a Wile extension.
system
Package system provides system interface primitives.
 Package system provides system interface primitives.
threads
Package threads provides SRFI-18 multithreading primitives.
 Package threads provides SRFI-18 multithreading primitives.
internal
bootstrap
Package runtime provides the runtime environment initialization for the Scheme interpreter.
 Package runtime provides the runtime environment initialization for the Scheme interpreter.
extensions/all
Package all provides additional primitives for records, promises, and extended string/character operations.
 Package all provides additional primitives for records, promises, and extended string/character operations.
extensions/envvars
Package envvars provides environment variable access primitives.
 Package envvars provides environment variable access primitives.
extensions/io
Package io provides I/O primitives for reading and writing.
 Package io provides I/O primitives for reading and writing.
extensions/iotest
Package iotest provides fault-injecting I/O ports for testing the classification of read errors per R7RS §6.11.
 Package iotest provides fault-injecting I/O ports for testing the classification of read errors per R7RS §6.11.
extensions/namespace
Package namespace provides namespace manipulation primitives.
 Package namespace provides namespace manipulation primitives.
forms
Package forms provides a shared registry for special form validators.
 Package forms provides a shared registry for special form validators.
match
Package match implements the pattern matching engine for syntax-rules and syntax-case.
 Package match implements the pattern matching engine for syntax-rules and syntax-case.
parser
Package parser implements R7RS Scheme syntax parsing.
 Package parser implements R7RS Scheme syntax parsing.
schemeutil
Package schemeutil provides conversion utilities between syntax, datum, and Go types.
 Package schemeutil provides conversion utilities between syntax, datum, and Go types.
syntax
Package syntax implements Scheme syntax representation with hygiene support.
 Package syntax implements Scheme syntax representation with hygiene support.
syntax/syntaxtest
Package syntaxtest provides test helpers for the syntax package.
 Package syntaxtest provides test helpers for the syntax package.
testutil
tokenizer
Package tokenizer implements R7RS Scheme lexical analysis.
 Package tokenizer implements R7RS Scheme lexical analysis.
validate
Package validate validates Scheme syntax and produces typed expressions.
 Package validate validates Scheme syntax and produces typed expressions.
ADDING A NEW PROMOTED OP
 ADDING A NEW PROMOTED OP
compilation
compilation/resolver
Package resolver provides file resolution infrastructure for the Scheme compiler.
 Package resolver provides file resolution infrastructure for the Scheme compiler.
compilation/sourceload
Package sourceload provides file-finding and load-stack tracking for locating source files across virtual filesystems.
 Package sourceload provides file-finding and load-stack tracking for locating source files across virtual filesystems.
pkg
wile
Package wile provides the public API for embedding the Wile Scheme interpreter.
 Package wile provides the public API for embedding the Wile Scheme interpreter.
Package registry provides a plugin architecture for registering Scheme primitives.
 Package registry provides a plugin architecture for registering Scheme primitives.
core
Package core provides the essential primitives required for Scheme to function.
 Package core provides the essential primitives required for Scheme to function.
helpers
Package helpers provides shared utility functions for primitive implementations.
 Package helpers provides shared utility functions for primitive implementations.
testhelpers
Package testhelpers provides shared test infrastructure for Scheme primitive tests.
 Package testhelpers provides shared test infrastructure for Scheme primitive tests.
Package repl provides composable components for building interactive Scheme REPLs on top of the Wile engine.
 Package repl provides composable components for building interactive Scheme REPLs on top of the Wile engine.
Package gorules defines custom lint rules for the Wile project.
 Package gorules defines custom lint rules for the Wile project.
Package security provides fine-grained authorization for Scheme runtime operations.
 Package security provides fine-grained authorization for Scheme runtime operations.
Package stdlib provides the embedded R7RS standard library files.
 Package stdlib provides the embedded R7RS standard library files.
Package values implements all Scheme runtime value types.
 Package values implements all Scheme runtime value types.
valuestest
Package valuestest provides test helpers for the values package.
 Package valuestest provides test helpers for the values package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.