machine

func (*CapturedContinuation) AcceptsArity ¶ added in v1.7.0

func (p *CapturedContinuation) AcceptsArity(n int) bool

AcceptsArity reports whether this continuation can be called with n arguments. Escape continuations accept exactly 1 argument — the value to resume with.

func (*CapturedContinuation) ComposableContinuation ¶ added in v1.7.0

func (p *CapturedContinuation) ComposableContinuation() *ComposableContinuation

ComposableContinuation returns the underlying composable continuation, which carries the MachineContinuation chain for mark extraction.

func (*CapturedContinuation) EqualTo ¶ added in v1.7.0

func (p *CapturedContinuation) EqualTo(o values.Value) bool

func (*CapturedContinuation) IsVoid ¶ added in v1.7.0

func (p *CapturedContinuation) IsVoid() bool

func (*CapturedContinuation) SchemeString ¶ added in v1.7.0

func (p *CapturedContinuation) SchemeString() string

func (*CaseLambdaClosure) AcceptsArity ¶ added in v1.5.0

func (p *CaseLambdaClosure) AcceptsArity(n int) bool

AcceptsArity reports whether any clause in this case-lambda can accept n arguments.

func (*CaseLambdaClosure) Clauses ¶

func (p *CaseLambdaClosure) Clauses() []*MachineClosure

func (*CaseLambdaClosure) EqualTo ¶

func (p *CaseLambdaClosure) EqualTo(o values.Value) bool

EqualTo implements Scheme equality for case-lambda closures. Two void closures (nil receivers) are considered equal to each other. Non-void closures are equal only if they have the same number of clauses and each corresponding clause is EqualTo its counterpart.

func (*CaseLambdaClosure) FindMatchingClause ¶

func (p *CaseLambdaClosure) FindMatchingClause(argCount int) (*MachineClosure, bool)

FindMatchingClause finds the first clause that matches the given argument count. It returns the matching closure and true when a clause can accept exactly argCount arguments (for fixed-arity clauses) or at least argCount arguments (for variadic clauses). If the receiver is nil or no clause matches, it returns nil, false.

func (*CaseLambdaClosure) IsVoid ¶

func (p *CaseLambdaClosure) IsVoid() bool

IsVoid reports whether this value represents the absence of a case-lambda closure. A nil receiver is treated as a distinguished "void" closure value, used as a sentinel to mean "no closure" rather than an error.

func (*CaseLambdaClosure) SchemeString ¶

func (p *CaseLambdaClosure) SchemeString() string

SchemeString returns the Scheme-readable representation of a case-lambda closure. Note that the void value (nil receiver) still prints as a case-lambda closure; callers must use IsVoid to distinguish the sentinel.

func (*ChainFileResolver) EnumerateLibraries ¶ added in v1.10.3

func (p *ChainFileResolver) EnumerateLibraries() ([]LibraryName, error)

EnumerateLibraries unions library enumerations from all child resolvers that implement LibraryEnumerator. First resolver wins on duplicate keys, matching the resolution priority order. Errors from child resolvers propagate immediately, matching ChainFileResolver.ResolveAndOpen behavior.

func (*ChainFileResolver) ResolveAndOpen ¶ added in v1.7.2

func (p *ChainFileResolver) ResolveAndOpen(ctx context.Context, path string) (fs.File, string, error)

func (CompileTimeCallContext) Context ¶ added in v1.5.0

func (p CompileTimeCallContext) Context() context.Context

Context returns the context associated with this compile-time call context.

func (CompileTimeCallContext) NotInTail ¶

func (p CompileTimeCallContext) NotInTail() CompileTimeCallContext

NotInTail returns a copy of the context with inTail set to false. Use this when compiling sub-expressions that are not in tail position:

• Function arguments
• Condition expressions in if
• Initial values in define/let bindings
• Non-final expressions in begin

Example:

// Compiling (f (g x)) - the call to g is not in tail position
err := p.CompileExpression(ctctx.NotInTail(), argExpr)

func (*CompileTimeContinuation) AppendOperations ¶

func (p *CompileTimeContinuation) AppendOperations(ops ...Operation)

AppendOperations appends operations tagged with the current source from the source stack. Routes through the integer-dispatch code[] path: Wave 1-3 operations become direct instructions, everything else goes via OpComplex to the sideTable.

func (*CompileTimeContinuation) CompileBeginForSyntax ¶

