Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsIncomplete ¶ added in v1.13.0
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 ¶
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
CompilerContext returns the shared compiler context for host integrations such as nREPL servers that must evaluate in the embedded runtime's namespace.
func (*LetGo) NS ¶ added in v1.13.0
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 ¶
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 ¶
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
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
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
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
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
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
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
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
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).