api

package
v1.13.0 Latest Latest
Warning

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

Go to latest
Published: Sep 20, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsIncomplete added in v1.13.0

func IsIncomplete(err error) bool

IsIncomplete reports whether err, as returned by Run, means the input ended in the middle of an open form (e.g. "(defn foo [x]") rather than being wrong. Interactive frontends use it to decide between reading more lines and reporting the error:

v, err := lg.Run(buffer)
if err != nil {
	if api.IsIncomplete(err) {
		continue // prompt for another line, re-Run the whole buffer
	}
	report(err)
}

Empty and whitespace-only input also read as incomplete, which a REPL loop treats the same way: keep prompting. A hard syntax error such as an unmatched delimiter ("(]") is not incomplete — more input can never complete it — and should be reported immediately.

Types

type LetGo

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

func NewLetGo

func NewLetGo(ns string, opts ...Option) (*LetGo, error)

NewLetGo constructs a runtime. With no options, behavior is exactly as it was pre-option: *out* and *err* keep their global default root bindings (os.Stdout / os.Stderr). Each I/O option installed gets pushed as a dynamic binding around each Run call, so different LetGo instances don't share or overwrite each other's I/O routing.

func (*LetGo) CompilerContext added in v1.13.0

func (l *LetGo) CompilerContext() *compiler.Context

CompilerContext returns the shared compiler context for host integrations such as nREPL servers that must evaluate in the embedded runtime's namespace.

func (*LetGo) Def

func (l *LetGo) Def(name string, value any) error

func (*LetGo) NS added in v1.13.0

func (l *LetGo) NS(name string) *NS

NS resolves the named namespace, creating it if it does not exist yet, and returns a registration handle for it. Typical embedder use is grouping host functions into their own namespaces at startup:

patch := lg.NS("music.patch")
patch.Def("oscillator", oscillatorFn)
patch.DefShadowing("filter", filterFn) // collides with clojure.core/filter

func (*LetGo) Run

func (l *LetGo) Run(expr string) (vm.Value, error)

Run compiles and evaluates expr. If this LetGo was constructed with WithStdout / WithStderr, the corresponding IOHandle is pushed as a dynamic binding on *out* / *err* for the eval's scope and popped on return (including on error / panic).

Two LetGo instances calling Run sequentially each get their own configured streams: A's Run pushes A's handle, evaluates, pops; then B's Run pushes B's handle. The root binding of *out*/*err* is never mutated.

func (*LetGo) SetLoadPath

func (l *LetGo) SetLoadPath(path []string)

type NS added in v1.13.0

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

NS is a handle for registering host values into one namespace. It is the namespace-targeted counterpart of LetGo.Def: same boxing, explicit destination. Obtain one from LetGo.NS.

func (*NS) Def added in v1.13.0

func (n *NS) Def(name string, value any) error

Def boxes value exactly as LetGo.Def does and defines it in this namespace. Defining a name that is referred in from clojure.core works (the local var wins) but emits the Clojure-parity shadow warning; use DefShadowing when the collision is intentional.

func (*NS) DefShadowing added in v1.13.0

func (n *NS) DefShadowing(name string, value any) error

DefShadowing defines name in this namespace, first excluding it from the clojure.core auto-refer — the programmatic equivalent of (:refer-clojure :exclude [name]). The definition is silent and unqualified references in the namespace resolve to it instead of the core var.

Boxing happens before any namespace mutation: if value is unboxable the namespace is left untouched, so a failed call is a true no-op rather than leaving name excluded-but-undefined (which would silently strip the unqualified clojure.core/<name> resolution).

type Option added in v1.11.0

type Option func(*config)

Option configures a LetGo runtime instance at construction. Options are applied in order; later options override earlier ones for the same configuration key.

func WithEmit added in v1.11.0

func WithEmit(fn func(name, dataJSON string)) Option

WithEmit configures the runtime to route (js/emit event-name data) through fn for this instance, the emit dual of WithStdout. fn receives the event name and the JSON-marshaled data — the same (name, dataJSON) pair the WASM bundle hands to LetGoHost.onEmit — so a Go embedder gets the events its guest dispatches without depending on the browser host.

Implementation: each Run pushes a FuncEmitter wrapping fn as a dynamic binding on *emit*, popped on return. Same per-Run isolation and process-global-binding-stack concurrency caveat as WithStdout.

Default: no-op (the *emit* root nopEmitter; (js/emit ...) is dropped).

func WithKeySource added in v1.11.0

func WithKeySource(ks rt.KeySource) Option

WithKeySource routes term/read-key and key-pending? through ks for this instance, the input dual of WithStdout. An embedder or test supplies the keystrokes the guest reads — driving a TUI without a real terminal, or feeding a deterministic script. ks is an rt.KeySource (ReadKey + KeyPending); see pkg/rt/keysource.go.

Implementation: each Run pushes ks as a dynamic binding on *keys*, popped on return. Same per-Run isolation and process-global-binding-stack concurrency caveat as WithStdout.

Default: the platform key source (stdin+SIGWINCH on native, the SAB in WASM). Wake — unblocking a parked read-key without a real key — is not part of this seam yet; see the note in pkg/rt/wasm/lg-host.js.

func WithStderr added in v1.11.0

func WithStderr(w io.Writer) Option

WithStderr configures the runtime to route output written via *err* (HTTP server error logs, pod stderr, panic reports, etc.) through w for this runtime instance. Same per-Run binding semantics as WithStdout; same concurrency caveat.

Default: os.Stderr.

func WithStdout added in v1.11.0

func WithStdout(w io.Writer) Option

WithStdout configures the runtime to route output written via *out* (i.e. (println ...), (print ...), (pr ...), (prn ...), and any user code that consults *out*) through w for this runtime instance.

Implementation: each Run call pushes an IOHandle wrapping w as a dynamic binding on *out*, then pops it on return. Per-Run scope means two LetGo instances with different WithStdout values DO NOT interfere with each other's sequential output capture, and a LetGo constructed without WithStdout sees the unaltered os.Stdout default regardless of what other instances have done.

Concurrency caveat: vm.Var's binding stack is process-global. If two goroutines call Run on different LetGo instances concurrently, their bindings push onto the same *out* stack — push/pop interleavings can scramble captures. For deterministic isolation, serialize Run calls or run different instances in different processes.

Default: os.Stdout (no binding pushed; runtime root unchanged).

func WithStorage added in v1.11.0

func WithStorage(store rt.Storage) Option

WithStorage routes the storage namespace through store for this instance. The store receives app-local logical keys; callers should not encode host filesystem or browser-origin details into those keys.

Implementation: each Run pushes store as a dynamic binding on *storage*, popped on return. Same process-global-binding-stack concurrency caveat as WithStdout.

Default: the runtime root binding. In ordinary native lg this is a file-backed store configured by the CLI; in bare embedders it is in-memory.

Error contract: a store must distinguish an absent key (storage/get yields nil) from a backend failure (throws in the guest) — see rt.Storage.

func WithSurface added in v1.13.0

func WithSurface(s rt.Surface) Option

WithSurface routes surface/present and surface/available? through s for this instance, the graphics dual of WithEmit. An embedder or test supplies a frame sink — capturing presented frames headlessly, or binding a native terminal-image encoder (RGBA -> PNG -> iTerm2 IIP, etc.). s is an rt.Surface (Present + Available); see pkg/rt/surface.go.

Implementation: each Run pushes s as a dynamic binding on *surface*, popped on return. Same process-global-binding-stack concurrency caveat as WithStdout.

Default: no-op (the *surface* root nopSurface; surface/present is dropped, surface/available? is false).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL