wile

func NewDebugger ¶

func NewDebugger() *Debugger

NewDebugger creates a new Debugger.

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.

When WithNamespace is used, the engine uses the pre-built namespace and ignores registry/extension/core options (they were applied when the namespace was created). Library paths and other engine-specific options still apply. See WithNamespace for the full list of options this path silently ignores, several of them security-relevant.

Initialization Order Invariant ¶

NewEngine performs 6 initialization steps that MUST execute in this order. Each step depends on prior steps; reordering causes silent failures or panics.

1. Config — build engineConfig from options
2. Registry — buildRegistry(cfg): register core + extension primitives
3. Namespace — NewNamespace() + SetRegistry + SetAuthorizer
4. Bootstrap — applyBaseEnvironment: bind primitives, syntax compilers, expanders, bootstrap macros (uses EmbedFileResolver, NOT the runtime file resolver)
5. File resolver — env.SetFileResolver: runtime include/load resolver. Must come AFTER bootstrap (step 4) so bootstrap uses its own EmbedFileResolver, not the runtime resolver.
6. Library system — setupLibrarySystem: search paths, extension libraries, library env factory. Requires file resolver (step 5) and bootstrap macros (step 4) for define-library parsing.

The WithNamespace path (pre-built namespace) skips steps 2-4 and trusts that the caller bootstrapped correctly. Step 5 still runs on that path, but only if the supplied namespace has no file resolver of its own; step 6 runs unconditionally. NewNamespace() performs steps 2-4.

package main

import (
	"context"
	"fmt"
	"log"

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

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

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

	fmt.Println(result.SchemeString())
}

Output:
6

package main