func (p *CompileTimeContinuation) CompileBeginForSyntax(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileBeginForSyntax handles (begin-for-syntax expr ...).

Evaluates a sequence of expressions at compile time in the expand phase environment. Used for setting up compile-time state (hash tables, registries) that macros can access. No runtime effect — used for side effects only.

func (*CompileTimeContinuation) CompileCondExpand ¶

func (p *CompileTimeContinuation) CompileCondExpand(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileCondExpand compiles a cond-expand expression. cond-expand is evaluated at compile-time and expands to the body of the first clause whose feature requirement is satisfied.

Syntax: (cond-expand <clause> ...) where <clause> is (<feature-requirement> <expression> ...)

Example:

(cond-expand
  (r7rs (display "R7RS"))
  (else (display "other")))

func (*CompileTimeContinuation) CompileDefineForSyntax ¶

func (p *CompileTimeContinuation) CompileDefineForSyntax(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileDefineForSyntax handles (define-for-syntax name expr) or (define-for-syntax (name args...) body...).

This form defines a binding in the expand phase environment that is available during macro expansion. The expression is compiled and evaluated at compile time, and the result is stored in env.Expand().

Unlike define-syntax (which stores macro transformers), define-for-syntax stores regular values with BindingTypeVariable.

func (*CompileTimeContinuation) CompileDefineLibrary ¶

func (p *CompileTimeContinuation) CompileDefineLibrary(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileDefineLibrary handles (define-library (lib-name) <library-declaration> ...).

R7RS library syntax:

(define-library <library-name>
  <library-declaration> ...)

<library-declaration> =
  | (export <export-spec> ...)
  | (import <import-set> ...)
  | (begin <command-or-definition> ...)
  | (include <filename> ...)
  | (include-ci <filename> ...)

This creates an isolated environment for the library, processes declarations in order, and registers the compiled library in the registry.

func (*CompileTimeContinuation) CompileDefineSyntax ¶

func (p *CompileTimeContinuation) CompileDefineSyntax(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileDefineSyntax handles (define-syntax keyword transformer-expr).

This is the compile-time handler for R7RS define-syntax. Unlike most definitions, define-syntax is processed entirely at compile time:

1. Parse the form: (define-syntax keyword (syntax-rules ...))
2. Compile the syntax-rules transformer to a MachineClosure
3. Store the closure in the environment with BindingTypeSyntax
4. Emit NO runtime operations (the binding is already established)

The BindingTypeSyntax marker is crucial: when the expander encounters a symbol, it checks if that symbol is bound to a syntax transformer. If so, it invokes the transformer closure to expand the macro.

This is how derived expressions like 'let' work: they're defined as macros using define-syntax, and expand to lambda expressions:

(define-syntax let
  (syntax-rules ()
    ((let ((name val) ...) body)
     ((lambda (name ...) body) val ...))))

Reference: R7RS Section 5.4 (Syntax definitions)

func (*CompileTimeContinuation) CompileEvalWhen ¶

func (p *CompileTimeContinuation) CompileEvalWhen(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileEvalWhen handles (eval-when (phase ...) body ...).

This form controls when code is evaluated based on phase specifiers. Phase names follow Chez Scheme's eval-when (Dybvig, TSPL §12.10):

• expand: evaluate during macro expansion (at compile time)
• compile: evaluate during compilation (currently same as expand)
• run: evaluate at runtime (generate code for normal execution)

Multiple phases can be specified. If both expand and run are specified, the body is evaluated at compile time AND code is generated for runtime.

eval-when is not part of R7RS-small; it is a Wile extension.

Examples:

(eval-when (expand)
  (display "at expansion time"))

(eval-when (run)
  (display "at runtime"))

(eval-when (expand run)
  (display "both times"))

func (*CompileTimeContinuation) CompileExport ¶

func (p *CompileTimeContinuation) CompileExport(_ CompileTimeCallContext, _ syntax.SyntaxValue) error

CompileExport handles top-level (export <export-spec> ...).

This is only valid within a library definition. At top-level, it's an error.

func (*CompileTimeContinuation) CompileExpression ¶

func (p *CompileTimeContinuation) CompileExpression(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileExpression compiles a general expression. Pushes the expression's source context onto the source stack so that all operations emitted during compilation (including infrastructure ops like Branch and Push) are tagged with the source location.

func (*CompileTimeContinuation) CompileImport ¶

func (p *CompileTimeContinuation) CompileImport(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileImport handles top-level (import <import-set> ...).

This is for top-level imports outside of a library definition. It loads the specified libraries and binds their exports in the current environment.

Supports Racket-style phased imports:

• (import (scheme base)) ; Phase 0 (runtime)
• (import (for-syntax (scheme base))) ; Phase 1 (expand)
• (import (for-template (scheme base))) ; Phase -1
• (import (for-meta 2 (scheme base))) ; Phase 2

func (*CompileTimeContinuation) CompileInclude ¶

func (p *CompileTimeContinuation) CompileInclude(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileInclude compiles an include expression. It reads and compiles all forms from the specified files in order. Each form is expanded and compiled in the current environment.

func (*CompileTimeContinuation) CompileIncludeCi ¶

func (p *CompileTimeContinuation) CompileIncludeCi(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileIncludeCi compiles an include-ci expression. It reads and compiles all forms from the specified files in order, treating symbols as case-insensitive (folded to lowercase).

func (*CompileTimeContinuation) CompileMeta ¶

func (p *CompileTimeContinuation) CompileMeta(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileMeta compiles a meta expression.

func (*CompileTimeContinuation) CompileQuasisyntax ¶

func (p *CompileTimeContinuation) CompileQuasisyntax(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileQuasisyntax compiles the (quasisyntax template) form.

quasisyntax is like quasiquote but for syntax objects. It supports:

• (unsyntax expr) - evaluate expr and splice result at depth 1
• (unsyntax-splicing expr) - evaluate and splice list at depth 1
• nested quasisyntax increases depth

Like quasiquote, unsyntax only evaluates when depth reaches 0. The result is a syntax object, not a raw datum.

func (*CompileTimeContinuation) CompileSelfEvaluating ¶

func (p *CompileTimeContinuation) CompileSelfEvaluating(_ CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileSelfEvaluating compiles a self-evaluating expression (literal).

func (*CompileTimeContinuation) CompileSymbol ¶

func (p *CompileTimeContinuation) CompileSymbol(ctctx CompileTimeCallContext, expr *syntax.SyntaxSymbol) error

CompileSymbol compiles a syntax symbol expression.

func (*CompileTimeContinuation) CompileSyntax ¶

func (p *CompileTimeContinuation) CompileSyntax(_ CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileSyntax compiles the (syntax template) form.

Unlike quote which unwraps syntax to raw values, syntax preserves the syntax structure. When used inside syntax-case, pattern variables in the template are substituted with their matched values.

For templates containing ellipsis (...), runtime expansion is used because ellipsis patterns capture variable-length lists that must be expanded dynamically.

(syntax template) -> syntax-object

func (*CompileTimeContinuation) CompileSyntaxCase ¶

func (p *CompileTimeContinuation) CompileSyntaxCase(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileSyntaxCase compiles the (syntax-case expr (literal ...) clause ...) form.

R6RS syntax-case is a pattern matching form that provides procedural macro facilities. Unlike syntax-rules which expands to templates, syntax-case evaluates arbitrary Scheme code in the body, with pattern variables bound as local variables.

Syntax:

(syntax-case expr (literal ...)
  (pattern body)
  (pattern fender body)
  ...)

Compilation strategy:

1. Compile expr to get the input syntax object
2. For each clause, generate pattern matching and body code
3. Pattern variables are bound as local variables in the body's scope
4. If fender exists, it's evaluated as a guard condition

func (*CompileTimeContinuation) CompileUnquote ¶

func (p *CompileTimeContinuation) CompileUnquote(_ CompileTimeCallContext, _ syntax.SyntaxValue) error

CompileUnquote errors - unquote outside of quasiquote

func (*CompileTimeContinuation) CompileUnquoteSplicing ¶

func (p *CompileTimeContinuation) CompileUnquoteSplicing(_ CompileTimeCallContext, _ syntax.SyntaxValue) error

CompileUnquoteSplicing errors - unquote-splicing outside of quasiquote

func (*CompileTimeContinuation) CompileUnsyntax ¶

func (p *CompileTimeContinuation) CompileUnsyntax(_ CompileTimeCallContext, _ syntax.SyntaxValue) error

CompileUnsyntax errors - unsyntax outside of quasisyntax

func (*CompileTimeContinuation) CompileUnsyntaxSplicing ¶

func (p *CompileTimeContinuation) CompileUnsyntaxSplicing(_ CompileTimeCallContext, _ syntax.SyntaxValue) error

CompileUnsyntaxSplicing errors - unsyntax-splicing outside of quasisyntax

func (*CompileTimeContinuation) CompileValidatedApply ¶ added in v1.5.0

func (p *CompileTimeContinuation) CompileValidatedApply(ctctx CompileTimeCallContext, v *validate.ValidatedApply) error

CompileValidatedApply compiles a validated (apply proc arg1 ... args) form.

R7RS §6.10: apply calls proc with the arguments arg1 ... concatenated with the elements of args (the final argument, which must be a list).

Bytecode (non-tail):

SaveContinuation →after
<compile proc>          PUSH
<compile arg1>          PUSH
...
<compile argN>          PUSH
<compile finalList>              ; value = finalList
OpUnpackListToStack              ; stack: [proc, arg1, ..., argN, x1, x2, ...]
Pull                             ; value = proc
Apply                            ; calls proc(arg1, ..., argN, x1, x2, ...)
after:

Tail position: same without SaveContinuation/patch.

func (*CompileTimeContinuation) CompileValidatedBegin ¶

func (p *CompileTimeContinuation) CompileValidatedBegin(ctctx CompileTimeCallContext, v *validate.ValidatedBegin) error

CompileValidatedBegin compiles a validated (begin expr...) form.

begin (R7RS 4.2.3) sequences expressions for side effects. All expressions are evaluated left-to-right; the value of the last expression becomes the value of the entire begin form.

R7RS §5.3.2: Internal definitions use letrec* semantics - all defined names are visible throughout the body, enabling forward references between defines.

Example: (begin (display "hello") (newline) 42) => 42 (after printing)

func (*CompileTimeContinuation) CompileValidatedCaseLambda ¶

func (p *CompileTimeContinuation) CompileValidatedCaseLambda(ctctx CompileTimeCallContext, v *validate.ValidatedCaseLambda) error

CompileValidatedCaseLambda compiles a validated (case-lambda [clause] ...) form.

case-lambda (R7RS 4.2.9) creates a procedure that dispatches to different implementations based on the number of arguments. For example:

(case-lambda
  ((x) (* x x))           ; 1 arg: square
  ((x y) (* x y))         ; 2 args: multiply
  ((x y . rest) (apply + x y rest)))  ; 2+ args: sum all

At runtime, the VM selects the first clause whose arity matches the call.

func (*CompileTimeContinuation) CompileValidatedDefine ¶

func (p *CompileTimeContinuation) CompileValidatedDefine(ctctx CompileTimeCallContext, v *validate.ValidatedDefine) error

CompileValidatedDefine compiles a validated define form.

func (*CompileTimeContinuation) CompileValidatedDefineFn ¶

func (p *CompileTimeContinuation) CompileValidatedDefineFn(ctctx CompileTimeCallContext, v *validate.ValidatedDefine) error

CompileValidatedDefineFn compiles the function shorthand form of define.

Usage: (define (name param ...) body ...)

(define (name param ... . rest) body ...)

This is syntactic sugar equivalent to:

(define name (lambda (param ...) body ...))

Examples:

(define (square x) (* x x))           ; fixed arity
(define (sum . args) (apply + args))  ; variadic (all args)
(define (sum x . rest) (apply + x rest))  ; variadic (1+ args)

The function name is bound before compiling the body to enable self-recursion:

(define (fact n) (if (<= n 1) 1 (* n (fact (- n 1)))))

func (*CompileTimeContinuation) CompileValidatedDynamicWind ¶

func (p *CompileTimeContinuation) CompileValidatedDynamicWind(ctctx CompileTimeCallContext, v *validate.ValidatedDynamicWind) error

CompileValidatedDynamicWind compiles a validated (dynamic-wind before thunk after) form.

R7RS §6.10: dynamic-wind calls thunk without arguments, returning the result(s). Before is called whenever execution enters the dynamic extent of the call to thunk, and after is called whenever it exits.

The key insight is that by compiling to bytecode, the cleanup code (calling after) is in the bytecode stream. When a continuation is captured inside the thunk and later restored, the cleanup code will run on normal completion.

Bytecode structure:

<compile before> PUSH
<compile thunk>  PUSH
<compile after>  PUSH          ; Stack: [before, thunk, after]
PEEK_K 2                       ; value = before
SAVE_CONTINUATION →after_before
APPLY                          ; call before()
after_before:                  ; Stack: [before, thunk, after]
OP_PUSH_WIND                   ; create winding frame
PEEK_K 1                       ; value = thunk
SAVE_CONTINUATION →after_thunk
APPLY                          ; call thunk()
after_thunk:                   ; Stack: [before, thunk, after]
PUSH                           ; save thunk result, Stack: [before, thunk, after, result]
OP_POP_WIND                    ; pop winding frame
PEEK_K 1                       ; value = after
SAVE_CONTINUATION →after_after
APPLY                          ; call after()
after_after:                   ; Stack: [before, thunk, after, result]
PEEK_K 0                       ; value = result (thunk's return value)
DROP DROP DROP DROP            ; clean up stack

func (*CompileTimeContinuation) CompileValidatedIf ¶

func (p *CompileTimeContinuation) CompileValidatedIf(ctctx CompileTimeCallContext, v *validate.ValidatedIf) error

CompileValidatedIf compiles a validated (if test conseq [alt]) form. The structure is guaranteed to be valid by the validator.

Constant folding (Aho et al., Compilers §8.5): when the test is a compile-time literal, the entire if-form reduces to one branch. This is the simplest form of constant folding — evaluating known expressions at compile time rather than runtime. See BIBLIOGRAPHY.md "Constant Folding".

func (*CompileTimeContinuation) CompileValidatedLambda ¶

func (p *CompileTimeContinuation) CompileValidatedLambda(ctctx CompileTimeCallContext, v *validate.ValidatedLambda) error

CompileValidatedLambda compiles a validated (lambda params body...) form.

func (*CompileTimeContinuation) CompileValidatedLet ¶ added in v1.9.4

func (p *CompileTimeContinuation) CompileValidatedLet(
	ctctx CompileTimeCallContext,
	v *validate.ValidatedLet,
) error

CompileValidatedLet compiles all binding forms based on Kind.

let: <inits> Push... | OpPushEnv | StoreLocal(reverse) | body | OpPopEnv let*: OpPushEnv | (init Push StoreLocal)... | body | OpPopEnv letrec: OpPushEnv | <inits> Push... | StoreLocal(reverse) | body | OpPopEnv letrec*: OpPushEnv | (init Push StoreLocal)... | body | OpPopEnv

func (*CompileTimeContinuation) CompileValidatedQuasiquote ¶

func (p *CompileTimeContinuation) CompileValidatedQuasiquote(ctctx CompileTimeCallContext, v *validate.ValidatedQuasiquote) error

CompileValidatedQuasiquote compiles a validated (quasiquote template) form. Quasiquote has complex runtime semantics, so we delegate to the existing compiler.

func (*CompileTimeContinuation) CompileValidatedQuote ¶

func (p *CompileTimeContinuation) CompileValidatedQuote(_ CompileTimeCallContext, v *validate.ValidatedQuote) error

CompileValidatedQuote compiles a validated (quote datum) form.

func (*CompileTimeContinuation) CompileValidatedSetBang ¶

func (p *CompileTimeContinuation) CompileValidatedSetBang(ctctx CompileTimeCallContext, v *validate.ValidatedSetBang) error

CompileValidatedSetBang compiles a validated (set! name expr) form.

func (*CompileTimeContinuation) CompileValidatedWithContinuationMark ¶ added in v1.7.0

func (p *CompileTimeContinuation) CompileValidatedWithContinuationMark(
	ctctx CompileTimeCallContext,
	v *validate.ValidatedWithContinuationMark,
) error

CompileValidatedWithContinuationMark compiles (with-continuation-mark key val body).

Tail position:

<compile key> PUSH
<compile val>
SetContMark               ; pops key, sets marks[key] = val
<compile body in tail>

Non-tail position:

<compile key> PUSH
<compile val>
SaveContMark              ; pops key, saves (key, old) on stack, sets mark
<compile body in non-tail>
RestoreContMark           ; pops (old, key), restores mark

func (*CompileTimeContinuation) CompileWithSyntax ¶

func (p *CompileTimeContinuation) CompileWithSyntax(ctctx CompileTimeCallContext, expr syntax.SyntaxValue) error

CompileWithSyntax compiles the (with-syntax ((pattern expr) ...) body ...) form.

with-syntax is a convenience form for binding pattern variables from expressions. It's equivalent to:

(syntax-case (list expr ...) ()
  ((pattern ...) (let () body ...)))

For now, this implements a simple transformation approach.

func (*CompileTimeContinuation) SetFileResolver ¶ added in v1.6.0

func (p *CompileTimeContinuation) SetFileResolver(r FileResolver)

SetFileResolver overrides the file resolver used by include/load. Nil resets to the environment's resolver (or OSFileResolver as fallback).

func (*CompileTimeContinuation) SetLibraryCallback ¶

func (p *CompileTimeContinuation) SetLibraryCallback(cb func(*CompiledLibrary))

SetLibraryCallback sets a callback function that will be called when a library is compiled via CompileDefineLibrary. This is used by LoadLibrary to capture the compiled library.

func (*CompiledLibrary) AddExport ¶

func (p *CompiledLibrary) AddExport(externalName, internalName string)

AddExport adds an export to the library. If internalName is empty, it defaults to externalName (no rename).

func (*CompiledLibrary) GetInternalName ¶

func (p *CompiledLibrary) GetInternalName(externalName string) string

GetInternalName returns the internal name for an exported external name. Returns empty string if not exported.

func (*CompiledLibrary) IsExported ¶

func (p *CompiledLibrary) IsExported(externalName string) bool

IsExported returns true if the given external name is exported.

func (*ComposableContinuation) AcceptsArity ¶ added in v1.5.0

func (p *ComposableContinuation) AcceptsArity(n int) bool

AcceptsArity reports whether this composable continuation can be called with n arguments. Composable continuations accept exactly 1 argument — the value to resume with.

func (*ComposableContinuation) AcquireSegment ¶ added in v1.6.0

func (p *ComposableContinuation) AcquireSegment() *MachineContinuation

AcquireSegment returns the continuation segment for grafting.

First invocation marks the segment shared and returns it directly, avoiding a DeepCopy. Shared marking ensures RestoreAndRelease preserves frame evals for potential re-invocation.

Subsequent invocations reset the bottom frame's parent to nil (undoing GraftContinuation's mutation from the prior invocation) and deep-copy from the preserved shared frames.

This optimizes one-shot continuations (the common case in Schelog-style backtracking), eliminating O(depth) frame allocations per invocation.

func (*ComposableContinuation) BarrierValid ¶ added in v1.4.0

func (p *ComposableContinuation) BarrierValid() *BarrierToken

BarrierValid returns the barrier identity token captured when this continuation was created. Used by applyComposableContinuation to detect barrier crossings.

func (*ComposableContinuation) Cont ¶

func (p *ComposableContinuation) Cont() *MachineContinuation

func (*ComposableContinuation) EqualTo ¶

func (p *ComposableContinuation) EqualTo(o values.Value) bool

func (*ComposableContinuation) IsVoid ¶

func (p *ComposableContinuation) IsVoid() bool

func (*ComposableContinuation) SchemeString ¶

func (p *ComposableContinuation) SchemeString() string

func (*ComposableContinuation) ThreadID ¶ added in v1.1.0

func (p *ComposableContinuation) ThreadID() uint64

func (*ComposableContinuation) WindingStack ¶

func (p *ComposableContinuation) WindingStack() WindingStack

func (*ContinuationMarkSet) EqualTo ¶ added in v1.7.0

func (p *ContinuationMarkSet) EqualTo(o values.Value) bool

func (*ContinuationMarkSet) First ¶ added in v1.7.0

func (p *ContinuationMarkSet) First(key, defaultVal values.Value) values.Value

First returns the value for key from the nearest frame, or defaultVal if no frame contains the key. Uses eq? semantics (eqIdentity) for key comparison.

func (*ContinuationMarkSet) IsVoid ¶ added in v1.7.0

func (p *ContinuationMarkSet) IsVoid() bool

func (*ContinuationMarkSet) SchemeString ¶ added in v1.7.0

func (p *ContinuationMarkSet) SchemeString() string

func (*ContinuationMarkSet) ToList ¶ added in v1.7.0

func (p *ContinuationMarkSet) ToList(key values.Value) values.Tuple

ToList returns a list of values for key across all frames, nearest first. Returns the empty list if no frame contains the key. Uses eq? semantics (eqIdentity) for key comparison.

func (*ContinuationMarkSet) ToListStar ¶ added in v1.7.0

func (p *ContinuationMarkSet) ToListStar(keys []values.Value, noneVal values.Value) values.Tuple

ToListStar returns a list of vectors for multiple keys across all frames. Each vector corresponds to a frame that has at least one of the requested keys. Vector positions correspond to the keys slice; noneVal fills missing keys. Uses eq? semantics (eqIdentity) for key comparison.

Racket §10.5: continuation-mark-set->list*

func (*Debugger) Breakpoints ¶

func (p *Debugger) Breakpoints() []*Breakpoint

Breakpoints returns all breakpoints.

func (*Debugger) CheckBreakpoint ¶

func (p *Debugger) CheckBreakpoint(mc *MachineContext) *Breakpoint

CheckBreakpoint checks if execution should break at current location.

func (*Debugger) Continue ¶

func (p *Debugger) Continue()

Continue resumes execution.

func (*Debugger) DisableBreakpoint ¶

func (p *Debugger) DisableBreakpoint(id BreakpointID) bool

DisableBreakpoint disables a breakpoint.

func (*Debugger) EnableBreakpoint ¶

func (p *Debugger) EnableBreakpoint(id BreakpointID) bool

EnableBreakpoint enables a breakpoint.

func (*Debugger) IsStepping ¶

func (p *Debugger) IsStepping() bool

IsStepping returns whether the debugger is in stepping mode.

func (*Debugger) OnBreak ¶

func (p *Debugger) OnBreak(fn func(mc *MachineContext, bp *Breakpoint))

OnBreak sets the callback for when a breakpoint is hit.

func (*Debugger) RemoveBreakpoint ¶

func (p *Debugger) RemoveBreakpoint(id BreakpointID) bool

RemoveBreakpoint removes a breakpoint.

func (*Debugger) SetBreakpoint ¶

func (p *Debugger) SetBreakpoint(file string, line, column int) BreakpointID

SetBreakpoint adds a breakpoint at the given source location.

func (*Debugger) ShouldStep ¶

func (p *Debugger) ShouldStep(mc *MachineContext) bool

ShouldStep checks if we should break due to stepping.

func (*Debugger) StepInto ¶

func (p *Debugger) StepInto()

StepInto enables step-into mode.

func (*Debugger) StepOut ¶

func (p *Debugger) StepOut(mc *MachineContext)

StepOut enables step-out mode.

func (*Debugger) StepOver ¶

func (p *Debugger) StepOver(mc *MachineContext)

StepOver enables step-over mode.

func (*Debugger) TriggerBreak ¶

func (p *Debugger) TriggerBreak(mc *MachineContext, bp *Breakpoint)

TriggerBreak calls the break callback if set.

func (*ERMacroTransformer) Closure ¶ added in v1.7.0

func (p *ERMacroTransformer) Closure() *MachineClosure

func (*ERMacroTransformer) DefEnv ¶ added in v1.7.0

func (p *ERMacroTransformer) DefEnv() *environment.EnvironmentFrame

func (*ERMacroTransformer) EqualTo ¶ added in v1.7.0

func (p *ERMacroTransformer) EqualTo(o values.Value) bool

func (*ERMacroTransformer) IsVoid ¶ added in v1.7.0

func (p *ERMacroTransformer) IsVoid() bool

func (*ERMacroTransformer) SchemeString ¶ added in v1.7.0

func (p *ERMacroTransformer) SchemeString() string

func (*EditPlan) AddLiteral ¶ added in v1.5.0

func (p *EditPlan) AddLiteral(v values.Value) int32

AddLiteral adds a value to the template's literal pool, with deduplication. Returns the index suitable for use in Instruction.Arg fields that reference the literal pool (OpLoadLiteral, OpLoadGlobal, OpStoreGlobal).

func (*EditPlan) Apply ¶ added in v1.5.0

func (p *EditPlan) Apply() int

Apply rewrites the template according to all accumulated edits:

1. Sorts and validates edits (panics on overlap)
2. Builds a PC remap from old positions to new positions
3. Fixes branch offsets for surviving original instructions
4. Rebuilds code + sourceRefs, splicing in replacements
5. Garbage-collects unreferenced sideTable entries, remaps OpComplex.Arg

Returns the net change in instruction count (negative means code shrunk).

func (*EditPlan) Delete ¶ added in v1.5.0

func (p *EditPlan) Delete(start, end int)

Delete marks the range [start, end) for removal.

func (*EditPlan) HasEdits ¶ added in v1.5.0

func (p *EditPlan) HasEdits() bool

HasEdits reports whether any edits have been added.

func (*EditPlan) Insert ¶ added in v1.5.0

func (p *EditPlan) Insert(at int, instrs []Instruction, src uint16)

Insert inserts instrs before the instruction at position at.

func (*EditPlan) Replace ¶ added in v1.5.0

func (p *EditPlan) Replace(start, end int, instrs []Instruction, src uint16)

Replace marks the range [start, end) for replacement with instrs. src is the source reference for all inserted instructions.

func (*EmbedFileResolver) ResolveAndOpen ¶ added in v1.6.0

func (p *EmbedFileResolver) ResolveAndOpen(_ context.Context, path string) (fs.File, string, error)

func (*ErrExceptionEscape) Error ¶

func (p *ErrExceptionEscape) Error() string

Error implements the error interface.

When Source is present and the condition is a NativeError, produces clean human-readable output like "file:5:3: error: division by zero". For non-NativeError conditions with Source, produces "file:5:3: exception: foo". When no Source is set, falls back to the original format for backward compat.

func (*ErrExceptionEscape) Unwrap ¶ added in v1.3.0

func (p *ErrExceptionEscape) Unwrap() error

Unwrap returns the underlying error when the condition implements the error interface (e.g., *NativeError). This enables errors.Is/errors.As to traverse through ErrExceptionEscape into the wrapped error chain, supporting sentinel matching like errors.Is(err, werr.ErrDivisionByZero) from Go callers.

func (*ErrPromptAbort) Error ¶

func (p *ErrPromptAbort) Error() string

func (*ExceptionHandler) Handler ¶

func (p *ExceptionHandler) Handler() values.Callable

Handler returns the handler procedure.

func (*ExceptionHandler) Parent ¶

func (p *ExceptionHandler) Parent() *ExceptionHandler

Parent returns the previous handler in the chain.

func (*ExpanderContext) Env ¶

func (p *ExpanderContext) Env() *environment.EnvironmentFrame

Env returns the environment frame associated with this context.

func (*ExpanderContext) Expand ¶

func (p *ExpanderContext) Expand(stx syntax.SyntaxValue) (syntax.SyntaxValue, error)

Expand fully expands a syntax object.

func (*ExpanderContext) ExpandOnce ¶

func (p *ExpanderContext) ExpandOnce(stx syntax.SyntaxValue) (syntax.SyntaxValue, bool, error)

ExpandOnce performs a single step of macro expansion. Returns (expanded-syntax, did-expand, error). If the input is a macro call, it expands it once and returns (result, true, nil). If the input is not a macro call, it returns (input, false, nil).

func (*ExpanderContext) IntroductionScope ¶

func (p *ExpanderContext) IntroductionScope() *syntax.Scope

IntroductionScope returns the introduction scope for the current macro expansion. This scope is added to identifiers introduced by a macro and can be flipped using syntax-local-introduce.

func (*ExpanderContext) SetIntroductionScope ¶

func (p *ExpanderContext) SetIntroductionScope(scope *syntax.Scope)

SetIntroductionScope sets the introduction scope for the current macro expansion.

func (*ExpanderContext) SetUseSiteScope ¶

func (p *ExpanderContext) SetUseSiteScope(scope *syntax.Scope)

SetUseSiteScope sets the use-site scope for binding forms.

func (*ExpanderContext) UseSiteScope ¶

func (p *ExpanderContext) UseSiteScope() *syntax.Scope

UseSiteScope returns the use-site scope for binding forms. This scope is used by syntax-local-identifier-as-binding to mark identifiers as binding sites.

func (*ExpanderTimeContinuation) Context ¶ added in v1.5.0

func (p *ExpanderTimeContinuation) Context() context.Context

Context returns the context associated with this expander continuation.

func (*ExpanderTimeContinuation) ExpandBodyWithDefineSyntax ¶

func (p *ExpanderTimeContinuation) ExpandBodyWithDefineSyntax(
	forms []syntax.SyntaxValue,
) ([]syntax.SyntaxValue, error)

ExpandBodyWithDefineSyntax expands a sequence of body forms, compiling define-syntax forms as encountered so subsequent forms can use the macros.

This unifies the expansion pattern used by: - Lambda bodies (internal define-syntax) - Library bodies (top-level define-syntax) - Include files (top-level define-syntax)

R7RS §5.3: Internal define-syntax forms must be processed before expanding subsequent body expressions so that locally-defined macros are visible.

R7RS §5.3.2: Bodies use letrec* semantics where all defined names are visible to all initializers. This enables forward references within macros - a macro can reference a definition that appears later in the same body.

func (*ExpanderTimeContinuation) ExpandExpression ¶

func (p *ExpanderTimeContinuation) ExpandExpression(expr syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandExpression expands a syntax expression.

func (*ExpanderTimeContinuation) ExpandOnce ¶

func (p *ExpanderTimeContinuation) ExpandOnce(expr syntax.SyntaxValue) (syntax.SyntaxValue, bool, error)

ExpandOnce performs a single step of macro expansion. Returns (expanded-syntax, did-expand, error). If the input is a macro call, it expands it once and returns (result, true, nil). If the input is not a macro call, it returns (input, false, nil). Unlike ExpandExpression, this does NOT recursively expand the result.

func (*ExpanderTimeContinuation) ExpandPrimitiveForm ¶

func (p *ExpanderTimeContinuation) ExpandPrimitiveForm(primName string, sym *syntax.SyntaxSymbol, expr syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandPrimitiveForm handles expansion within primitive forms like if, begin, lambda, define, etc. Some primitives need their subexpressions expanded (like if, begin) while others should be left unchanged (like quote, define-syntax).

This function looks up the primitive expander in the expand environment registry. If found, it invokes the expander; otherwise returns the form unchanged.

func (*ExpanderTimeContinuation) ExpandQuasiquote ¶

func (p *ExpanderTimeContinuation) ExpandQuasiquote(_ syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandQuasiquote handles the expansion of quasiquoted expressions.

func (*ExpanderTimeContinuation) ExpandQuote ¶

func (p *ExpanderTimeContinuation) ExpandQuote(_ syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandQuote handles the expansion of quoted expressions.

func (*ExpanderTimeContinuation) ExpandSelfEvaluating ¶

func (p *ExpanderTimeContinuation) ExpandSelfEvaluating(expr syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandSelfEvaluating handles self-evaluating expressions.

func (*ExpanderTimeContinuation) ExpandSymbol ¶

func (p *ExpanderTimeContinuation) ExpandSymbol(expr *syntax.SyntaxSymbol) (syntax.SyntaxValue, error)

ExpandSymbol handles a symbol expression.

func (*ExpanderTimeContinuation) ExpandSyntaxArgumentList ¶

func (p *ExpanderTimeContinuation) ExpandSyntaxArgumentList(args syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandSyntaxArgumentList expands each argument in the argument list. It returns a new syntax list with the expanded arguments.

func (*ExpanderTimeContinuation) ExpandSyntaxExpression ¶

func (p *ExpanderTimeContinuation) ExpandSyntaxExpression(sym *syntax.SyntaxSymbol, expr syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandSyntaxExpression checks if sym is a macro and expands it, or returns the expression as a procedure call if not.

This is where macro invocation happens:

1. Look up the symbol in the expand environment
2. If bound with BindingTypeSyntax, it's a macro - invoke the transformer
3. If it's a primitive (like quote, if, define-syntax), don't expand args
4. Otherwise, treat as procedure call and expand arguments

The transformer closure (MachineClosure from CompileSyntaxRules) is invoked by creating a MachineContext and running it. The transformer:

• Receives the full macro invocation form on the eval stack
• Pattern matches against its clauses (OperationSyntaxRulesTransform)
• Expands the matching template with captured bindings
• Adds an intro scope to the expansion for hygiene
• Returns the expanded syntax in the value register

The expanded result may itself contain macro invocations, so the caller should recursively expand it.

func (*ExpanderTimeContinuation) ExpandSyntaxOrProcedureCall ¶

func (p *ExpanderTimeContinuation) ExpandSyntaxOrProcedureCall(car syntax.SyntaxValue, cdr syntax.SyntaxValue) (syntax.SyntaxValue, error)

ExpandSyntaxOrProcedureCall handles a list expression. The car may be a symbol (possibly a macro), a nested pair (computed procedure), or a self-evaluating value (like in quoted data or malformed expressions).

func (*FSFileResolver) EnumerateLibraries ¶ added in v1.10.3

func (p *FSFileResolver) EnumerateLibraries() ([]LibraryName, error)

EnumerateLibraries walks the virtual filesystem to discover all libraries. It uses the same search paths as resolution: library registry paths first, then the FS root as fallback. Hidden directories (starting with ".") are skipped. Files with .sld or .scm extensions are converted to library names via FilePathToLibraryName. Duplicate library names (same key from different paths or extensions) are deduplicated, with earlier discovery winning.

Best-effort: non-existent directories are skipped gracefully, and unreadable subdirectories are skipped without failing the whole walk. Only the security authorizer can exclude individual files.

func (*FSFileResolver) ResolveAndOpen ¶ added in v1.7.1

func (p *FSFileResolver) ResolveAndOpen(_ context.Context, path string) (fs.File, string, error)

func (*ForeignClosure) AcceptsArity ¶ added in v1.5.0

func (p *ForeignClosure) AcceptsArity(n int) bool

AcceptsArity reports whether this closure can be called with n arguments.

func (*ForeignClosure) Doc ¶ added in v1.10.3

func (p *ForeignClosure) Doc() string

func (*ForeignClosure) Env ¶ added in v1.5.0

func (p *ForeignClosure) Env() *environment.EnvironmentFrame

func (*ForeignClosure) EqualTo ¶ added in v1.5.0

func (p *ForeignClosure) EqualTo(o values.Value) bool

EqualTo uses identity semantics — two foreign closures are equal only if they are the same pointer.

func (*ForeignClosure) Fn ¶ added in v1.5.0

func (p *ForeignClosure) Fn() ForeignFunction

func (*ForeignClosure) IsVariadic ¶ added in v1.5.0

func (p *ForeignClosure) IsVariadic() bool

func (*ForeignClosure) IsVoid ¶ added in v1.5.0

func (p *ForeignClosure) IsVoid() bool

func (*ForeignClosure) Name ¶ added in v1.5.0

func (p *ForeignClosure) Name() string

func (*ForeignClosure) ParameterCount ¶ added in v1.5.0

func (p *ForeignClosure) ParameterCount() int

func (*ForeignClosure) SchemeString ¶ added in v1.5.0

func (p *ForeignClosure) SchemeString() string

func (*ForeignClosure) SetDoc ¶ added in v1.10.3

func (p *ForeignClosure) SetDoc(doc string)

func (*ForeignClosure) SetName ¶ added in v1.5.0

func (p *ForeignClosure) SetName(name string)

func (*ForeignClosure) SetValidator ¶ added in v1.10.3

func (p *ForeignClosure) SetValidator(v ForeignFunction)

SetValidator installs a contract validation function that runs before the implementation. Called during registration when contract enforcement is enabled.

func (*ForeignClosure) Validator ¶ added in v1.10.3

func (p *ForeignClosure) Validator() ForeignFunction

Validator returns the installed contract validator, or nil if none.

func (*FreeIdResolution) GetGlobal ¶

func (p *FreeIdResolution) GetGlobal() *environment.GlobalIndex

GetGlobal returns the global binding's index, or nil if this is a local binding. Implements the globalBindingProvider interface for match package hygiene.

func (*FreeIdResolution) GetHasLocalBinding ¶

func (p *FreeIdResolution) GetHasLocalBinding() bool

GetHasLocalBinding returns true if a local binding was found at macro definition time. This is used to distinguish "local binding with empty scopes" from "no binding at all". Implements the hasLocalBindingProvider interface.

func (*FreeIdResolution) GetLibraryScope ¶ added in v1.6.0

func (p *FreeIdResolution) GetLibraryScope() *syntax.Scope

GetLibraryScope returns the library scope associated with this free identifier, or nil if the containing macro was not compiled inside a library. Implements the libraryScopeProvider interface for match package hygiene.

func (*FreeIdResolution) GetLocalScopes ¶

func (p *FreeIdResolution) GetLocalScopes() []*syntax.Scope

GetLocalScopes returns the local binding's scopes, or nil if this is a global binding. Implements the localScopesProvider interface for match package hygiene.

func (*FreeList[T]) Acquire ¶ added in v1.9.1

func (p *FreeList[T]) Acquire() *T

Acquire returns a recycled object from the freelist. If the freelist is empty or disabled, it calls newFn to allocate a new object.

func (*FreeList[T]) Drain ¶ added in v1.9.1

func (p *FreeList[T]) Drain()

Drain clears all cached objects from the freelist.

func (*FreeList[T]) Name ¶ added in v1.9.1

func (p *FreeList[T]) Name() string

Name returns the freelist's name.

func (*FreeList[T]) Release ¶ added in v1.9.1

func (p *FreeList[T]) Release(v *T)

Release resets the object and appends it to the freelist. If disabled, the object is discarded after reset.

func (*FreeList[T]) SetEnabled ¶ added in v1.9.1

func (p *FreeList[T]) SetEnabled(on bool)

SetEnabled toggles the freelist on or off. When disabled, Acquire calls newFn directly and Release discards after reset.

func (*FreeList[T]) Stats ¶ added in v1.9.1

func (p *FreeList[T]) Stats() PoolSnapshot

Stats returns a point-in-time snapshot of the freelist's counters.

func (*ImportSet) ApplyToExports ¶

func (p *ImportSet) ApplyToExports(lib *CompiledLibrary) (map[string]string, error)

ApplyToExports applies the import modifiers and returns the final bindings. Returns a map of local-name -> external-name (the name in the library).

func (Instruction) String ¶ added in v1.4.0

func (instr Instruction) String() string

String returns a human-readable representation of the instruction.

func (LibraryName) Key ¶

func (p LibraryName) Key() string

Key returns a unique string key for map lookups.

func (LibraryName) SchemeString ¶

func (p LibraryName) SchemeString() string

SchemeString returns the Scheme representation like "(scheme base)".

func (LibraryName) String ¶

func (p LibraryName) String() string

String returns a human-readable representation like "scheme/base".

func (LibraryName) ToFSPath ¶ added in v1.7.1

func (p LibraryName) ToFSPath() string

ToFSPath returns the library name as a forward-slash-separated path with .sld extension. Unlike ToFilePath, this always uses "/" as separator, suitable for fs.FS and FileResolver operations.

func (LibraryName) ToFilePath ¶

func (p LibraryName) ToFilePath() string

ToFilePath converts a library name to a file path. (scheme base) -> "scheme/base.sld"

func (LibraryName) ToSchemeValue ¶ added in v1.10.3

func (p LibraryName) ToSchemeValue() values.Value

ToSchemeValue converts a LibraryName to a Scheme list. Parts that parse as nonnegative integers become exact integers; all others become symbols. Matches R7RS library name syntax.

func (*LibraryRegistry) All ¶ added in v1.10.3

func (p *LibraryRegistry) All() []*CompiledLibrary

All returns all loaded libraries, sorted by name key for determinism.

func (*LibraryRegistry) AllNames ¶ added in v1.10.3

func (p *LibraryRegistry) AllNames() []LibraryName

AllNames returns the names of all registered libraries, sorted by key.

func (*LibraryRegistry) FindLibraryFile ¶

func (p *LibraryRegistry) FindLibraryFile(name LibraryName) (string, error)

FindLibraryFile searches for a library file in the search paths. Returns the full path to the file, or an error if not found.

func (*LibraryRegistry) FinishLoading ¶

func (p *LibraryRegistry) FinishLoading(name LibraryName)

FinishLoading marks a library as finished loading.

func (*LibraryRegistry) GetSearchPaths ¶

func (p *LibraryRegistry) GetSearchPaths() []string

GetSearchPaths returns the current library search paths.

func (*LibraryRegistry) ImportObserver ¶ added in v1.5.0

func (p *LibraryRegistry) ImportObserver() LibraryImportObserver

ImportObserver returns the current import observer, or nil.

func (*LibraryRegistry) IsLoading ¶

func (p *LibraryRegistry) IsLoading(name LibraryName) bool

IsLoading returns true if the library is currently being loaded. Used to detect circular dependencies.

func (*LibraryRegistry) Lookup ¶

func (p *LibraryRegistry) Lookup(name LibraryName) *CompiledLibrary

Lookup returns a library by name, or nil if not found.

func (*LibraryRegistry) PrependSearchPath ¶ added in v1.5.0

func (p *LibraryRegistry) PrependSearchPath(path string)

PrependSearchPath adds a path to the beginning of the search path list.

func (*LibraryRegistry) Register ¶

func (p *LibraryRegistry) Register(lib *CompiledLibrary) error

Register adds a compiled library to the registry.

func (*LibraryRegistry) SetImportObserver ¶ added in v1.5.0

func (p *LibraryRegistry) SetImportObserver(obs LibraryImportObserver)

SetImportObserver sets an optional observer that is called each time a library is imported. The observer is read-only and cannot influence the import. Pass nil to remove the observer.

func (*LibraryRegistry) SetSearchPaths ¶

func (p *LibraryRegistry) SetSearchPaths(paths []string)

SetSearchPaths sets the library search paths.

func (*LibraryRegistry) StartLoading ¶

func (p *LibraryRegistry) StartLoading(name LibraryName)

StartLoading marks a library as being loaded.

func (*MachineClosure) AcceptsArity ¶ added in v1.5.0

func (p *MachineClosure) AcceptsArity(n int) bool

AcceptsArity reports whether this closure can be called with n arguments. Fixed-arity closures require exactly paramCount args; variadic closures require at least paramCount-1 (the rest parameter collects the remainder).

func (*MachineClosure) Copy ¶

func (p *MachineClosure) Copy() *MachineClosure

func (*MachineClosure) Env ¶ added in v1.5.0

func (p *MachineClosure) Env() *environment.EnvironmentFrame

Env returns the closure's captured environment.

func (*MachineClosure) EqualTo ¶

func (p *MachineClosure) EqualTo(o values.Value) bool

func (*MachineClosure) IsVoid ¶

func (p *MachineClosure) IsVoid() bool

func (*MachineClosure) SchemeString ¶

func (p *MachineClosure) SchemeString() string

func (*MachineClosure) Template ¶

func (p *MachineClosure) Template() *NativeTemplate

func (*MachineContext) Apply ¶

func (p *MachineContext) Apply(mcls *MachineClosure, vs ...values.Value) (*MachineContext, error)

func (*MachineContext) ApplyCallable ¶ added in v1.2.0

func (p *MachineContext) ApplyCallable(callable values.Value, args ...values.Value) (*MachineContext, error)

ApplyCallable dispatches a procedure call to the appropriate handler based on the callee's concrete type. This is the unified entry point for all Scheme procedure application, symmetric with OperationApply.

Supported callable types:

• *MachineClosure: standard Scheme lambda
• *ForeignClosure: Go foreign function (direct call, no bytecode)
• *CaseLambdaClosure: R7RS case-lambda (§4.2.9)
• *Parameter: R7RS parameter object (§4.2.6)
• *ComposableContinuation: delimited continuation

Precondition: p.ctx must be set (always true for contexts created via NewMachineContext or NewSubContext).

func (*MachineContext) ApplyCaseLambda ¶

func (p *MachineContext) ApplyCaseLambda(clcls *CaseLambdaClosure, vs ...values.Value) (*MachineContext, error)

ApplyCaseLambda applies a case-lambda closure by finding the matching clause.

func (*MachineContext) Arg ¶

func (p *MachineContext) Arg(index int) values.Value

func (*MachineContext) Authorizer ¶ added in v1.7.0

func (p *MachineContext) Authorizer() security.Authorizer

Authorizer returns the security authorizer from this context's namespace, or nil if none is set.

func (*MachineContext) BarrierValid ¶ added in v1.4.0

func (p *MachineContext) BarrierValid() *BarrierToken

BarrierValid returns the barrier validity flag for the current context. Non-nil means execution is inside a with-continuation-barrier; the pointer identity distinguishes which barrier. Nil means no active barrier.

Escape closures and composable continuations use this to detect barrier crossings: if the capture-time pointer differs from the invocation-time pointer, the continuation would cross a barrier boundary.

func (*MachineContext) CallDepth ¶

func (p *MachineContext) CallDepth() int

CallDepth returns the depth of the current continuation stack.

func (*MachineContext) CaptureStackTrace ¶

func (p *MachineContext) CaptureStackTrace(maxDepth int) StackTrace

CaptureStackTrace walks the continuation chain and builds a stack trace.

func (*MachineContext) CaptureSubContextParams ¶ added in v1.3.0

func (p *MachineContext) CaptureSubContextParams() SubContextParams

CaptureSubContextParams extracts the state needed to create a sub-context in a different goroutine. This is used by thread creation to avoid race conditions when accessing the parent MachineContext from a child goroutine (T4 from architectural review).

Call this in the parent goroutine before creating the child goroutine, then pass the result to NewThreadSubContext in the child goroutine.

func (*MachineContext) CollectContinuationMarks ¶ added in v1.7.0

func (p *MachineContext) CollectContinuationMarks(tag *PromptTag) *ContinuationMarkSet

CollectContinuationMarks walks the continuation chain and builds a ContinuationMarkSet snapshot. Collects marks from the current frame and all continuation frames up to and including the nearest frame with a matching promptTag.

func (*MachineContext) Context ¶

func (p *MachineContext) Context() context.Context

Context returns the context for this machine context.

func (*MachineContext) Counters ¶ added in v1.1.0

func (p *MachineContext) Counters() VMCounters

Counters returns a snapshot of the performance counters for this context.

func (*MachineContext) CurrentContinuation ¶

func (p *MachineContext) CurrentContinuation() *MachineContinuation

func (*MachineContext) CurrentSource ¶

func (p *MachineContext) CurrentSource() *syntax.SourceContext

CurrentSource returns the source location for the current execution point. When the current template has no source (e.g., inside a foreign function), walks up the continuation chain to find the nearest call site with source info. Continuation PCs are return addresses (one past the call), so pc-1 gives the call site.

func (*MachineContext) Debugger ¶

func (p *MachineContext) Debugger() *Debugger

Debugger returns the attached debugger, or nil if none.

func (*MachineContext) DeleteMark ¶ added in v1.7.0

func (p *MachineContext) DeleteMark(key values.Value)

DeleteMark removes the continuation mark for key from the current frame. Nils the slice when empty to maintain the "nil = zero-cost" invariant. Uses eq? semantics for key comparison. Deletion uses swap-with-last for O(1) removal; insertion order is not preserved.

func (*MachineContext) EnvironmentFrame ¶

func (p *MachineContext) EnvironmentFrame() *environment.EnvironmentFrame

func (*MachineContext) Error ¶

func (p *MachineContext) Error(msg string) *SchemeError

Error creates a SchemeError with the current source location and stack trace.

func (*MachineContext) EscapeCont ¶

func (p *MachineContext) EscapeCont() *MachineContinuation

EscapeCont returns the escape continuation for this context. This is set by foreign functions (like dynamic-wind) that need call/cc inside their sub-contexts to know where to continue after completion.

func (*MachineContext) ExceptionHandler ¶

func (p *MachineContext) ExceptionHandler() *ExceptionHandler

ExceptionHandler returns the current exception handler chain.

func (*MachineContext) ExpanderContext ¶

func (p *MachineContext) ExpanderContext() *ExpanderContext

ExpanderContext returns the expander context, or nil if not in expansion context.

func (*MachineContext) FindPrompt ¶

func (p *MachineContext) FindPrompt(tag *PromptTag) (*MachineContinuation, bool)

FindPrompt walks the continuation chain to find the nearest frame with a matching prompt tag. Also checks the context's own prompt tag (set by call-with-continuation-prompt on sub-contexts). Returns the matching frame and true, or nil and false.

When the prompt is on the context itself (not a continuation frame), returns nil and true — the caller should treat this as "prompt at the boundary of this sub-context" and slice the entire continuation chain.

func (*MachineContext) GetImmediateMark ¶ added in v1.7.0

func (p *MachineContext) GetImmediateMark(key values.Value) values.Value

GetImmediateMark returns the nearest mark for key, checking the current frame first, then the immediately saved continuation frame.

This is the correct lookup for call-with-immediate-continuation-mark: in tail position, with-continuation-mark sets the mark on the live frame (mc.marks); in non-tail position, SaveContinuation moves mc.marks to mc.cont and nils the live frame. Both cases are handled here.

func (*MachineContext) GetMark ¶ added in v1.7.0

func (p *MachineContext) GetMark(key values.Value) values.Value

GetMark returns the continuation mark for key on the current frame, or nil if no mark is set. Uses eq? semantics for key comparison. Invariant: nil is used exclusively as the "not found" sentinel. Mark values are always non-nil Scheme values (GetValue never returns nil); SetMark must never be called with a nil val, as nil would be indistinguishable from absent.

func (*MachineContext) GetValue ¶

func (p *MachineContext) GetValue() values.Value

GetValue returns the first (or only) value from the value register. Returns Void if the register is empty.

func (*MachineContext) GetValues ¶

func (p *MachineContext) GetValues() MultipleValues

GetValues returns all values from the value register as a MultipleValues slice. For the single-value case this allocates a one-element slice; callers on the hot path should use GetValue instead.

func (*MachineContext) MaxCallDepth ¶ added in v1.3.0

func (p *MachineContext) MaxCallDepth() uint64

MaxCallDepth returns the maximum call depth limit. 0 means unlimited.

func (*MachineContext) NewSubContext ¶

func (p *MachineContext) NewSubContext() *MachineContext

NewSubContext creates a new MachineContext for running sub-calls (e.g., apply, map, for-each). The sub-context shares the global environment but has a fresh call stack, eval stack, and value register. This allows foreign functions to call Scheme closures without corrupting the parent context's state.

Note: Sub-contexts have isolated continuation chains (cont = nil). When call/cc captures a continuation inside a sub-context, it captures mc.Parent() which refers to the sub-context's chain (nil). For continuations to escape back to the outer context, the escape error propagates up through the call stack and is handled by RunWithEscapeHandling at the top level.

The parentMC field tracks the parent context, allowing call/cc to find an outer continuation for proper R7RS continuation semantics when captured inside sub-contexts.

The escapeCont field is inherited, allowing nested sub-contexts to know where execution should continue after their completion (set by dynamic-wind and similar constructs).

func (*MachineContext) PC ¶

func (p *MachineContext) PC() int

func (*MachineContext) Parent ¶

func (p *MachineContext) Parent() *MachineContinuation

func (*MachineContext) ParentMC ¶

func (p *MachineContext) ParentMC() *MachineContext

ParentMC returns the parent machine context (for sub-contexts), or nil for top-level contexts.

func (*MachineContext) PopContinuation ¶

func (p *MachineContext) PopContinuation() (*MachineContinuation, error)

PopContinuation pops the current continuation from the machine context and returns it. It restores the machine context to the state saved in the popped continuation. Returns ErrContinuationUnderflow if callDepth would go below zero (compiler bug).

Note: Unlike Restore(), we do NOT copy evals here because PopContinuation is used for normal function return where the continuation is consumed once. Restore() is used for continuation re-entry (call/cc) where the same continuation may be invoked multiple times, requiring the copy to prevent stack corruption.

func (*MachineContext) PopExceptionHandler ¶

func (p *MachineContext) PopExceptionHandler() *ExceptionHandler

PopExceptionHandler pops the current exception handler from the stack and returns it. Returns nil if no handler is installed.

func (*MachineContext) PopWindingFrame ¶

func (p *MachineContext) PopWindingFrame() *DynamicWindFrame

PopWindingFrame removes the innermost frame from the winding stack.

func (*MachineContext) PromptTag ¶

func (p *MachineContext) PromptTag() *PromptTag

PromptTag returns the prompt tag for this context, or nil.

func (*MachineContext) PushExceptionHandler ¶

func (p *MachineContext) PushExceptionHandler(handler values.Callable)

PushExceptionHandler pushes a new exception handler onto the handler stack.

func (*MachineContext) PushWindingFrame ¶

func (p *MachineContext) PushWindingFrame(frame *DynamicWindFrame)

PushWindingFrame adds a frame to the winding stack.

func (*MachineContext) ResolveParameterValue ¶ added in v1.7.0

func (p *MachineContext) ResolveParameterValue(param *Parameter) values.Value

ResolveParameterValue returns the effective value of a parameter, checking continuation marks (from parameterize) before falling back to the base value. This is the Go-side equivalent of calling the parameter with 0 args.

func (*MachineContext) Restore ¶

func (p *MachineContext) Restore(cont *MachineContinuation)

func (*MachineContext) RestoreAndRelease ¶ added in v1.4.0

func (p *MachineContext) RestoreAndRelease(cont *MachineContinuation)

RestoreAndRelease is the fast path for normal function return. It transfers the continuation's state into the MachineContext (like Restore) but avoids copying evals — instead it transfers ownership directly and pools the consumed frame. This is safe because normal return consumes the frame exactly once; call/cc and escape paths must use Restore (which copies).

Shared frames (marked by MarkChainShared during call/cc capture) cannot be pooled because a captured continuation may re-invoke them. For shared frames, evals are copied (like Restore) and the frame is left for GC instead of pooling.

The sequence for unshared frames:

1. Release mc's current evals to the stack pool (it's dead after restore)
2. Transfer cont's evals directly to mc (no copy)
3. Nil cont.evals so releaseContinuation won't double-release it
4. Pool the consumed continuation frame

func (*MachineContext) RestoreWithWinding ¶

func (p *MachineContext) RestoreWithWinding(cont *MachineContinuation, targetStack WindingStack) error

RestoreWithWinding restores a continuation with proper dynamic-wind handling. It unwinds from the current dynamic extent, rewinds to the target extent, then restores the machine state.

If cont is nil (continuation captured in a sub-context), we still perform the winding operations but don't restore machine state - the caller should handle continued execution appropriately.

func (*MachineContext) RestoreWithWindingFrom ¶

func (p *MachineContext) RestoreWithWindingFrom(cont *MachineContinuation, sourceStack, targetStack WindingStack) error

RestoreWithWindingFrom restores a continuation with proper dynamic-wind handling, using an explicit source winding stack instead of the current context's stack.

This is needed when the escape originated from a sub-context that has a different winding stack than the context where RestoreWithWinding is called. For example, when call/cc captures inside a sub-context and the escape propagates up, the source winding stack (where the escape happened) may have frames that the top-level context doesn't know about.

Parameters:

• cont: The continuation to restore to
• sourceStack: The winding stack where the escape originated (for unwinding)
• targetStack: The winding stack to restore to (for rewinding)

func (*MachineContext) RewindTo ¶

func (p *MachineContext) RewindTo(target WindingStack, commonDepth int) error

RewindTo runs before thunks from common ancestor to target depth. Returns error if any before thunk fails.

func (*MachineContext) Run ¶

func (p *MachineContext) Run() error

Run executes the VM loop starting from the current pc. The pc is NOT reset here - callers are responsible for ensuring the correct initial pc:

• NewMachineContext copies pc from the continuation (typically 0 for fresh execution)
• Apply sets pc = 0 for fresh closure invocation
• Restore sets pc from the saved continuation for resumption

This design allows continuation resumption (e.g., raise-continuable) to work correctly by preserving the pc set by Restore rather than unconditionally resetting to 0.

Dispatch: Run always uses switch-dispatch over integer opcodes.

Context cancellation: The loop checks p.ctx.Done() every 1024 ops, allowing preemption via context.WithTimeout or context.WithCancel. This enables:

• Test timeouts that actually stop execution
• REPL interrupt support (Ctrl+C)
• Resource management for long-running computations

Run executes the VM loop using switch-dispatch with integer opcodes. Hot-path operations (Wave 1-3) are inlined as switch cases; complex operations (closures, macros, FFI) are dispatched via OpComplex to the template's sideTable.

Set the context via SetContext() before calling Run().

func (*MachineContext) RunWithEscapeHandling ¶

func (p *MachineContext) RunWithEscapeHandling() error

RunWithEscapeHandling runs the VM loop, handling continuation escapes that weren't caught by an enclosing call/cc. This is used at the top level (REPL and file execution) to catch continuations invoked outside their original dynamic extent.

When a continuation captured inside a foreign function (like dynamic-wind's thunk) is invoked from outside, the escape error propagates up. This method catches it and restores the continuation with proper dynamic-wind handling.

For continuations captured inside sub-contexts (like dynamic-wind thunks):

• Continuation: the inner state (inside the thunk)
• EscapeCont: the outer continuation (after the original sub-context would have completed)

After the inner execution completes and unwinds, if there's a pending escape continuation, execution continues from there.

When execution completes normally (Run returns nil), any remaining frames on the winding stack are unwound (after thunks are called).

func (*MachineContext) SaveContinuation ¶

func (p *MachineContext) SaveContinuation(off int) error

SaveContinuation pushes a new continuation onto the machine context with the given offset to the current program counter. Returns ErrCallDepthExceeded if the call depth limit has been reached.

Note: callDepth is incremented BEFORE calling NewMachineContinuationFromMachineContext. The continuation's own callDepth is derived from mc.cont (the parent pointer), not from mc.callDepth, so this pre-increment does not affect the continuation's cached depth. See the comment on NewMachineContinuationFromMachineContext for why this matters.

func (*MachineContext) SetBarrierValid ¶ added in v1.4.0

func (p *MachineContext) SetBarrierValid(v *BarrierToken)

SetBarrierValid sets the barrier identity token on this context. Called by PrimCallWithContinuationBarrier to mark the sub-context as inside a barrier.

func (*MachineContext) SetContext ¶

func (p *MachineContext) SetContext(ctx context.Context)

SetContext sets the context for this machine context. This should be called before Run() to enable context cancellation/timeout.

func (*MachineContext) SetDebugger ¶

func (p *MachineContext) SetDebugger(d *Debugger)

SetDebugger attaches a debugger to this context.

func (*MachineContext) SetEscapeCont ¶

func (p *MachineContext) SetEscapeCont(cont *MachineContinuation)

SetEscapeCont sets the escape continuation for this context.

func (*MachineContext) SetExceptionHandler ¶

func (p *MachineContext) SetExceptionHandler(h *ExceptionHandler)

SetExceptionHandler sets the exception handler chain.

func (*MachineContext) SetExpanderContext ¶

func (p *MachineContext) SetExpanderContext(ctx *ExpanderContext)

SetExpanderContext sets the expander context for this machine context. This is called when invoking macro transformers to enable syntax-local-* primitives.

func (*MachineContext) SetMark ¶ added in v1.7.0

func (p *MachineContext) SetMark(key, val values.Value)

SetMark sets a continuation mark on the current frame using eq? semantics. Updates an existing entry with the same key, or appends a new one.

func (*MachineContext) SetMaxCallDepth ¶ added in v1.3.0

func (p *MachineContext) SetMaxCallDepth(n uint64)

SetMaxCallDepth sets the maximum call depth limit. 0 means unlimited.

func (*MachineContext) SetPC ¶

func (p *MachineContext) SetPC(v int)

SetPC sets the program counter. Used by PrimCallCC for inline lambda execution.

func (*MachineContext) SetPromptTag ¶

func (p *MachineContext) SetPromptTag(tag *PromptTag)

SetPromptTag sets the prompt tag on this context. Used by call-with-continuation-prompt to mark sub-contexts as prompt boundaries.

func (*MachineContext) SetThread ¶ added in v1.1.0

func (p *MachineContext) SetThread(t *values.Thread)

SetThread sets the SRFI-18 thread identity on this context. Both the thread object and its ID are stored for efficient comparison.

func (*MachineContext) SetValue ¶

func (p *MachineContext) SetValue(v values.Value)

SetValue stores a single value in the value register without allocating. This is the hot path: every LoadLocal, LoadGlobal, LoadLiteral, Pull, Pop, MakeClosure, etc. goes through here.

func (*MachineContext) SetValues ¶

func (p *MachineContext) SetValues(vs ...values.Value)

SetValues sets the value register. For a single value this uses the zero-allocation fast path (singleValue); for multiple values it falls back to the multiValues slice.

func (*MachineContext) SetWindingStack ¶

func (p *MachineContext) SetWindingStack(stack WindingStack)

SetWindingStack sets the winding stack (used by sub-contexts).

func (*MachineContext) SliceContinuationAt ¶

func (p *MachineContext) SliceContinuationAt(prompt *MachineContinuation) *MachineContinuation

SliceContinuationAt deep-copies the continuation chain segment from p.cont down to (but not including) the prompt frame. The returned chain's bottom frame has parent = nil, making it a standalone segment suitable for composable continuation capture.

func (*MachineContext) Template ¶

func (p *MachineContext) Template() *NativeTemplate

func (*MachineContext) Thread ¶ added in v1.1.0

func (p *MachineContext) Thread() *values.Thread

Thread returns the SRFI-18 thread object for this context, or nil for the primordial thread.

func (*MachineContext) ThreadID ¶ added in v1.1.0

func (p *MachineContext) ThreadID() uint64

ThreadID returns the SRFI-18 thread ID for this context. 0 means the primordial thread (main goroutine).

func (*MachineContext) UnwindTo ¶

func (p *MachineContext) UnwindTo(commonDepth int) error

UnwindTo runs after thunks from innermost to the common ancestor. Returns error if any after thunk fails.

func (*MachineContext) WindingStack ¶

func (p *MachineContext) WindingStack() WindingStack

WindingStack returns the current winding stack.

func (*MachineContext) WrapError ¶

func (p *MachineContext) WrapError(err error, msg string) *SchemeError

WrapError wraps an existing error with the current source location and stack trace.

func (*MachineContinuation) CallDepth ¶

func (p *MachineContinuation) CallDepth() int

CallDepth returns the depth of the continuation stack. The depth is cached in each frame at creation time, so this is O(1).

func (*MachineContinuation) Copy ¶

func (p *MachineContinuation) Copy() *MachineContinuation

func (*MachineContinuation) DeepCopy ¶

func (p *MachineContinuation) DeepCopy() *MachineContinuation

DeepCopy creates a deep copy of the entire continuation chain. Each frame in the chain is copied, with parent pointers updated to point to the copied frames. This is needed for composable continuations which must be safely re-invoked multiple times.

func (*MachineContinuation) EnvironmentFrame ¶

func (p *MachineContinuation) EnvironmentFrame() *environment.EnvironmentFrame

func (*MachineContinuation) EqualTo ¶

func (p *MachineContinuation) EqualTo(o values.Value) bool

func (*MachineContinuation) IsVoid ¶

func (p *MachineContinuation) IsVoid() bool

func (*MachineContinuation) MarkChainShared ¶ added in v1.4.0

func (p *MachineContinuation) MarkChainShared()

MarkChainShared marks every frame in the continuation chain as shared. Shared frames are not pooled by RestoreAndRelease — their evals are copied instead of transferred, preserving them for re-invocation.

Early-exits when a frame is already shared: all ancestors must already be shared from a prior capture (sharing propagates toward the root).

func (*MachineContinuation) PC ¶

func (p *MachineContinuation) PC() int

func (*MachineContinuation) Parent ¶

func (p *MachineContinuation) Parent() *MachineContinuation

func (*MachineContinuation) PromptHandler ¶

func (p *MachineContinuation) PromptHandler() Closure

func (*MachineContinuation) PromptTag ¶

func (p *MachineContinuation) PromptTag() *PromptTag

func (*MachineContinuation) PushValues ¶

func (p *MachineContinuation) PushValues(v ...values.Value)

PushValues appends values to the continuation's value register. If the register currently holds a single value, it is promoted to the multi-value representation before appending. This promote-then-append pattern avoids losing the existing single value when transitioning to the multi-value path.

func (*MachineContinuation) SchemeString ¶

func (p *MachineContinuation) SchemeString() string

func (*MachineContinuation) SetPC ¶

func (p *MachineContinuation) SetPC(v int)

func (*MachineContinuation) SetPromptHandler ¶

func (p *MachineContinuation) SetPromptHandler(h Closure)

func (*MachineContinuation) SetPromptTag ¶

func (p *MachineContinuation) SetPromptTag(t *PromptTag)

func (*MachineContinuation) Template ¶

func (p *MachineContinuation) Template() *NativeTemplate

func (*MachineContinuation) ThreadID ¶ added in v1.1.0

func (p *MachineContinuation) ThreadID() uint64

func (MultipleValues) Copy ¶

func (p MultipleValues) Copy() MultipleValues

Copy creates a copy of the MultipleValues.

func (MultipleValues) EqualTo ¶

func (p MultipleValues) EqualTo(o values.Value) bool

EqualTo checks if the MultipleValues is equal to another value.

func (MultipleValues) IsVoid ¶

func (p MultipleValues) IsVoid() bool

IsVoid returns true if the MultipleValues represents 'void' - either

func (MultipleValues) Len ¶

func (p MultipleValues) Len() int

Len returns the number of values in the MultipleValues.

func (MultipleValues) SchemeString ¶

func (p MultipleValues) SchemeString() string

SchemeString returns the Scheme representation of the MultipleValues.

func (*NativeTemplate) AppendCachedBinding ¶ added in v1.5.0

func (p *NativeTemplate) AppendCachedBinding(bd *environment.Binding) int32

AppendCachedBinding adds a *Binding to the cached bindings array, deduplicating by pointer identity. Returns the index for use as an OpLoadCachedBinding/OpPushCachedBinding operand.

func (*NativeTemplate) AppendInstruction ¶ added in v1.4.0

func (p *NativeTemplate) AppendInstruction(instr Instruction)

AppendInstruction appends a single instruction with no source attribution.

func (*NativeTemplate) AppendInstructionWithSource ¶ added in v1.4.0

func (p *NativeTemplate) AppendInstructionWithSource(src *syntax.SourceContext, instr Instruction)

AppendInstructionWithSource appends a single instruction to the integer-dispatch bytecode and tags it with the given source context.

func (*NativeTemplate) AppendOperations ¶

func (p *NativeTemplate) AppendOperations(ops ...Operation)

AppendOperations appends operations with no source attribution (index 0 = nil). Converts operations to instructions using AppendOperationsWithSource.

func (*NativeTemplate) AppendOperationsWithSource ¶ added in v1.4.0

func (p *NativeTemplate) AppendOperationsWithSource(src *syntax.SourceContext, ops ...Operation)

AppendOperationsWithSource converts operations to instructions and tags each with the given source. Wave 1-3 operations become direct switch cases; complex operations go through the sideTable and are dispatched via OpComplex. This is a public method for test use.

func (*NativeTemplate) AppendSideTableOp ¶ added in v1.4.0

func (p *NativeTemplate) AppendSideTableOp(op InlinedOperation) Instruction

AppendSideTableOp adds a complex operation to the side table and returns an OpComplex instruction that references it.

func (*NativeTemplate) Code ¶ added in v1.4.0

func (p *NativeTemplate) Code() []Instruction

Code returns the integer-dispatch bytecode slice.

func (*NativeTemplate) CodeLen ¶ added in v1.4.0

func (p *NativeTemplate) CodeLen() int

CodeLen returns the current code[] length (number of instructions emitted).

func (*NativeTemplate) Copy ¶

func (p *NativeTemplate) Copy() *NativeTemplate

func (*NativeTemplate) DeduplicateLiteral ¶

func (p *NativeTemplate) DeduplicateLiteral(v values.Value) values.Value

DeduplicateLiteral deduplicates the given value using the template's literal pool. For composite values (pairs and vectors), all elements are deduplicated recursively. Returns the deduplicated value.

func (*NativeTemplate) Doc ¶ added in v1.10.3

func (p *NativeTemplate) Doc() string

func (*NativeTemplate) EqualTo ¶

func (p *NativeTemplate) EqualTo(o values.Value) bool

func (*NativeTemplate) IsVariadic ¶

func (p *NativeTemplate) IsVariadic() bool

func (*NativeTemplate) IsVoid ¶

func (p *NativeTemplate) IsVoid() bool

func (*NativeTemplate) Literals ¶ added in v1.5.0

func (p *NativeTemplate) Literals() MultipleValues

Literals returns the literals pool.

func (*NativeTemplate) MaybeAppendLiteral ¶

func (p *NativeTemplate) MaybeAppendLiteral(v values.Value) LiteralIndex

func (*NativeTemplate) Name ¶

func (p *NativeTemplate) Name() string

func (*NativeTemplate) Operations ¶

func (p *NativeTemplate) Operations() Operations

Operations reconstructs the operation sequence from the bytecode. Converts Instructions back to Operation values for compatibility with existing code that expects Operations (e.g., tests, EqualTo).

func (*NativeTemplate) Optimize ¶ added in v1.5.0

func (p *NativeTemplate) Optimize()

Optimize performs a peephole optimization pass on the template's bytecode. It removes dead instructions identified by pattern-matching rules, fixes branch offsets to account for removed instructions, and compacts the code and source reference arrays in parallel.

Superinstruction formation (Ertl & Gregg 2003). Fusing adjacent instructions reduces dispatch overhead in the Run() switch loop.

Fusions:
  Load* + Push  → Push*       (eliminates 1 dispatch)
  Pull + Apply  → PullApply   (eliminates 1 dispatch)
  SaveCont + PushCachedBinding ... PullApply
              → CallForeignCached  (eliminates ~5 dispatches)

Cost model: each fusion saves one (fetch opcode + switch branch).
  In switch-dispatch interpreters, dispatch dominates execution time.

Invariant: fusions must not change observable semantics. Branch
  offsets are recomputed after compaction.
Constrains: Run() must implement fused opcodes with identical
  semantics to the original sequence.
Constrained by: must preserve semantic equivalence of fused
  instruction sequences.

See BIBLIOGRAPHY.md "Superinstruction Formation".

After compacting its own code, Optimize recurses into any *NativeTemplate values in the literals pool (lambda closures compiled as sub-templates).

Idempotent: a second call finds nothing to remove.

func (*NativeTemplate) ParameterCount ¶

func (p *NativeTemplate) ParameterCount() int

func (*NativeTemplate) PatchInstructionArg ¶ added in v1.4.0

func (p *NativeTemplate) PatchInstructionArg(codeIdx int, arg int32)

PatchInstructionArg updates the Arg field of the instruction at code[codeIdx]. Used for patching branch offsets and continuation save offsets after the target PC is known.

func (*NativeTemplate) SchemeString ¶

func (p *NativeTemplate) SchemeString() string

func (*NativeTemplate) SetDoc ¶ added in v1.10.3

func (p *NativeTemplate) SetDoc(doc string)

func (*NativeTemplate) SetName ¶

func (p *NativeTemplate) SetName(name string)

func (*NativeTemplate) SideTable ¶ added in v1.4.0

func (p *NativeTemplate) SideTable() []InlinedOperation

SideTable returns the complex operations referenced by OpComplex instructions.

func (*NativeTemplate) SourceAt ¶

func (p *NativeTemplate) SourceAt(pc int) *syntax.SourceContext

SourceAt returns the source location for the operation at pc. Returns nil if pc is out of bounds or no source was recorded. O(1) lookup via the parallel sourceRefs array.

func (*NativeTemplate) ValueCount ¶

func (p *NativeTemplate) ValueCount() int

func (*OSFileResolver) EnumerateLibraries ¶ added in v1.10.3

func (p *OSFileResolver) EnumerateLibraries() ([]LibraryName, error)

EnumerateLibraries walks the OS filesystem to discover importable libraries. Walks library registry search paths, SCHEME_INCLUDE_PATH directories, and CWD, matching the same search order used by ResolveAndOpen.

Best-effort: non-existent directories are skipped gracefully, and unreadable subdirectories are skipped without failing the whole walk. Only the security authorizer can exclude individual files.

func (*OSFileResolver) ResolveAndOpen ¶ added in v1.6.0

func (p *OSFileResolver) ResolveAndOpen(ctx context.Context, path string) (fs.File, string, error)

func (OpCode) String ¶ added in v1.4.0

func (op OpCode) String() string

String returns the human-readable name of the opcode.

func (*OperationApply) EqualTo ¶

func (p *OperationApply) EqualTo(o values.Value) bool

EqualTo returns true if o is also an OperationApply (identity by type).

func (OperationBase) IsVoid ¶ added in v1.3.0

func (p OperationBase) IsVoid() bool

IsVoid returns false; operations are never void. Unlike other values.Value implementations, this does not handle nil receivers — operations are bytecode instructions constructed by the compiler and stored in NativeTemplate slices; they are never nil.

func (OperationBase) SchemeString ¶ added in v1.3.0

func (p OperationBase) SchemeString() string

SchemeString returns the Scheme representation of the operation.

func (OperationBase) String ¶ added in v1.3.0

func (p OperationBase) String() string

String returns the Go string representation of the operation.

func (*OperationBindPatternVars) Apply ¶

func (p *OperationBindPatternVars) Apply(mc *MachineContext) (*MachineContext, error)

func (*OperationBindPatternVars) EqualTo ¶

func (p *OperationBindPatternVars) EqualTo(other values.Value) bool

func (*OperationBranchOffsetImmediate) EqualTo ¶

func (p *OperationBranchOffsetImmediate) EqualTo(o values.Value) bool

func (*OperationBranchOffsetImmediate) SchemeString ¶

func (p *OperationBranchOffsetImmediate) SchemeString() string

SchemeString overrides OperationBase to include offset value.

func (*OperationBranchOnFalseValueOffsetImmediate) EqualTo ¶ added in v1.4.0

func (p *OperationBranchOnFalseValueOffsetImmediate) EqualTo(o values.Value) bool

func (*OperationBranchOnFalseValueOffsetImmediate) SchemeString ¶ added in v1.4.0

func (p *OperationBranchOnFalseValueOffsetImmediate) SchemeString() string

SchemeString overrides OperationBase to include offset value.

func (*OperationBuildSyntaxList) Apply ¶

func (p *OperationBuildSyntaxList) Apply(mc *MachineContext) (*MachineContext, error)

Apply implements the Operation interface.

func (*OperationBuildSyntaxList) EqualTo ¶

func (p *OperationBuildSyntaxList) EqualTo(other values.Value) bool

func (*OperationClearSyntaxCaseInput) Apply ¶

func (p *OperationClearSyntaxCaseInput) Apply(mc *MachineContext) (*MachineContext, error)

func (*OperationClearSyntaxCaseInput) EqualTo ¶

func (p *OperationClearSyntaxCaseInput) EqualTo(other values.Value) bool

func (*OperationDrop) EqualTo ¶

func (p *OperationDrop) EqualTo(o values.Value) bool

func (*OperationForeignFunctionCall) Apply ¶

func (p *OperationForeignFunctionCall) Apply(mc *MachineContext) (rmc *MachineContext, rerr error)

func (*OperationForeignFunctionCall) EqualTo ¶

func (p *OperationForeignFunctionCall) EqualTo(o values.Value) bool

func (*OperationLoadCachedBinding) EqualTo ¶ added in v1.5.0

func (p *OperationLoadCachedBinding) EqualTo(o values.Value) bool

EqualTo returns true if both operations have the same binding index.

func (*OperationLoadCachedBinding) SchemeString ¶ added in v1.5.0

func (p *OperationLoadCachedBinding) SchemeString() string

SchemeString returns the Scheme representation of the operation.