wile

module
v1.20.0 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 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. For a build free of known stdlib vulnerabilities, use Go 1.26.4 or later (Go 1.26.3 and earlier carry reachable stdlib CVEs); see SECURITY.md.

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 --check program.scm              # Compile without running; report errors
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/.

Asking for a cut

Wile is a full R7RS-small implementation, and its breadth can be more than an embedder wants. The extension system is built for trimming: profiles (WithProfile) and WithExtension opt into only the primitives you need, and per-engine registries keep one engine's cut from affecting another. If your application only wants, say, a configuration DSL or a policy evaluator, you can run a much smaller surface than the default.

Reducing the linked binary size is a further step — it means splitting Wile into separate modules so a build can exclude what it does not import. That work is deferred until someone needs it, because the right split depends on the cut being asked for. If binary size is blocking you from embedding Wile, open an issue describing the cut you want and it can be scoped against your case.

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
cmd
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.
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
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.
algebragraph
Package algebragraph exposes the Go-side graph kernels in extensions/algebra/graph as Scheme primitives.
 Package algebragraph exposes the Go-side graph kernels in extensions/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.
pkg
debug
Package debug is the embedder-facing debugger: breakpoints, stepping, and the break-prompt command surface a REPL renders.
 Package debug is the embedder-facing debugger: breakpoints, stepping, and the break-prompt command surface a REPL renders.
docparse
Package docparse parses structured metadata from Guile-style docstrings.
 Package docparse parses structured metadata from Guile-style docstrings.
environment
Package environment provides variable binding and scoping for the Scheme compiler.
 Package environment provides variable binding and scoping for the Scheme compiler.
extensions/io
Package io provides I/O primitives for reading and writing.
 Package io provides I/O primitives for reading and writing.
internal/bootstrap
Package bootstrap initializes the top-level Scheme environment.
 Package bootstrap initializes the top-level Scheme environment.
internal/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.
internal/extensions/envvars
Package envvars provides environment variable access primitives.
 Package envvars provides environment variable access primitives.
internal/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.
internal/extensions/namespace
Package namespace provides namespace manipulation primitives.
 Package namespace provides namespace manipulation primitives.
internal/forms
Package forms provides a shared registry for special form validators.
 Package forms provides a shared registry for special form validators.
internal/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.
internal/tokenizer
Package tokenizer implements R7RS Scheme lexical analysis.
 Package tokenizer implements R7RS Scheme lexical analysis.
internal/validate
Package validate validates Scheme syntax and produces typed expressions.
 Package validate validates Scheme syntax and produces typed expressions.
machine
Package machine implements the Scheme virtual machine, compiler, and macro expander.
 Package machine implements the Scheme virtual machine, compiler, and macro expander.
machine/compilation
machine/compilation/resolver
Package resolver provides file resolution infrastructure for the Scheme compiler.
 Package resolver provides file resolution infrastructure for the Scheme compiler.
machine/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.
parser
Package parser implements R7RS Scheme syntax parsing.
 Package parser implements R7RS Scheme syntax parsing.
registry
Package registry provides a plugin architecture for registering Scheme primitives.
 Package registry provides a plugin architecture for registering Scheme primitives.
registry/core
Package core provides the essential primitives required for Scheme to function.
 Package core provides the essential primitives required for Scheme to function.
registry/helpers
Package helpers provides shared utility functions for primitive implementations.
 Package helpers provides shared utility functions for primitive implementations.
registry/testhelpers
Package testhelpers provides shared test infrastructure for Scheme primitive tests.
 Package testhelpers provides shared test infrastructure for Scheme primitive tests.
repl
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.
schemeutil
Package schemeutil provides conversion utilities between syntax, datum, and Go types.
 Package schemeutil provides conversion utilities between syntax, datum, and Go types.
security
Package security provides fine-grained authorization for Scheme runtime operations.
 Package security provides fine-grained authorization for Scheme runtime operations.
stdlib
Package stdlib provides the embedded R7RS standard library files.
 Package stdlib provides the embedded R7RS standard library files.
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
values
Package values implements all Scheme runtime value types.
 Package values implements all Scheme runtime value types.
values/valuestest
Package valuestest provides test helpers for the values package.
 Package valuestest provides test helpers for the values package.
werr
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.
tools
cmd/cxmeasure command
Command cxmeasure reports cyclomatic and cognitive complexity per function, file, and package, so that refactoring is aimed at measured density rather than at whichever file someone happened to be reading.
 Command cxmeasure reports cyclomatic and cognitive complexity per function, file, and package, so that refactoring is aimed at measured density rather than at whichever file someone happened to be reading.
cmd/nestinglint command
Command nestinglint enforces the project's shallow-nesting rule (CODING_STYLE.md: "Keep Indentation Shallow" / "avoids 'arrow code,' where indentation grows with each condition checked").
 Command nestinglint enforces the project's shallow-nesting rule (CODING_STYLE.md: "Keep Indentation Shallow" / "avoids 'arrow code,' where indentation grows with each condition checked").
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.
cmd/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.
ruleguard
Package gorules defines custom lint rules for the Wile project.
 Package gorules defines custom lint rules for the Wile project.

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.