import (
	"context"
	"fmt"
	"log"

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

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 WithAuthorizer ¶

func WithAuthorizer(auth security.Authorizer) EngineOption

WithAuthorizer sets the Authorizer for the engine. The authorizer is recorded on the engine's namespace at construction and consulted by gate sites via MachineContext.Authorizer(), gating runtime primitives and compile-time code loading.

An explicit WithAuthorizer takes precedence over any profile's built-in authorizer regardless of option order: WithAuthorizer(a) and WithProfile(p) resolve to a (then intersected with any WithSandbox layer) no matter which is written first. Passing nil is meaningful — it opens the engine, overriding a profile authorizer (symmetric with WithEnvMap(nil)).

Without this option, all operations are allowed (open by default) unless a profile or sandbox supplies an authorizer. The authorizer is immutable after engine construction.

Example:

eng, err := wile.NewEngine(ctx,
    wile.WithAuthorizer(security.ReadOnly()),
)

func WithContractEnforcement ¶

func WithContractEnforcement() EngineOption

WithContractEnforcement enables runtime type validation for primitives that declare ParamTypes contracts. When enabled, each contracted primitive validates its arguments against declared types before calling the implementation and returns a typed error on mismatch.

Disabled by default. Intended as a correctness-verification aid for extension authors — production extensions should perform their own argument checks (e.g., via helpers.RequireArg) rather than depend on this option, since enabling it adds a per-call validator invocation.

func WithCoverage ¶

func WithCoverage(c *coverage.Collector) EngineOption

WithCoverage enables Scheme-side line coverage collection. After each compilation, the engine registers the resulting top-level template and every sub-template reachable via its literals pool with the given collector. Per-s-expression execution is then aggregated into the collector's Entries.

Zero hot-path cost when not set (nil check in VM dispatch).

func WithDialect ¶ added in v1.18.0

func WithDialect(d Dialect) EngineOption

WithDialect installs a Dialect on the engine, customizing its special-form surface at construction time. Last-wins if supplied more than once. A nil dialect (the default) applies DefaultDialect, leaving the R7RS-default forms in place. If the dialect's InstallForms returns an error, NewEngine fails with that error wrapped in werr.ErrEngineInit.

func WithEnv ¶

func WithEnv(key, value string) EngineOption

WithEnv adds a single virtual environment variable. When any virtual env var is set, the envvars extension reads from the virtual map instead of os.Getenv.

func WithEnvMap ¶

func WithEnvMap(m map[string]string) EngineOption

WithEnvMap sets the complete virtual environment variable map. Replaces any previously set virtual env vars.

Passing nil clears the virtual env map so envvars primitives fall back to os.Getenv (still gated by the authorizer). This is symmetric with WithAuthorizer(nil): the zero value means "no restriction", not "empty sandbox". To explicitly sandbox with no visible env, pass an empty map.

Note: when combined with WithProfile(Console) or WithProfile(ConsoleWithLoad), option order matters. WithProfile fills in an empty map only if envMap is currently nil; a later WithEnvMap(nil) re-nils it and opens the sandbox.

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 WithImmutableTopLevel ¶

func WithImmutableTopLevel() EngineOption

WithImmutableTopLevel selects top-level-define immutability in the user program. A top-level define that is defined-once and never set! within its compilation unit is marked rebind-stable (BindingMeta.Stable), and a subsequent set! of such a binding is rejected with ErrImmutableBinding. This is now the DEFAULT (newEngineConfig); the option remains as an explicit, redundant selector for source compatibility.

This is a documented deviation from strict R7RS §4.1.6/§5.3 (which permit top-level set!/redefinition); it unlocks the frame-reclamation optimizer's top-level payoff (sibling escape-gated plan) — the "compile for speed" contract used by sealed-module Schemes. Use WithMutableTopLevel() to opt out.

Enforcement is scoped to the engine's own user runtime global (the layered-environment sealed-base carve): a re-define of a sealed primitive/stdlib name is a child-frame shadow rather than a rejected rebind, and user-loaded LIBRARIES stay mutable — a library's cross-form (define x)/(set! x) is permitted. See docs/reference/r7rs-differences.md.

func WithImportObserver ¶

func WithImportObserver(obs func(LibraryImportEvent)) EngineOption

WithImportObserver sets a callback that is invoked each time a library is imported. The observer is read-only — it cannot influence the import. Requires WithLibraryPaths to be effective (no libraries loaded without it).

func WithInlineThreshold ¶

func WithInlineThreshold(n int) EngineOption

WithInlineThreshold sets the maximum body length (in top-level expressions) for procedure inlining. Procedures with bodies longer than this threshold are not inlined. A value of 0 disables inlining entirely. When not called, the engine uses compilation.DefaultInlineThreshold (5).

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 default ("."). The embedded standard library is served by the FileResolver chain (e.g. WithSourceFS(stdlib.FS)), not a search path. An empty call WithLibraryPaths() enables library support with the default only.

Example:

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

func WithLossyConversionsAllowed ¶

func WithLossyConversionsAllowed() EngineOption

WithLossyConversionsAllowed permits FFI converters to silently truncate when converting Scheme numerics to fixed-precision Go types (float64, complex128). When set, *BigFloat with magnitude exceeding float64 range converts to ±math.Inf(0) without error; *Rational with non-representable denominators rounds via (*big.Rat).Float64 with the loss bit discarded; *BigComplex imaginary/real components each may truncate independently.

Default (option not set): the FFI converter returns werr.ErrLossyConversion (wrapped, with direction info) when any precision loss would occur. This is the "fail loud" discipline — opt-in is required to suppress.

The option is per-engine; the flag is captured into each FFI closure at RegisterFunc time, so calling WithLossyConversionsAllowed after some functions have already registered does NOT change their behavior.

func WithMaxCallDepth ¶

func WithMaxCallDepth(n int) 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 (no depth check). Negative values are clamped to 0 and therefore also mean unlimited (matches WithInlineThreshold). When not called, the engine uses DefaultMaxCallDepth (10000).

func WithMaxExpandDepth ¶

func WithMaxExpandDepth(n int) EngineOption

WithMaxExpandDepth sets the maximum structural recursion depth the macro expander will accept. The parser already bounds nesting in textual input (see WithMaxParseDepth); this bounds programmatically-constructed deep syntax — macro output, datum->syntax, and quasiquote — which reaches the expander without passing through the parser. When expansion nests deeper, ErrExpandDepthExceeded is returned instead of crashing with a fatal Go stack overflow. A value of 0 means unlimited (negative values are clamped to 0). When not called, the expander uses DefaultMaxExpandDepth (50000).

Scope: this bound applies to expansion of top-level program text run through the engine. Expansion triggered from within running Scheme — (eval ...), (load ...), (compile ...), (expand ...) — always uses DefaultMaxExpandDepth regardless of this option, because the primitive layer has no channel to the engine's configured value. Those paths are still protected from the fatal stack overflow (by the default); they are simply not retunable per-engine.

func WithMaxParseDepth ¶

func WithMaxParseDepth(n int) EngineOption

WithMaxParseDepth sets the maximum structural nesting depth the parser will accept. When input nests deeper, ErrParseDepthExceeded is returned instead of crashing with a fatal Go stack overflow. A value of 0 means unlimited (negative values are clamped to 0). When not called, the parser uses DefaultMaxParseDepth (10000).

Scope: this bound is threaded onto the engine's own parse entry points — Parse, ParseWithSource, ReadExpression, ReadExpressions, EvalMultiple, EvalProgram, and file/-e execution. Parsing triggered from within running Scheme — (read ...), (read-syntax ...), (eval ...), (compile ...) — uses DefaultMaxParseDepth regardless of this option, because the primitive layer has no channel to the engine's configured value (mirrors WithMaxExpandDepth). Those paths are still protected from the fatal stack overflow by the default; they are simply not retunable per-engine.

func WithMaxStackSize ¶

func WithMaxStackSize(n uint64) EngineOption

WithMaxStackSize sets the maximum eval stack size for the VM. When the eval stack exceeds this size, ErrStackOverflow is returned. This is opt-in: a value of 0 means unlimited (no stack size check). There is no default — when not called, the stack is unlimited.

func WithMutableTopLevel ¶

func WithMutableTopLevel() EngineOption

WithMutableTopLevel selects strict R7RS mutable/redefinable top-level bindings, the inverse of WithImmutableTopLevel. It exists as an explicit opt-out so callers can request mutable semantics independent of the engine default (which Phase 4 of the layered-environment work flips to immutable). Opting out forfeits the frame-reclaim GC win for user recursion.

func WithNamespace ¶

func WithNamespace(ns *environment.Namespace) EngineOption

WithNamespace uses a pre-built namespace instead of building one from extension options. When set, registry/extension/core options are ignored by NewEngine (they were already applied when the namespace was created).

This enables sharing a namespace across engines or pre-configuring namespaces with specific capabilities.

Every option consumed by namespace construction is silently ignored on this path, because NewEngine skips the bootstrap step that would apply them: WithAuthorizer, WithSandbox, a profile's built-in authorizer, WithEnv, WithEnvMap, and WithImmutableTopLevel/WithMutableTopLevel. The omission is security-relevant: WithNamespace(ns) combined with WithSandbox() yields no sandbox and no error. Apply those options to NewNamespace, which runs the bootstrap step, and pass its result here. (WithDialect is the one such option NewEngine rejects outright instead of dropping.)

func WithProfile ¶

func WithProfile(p Profile) EngineOption

WithProfile configures the engine with the named profile's extensions and authorization constraints. WithProfile is additive: it appends the profile's extensions to any already configured via WithExtension/WithExtensions, and records the profile's authorizer only if one is defined. An explicit WithAuthorizer always takes precedence over the profile's authorizer regardless of option order (see resolveAuthorizer), so profile and authorizer options compose commutatively.

Across multiple WithProfile calls the last profile that defines an authorizer wins; a later profile with no authorizer (e.g. Tiny, Small, KitchenSink) does not clear an earlier one. This fails safe — a prior restriction is retained rather than silently dropped.

Per-profile envMap behavior (all five current profiles):

• Tiny: envMap untouched; profile registers no extensions, so envvars primitives are absent.
• Console: allocates empty envMap when unset; sandboxes to the virtual map (no os.Getenv fallthrough).
• ConsoleWithLoad: same as Console (empty envMap when unset).
• Small: envMap untouched. envvars primitives are registered and fall through to os.Getenv when envMap is nil, gated by the authorizer (if any).
• KitchenSink: same fallthrough behavior as Small.

When WithEnv/WithEnvMap is combined with WithProfile(Console*), the caller-supplied contents are preserved: WithProfile only allocates an empty map when none is set. Option order matters — a later WithEnvMap(nil) re-nils the map and opens the sandbox.

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.

func WithSandbox ¶

func WithSandbox(opts ...SandboxOption) EngineOption

WithSandbox layers a restrictive authorizer on top of any profile. File reads and stats are allowed; file writes and deletes are denied. Environment variable reads are prefix-filtered (default "WILE_"). Code loading and process execution are denied.

The sandbox layer is always intersected (most-restrictive-wins, via security.All) on top of whatever base authorizer the profile and/or WithAuthorizer resolve to. This holds regardless of option order — the composition is performed once at engine construction by resolveAuthorizer, so WithSandbox may appear before or after WithProfile/WithAuthorizer.

Multiple WithSandbox calls accumulate: each layer is intersected with the previously recorded sandbox authorizer, so restrictions only ever tighten (a second call cannot silently widen the first). Intersection is order- independent for the allow/deny decision.

func WithSourceFS ¶

func WithSourceFS(fsys fs.FS) EngineOption

WithSourceFS adds a virtual filesystem layer to the source file resolver chain. Multiple calls add layers searched in call order. When no resolver options are used, the engine defaults to the OS filesystem. Once any resolver option is used (WithSourceFS or WithSourceOS), only the explicitly configured resolvers are active.

Bootstrap macros are unaffected — they always load from the embedded bootstrap filesystem.

WithSourceFS panics if fsys is nil: a nil filesystem is a programming error, not a runtime condition an embedder can recover from.

Example:

//go:embed scheme
var schemeFS embed.FS

eng, err := wile.NewEngine(ctx,
    wile.WithSourceFS(schemeFS),  // searched first
    wile.WithSourceOS(),          // OS filesystem searched last
)

func WithSourceOS ¶

func WithSourceOS() EngineOption

WithSourceOS adds the OS filesystem to the source file resolver chain. This is typically called last so that virtual filesystems are searched first. When no resolver options are used, the engine defaults to the OS filesystem; WithSourceOS is only needed when building an explicit chain with WithSourceFS.

Example:

eng, err := wile.NewEngine(ctx,
    wile.WithSourceFS(embedFS),  // virtual FS first
    wile.WithSourceOS(),         // OS fallback last
)

func WithStrictNamespace ¶ added in v1.18.0

func WithStrictNamespace() EngineOption

WithStrictNamespace makes the engine's top level start BARE: the profile's extension primitives are REGISTERED (so libraries can import them) but are NOT pre-bound at the top level. Reach them with (import …). Core primitives and core syntax remain visible, so the bare surface matches a Tiny engine's; the full profile registry is still used for library environments, so a layered import such as (import (scheme r5rs)) resolves over the bare baseline.

Orthogonal to WithProfile/WithSandbox/WithAuthorizer; composes commutatively. The profile (or explicit WithExtension set) remains the security boundary — strict mode never widens what is reachable, it only withholds it from the top level until imported. Off by default.

The bare surface is carved when the namespace is built, so strictness must be set at namespace-creation time. Like WithRegistry/WithExtension/WithoutCore, this option has no effect on the WithNamespace path (a pre-built namespace is authoritative for its own top level) — bake strictness in at NewNamespace. It is incompatible with WithRegistry/WithoutCore (which supply a custom or coreless registry): strict mode derives its bare surface from the default core registry, so the combination is rejected at construction.

func WithoutCore ¶

func WithoutCore() EngineOption

WithoutCore creates an engine with an empty registry — no core primitives (arithmetic, pairs, control flow, etc.) are added. Extensions added via WithExtension are still applied.

This is useful for building minimal engines where only specific extensions are needed, or for testing extension isolation.

func SandboxEnvPrefix ¶

func SandboxEnvPrefix(prefix string) SandboxOption

SandboxEnvPrefix sets the environment variable prefix that the sandbox allows reading. Default is "WILE_".

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.

func WrapValue ¶

func WrapValue(v values.Value) Value

WrapValue wraps a values.Value as a wile.Value for use with Engine methods that accept Value (FormLabel, DisassembleValue, etc.). Returns nil if v is nil.