glisp / eval
eval
Classes
IO
Defined in: eval.ts:463
A computed effect awaiting execution. Created by special forms like def that mutate the env (or other side effects); a host runs them by calling .run(). The REPL forces top-level IO actions automatically; elsewhere they sit inert as (IO ())-typed values.
run returns the diagnostics produced by the effect itself (e.g. a name collision when binding) so the host can surface them.
Constructors
Constructor
new IO(
description,run):IO
Defined in: eval.ts:464
Parameters
| Parameter | Type |
|---|---|
description | string |
run | () => readonly Diagnostic[] |
Returns
Properties
| Property | Modifier | Type |
|---|---|---|
description | readonly | string |
run | readonly | () => readonly Diagnostic[] |
OverloadValue
Defined in: eval.ts:439
A multi-variant function value: a sequence of variants (typed host fns or Glisp closures) where the first one whose declared parameter types match the call’s argument types is chosen. Created by the overload special form. Dispatch walks the call’s args through infer + typeFits against each variant’s declared param types in order; the first match wins.
Constructors
Constructor
new OverloadValue(
variants):OverloadValue
Defined in: eval.ts:440
Parameters
| Parameter | Type |
|---|---|
variants | readonly (TypedHostFn | GlispClosure)[] |
Returns
Properties
| Property | Modifier | Type |
|---|---|---|
variants | readonly | readonly (TypedHostFn | GlispClosure)[] |
Interfaces
EvalResult
Defined in: eval.ts:38
What evaluate returns: the resolved JS value plus any diagnostics accumulated along the way. Evaluation never throws on user errors, so every reasonable host must check diagnostics after calling evaluate — value may be the spec-defined fallback (() or a type’s default) when something went wrong.
Properties
| Property | Modifier | Type |
|---|---|---|
diagnostics | readonly | readonly Diagnostic[] |
value | readonly | unknown |
GlispClosure()
Defined in: eval.ts:57
Glisp function value. Per host-api.md, a Glisp closure surfaced to JS is a callable JS function: invoking it forces evaluation in the closure’s captured env and returns the JS value.
The implementation is a regular JS function carrying brand-property marker __glispClosure, plus the function-literal AST and the env in which the literal was created. instanceof-style checks are not usable on a plain function, so dispatch goes through isGlispClosure.
GlispClosure(…
args):unknown
Defined in: eval.ts:58
Glisp function value. Per host-api.md, a Glisp closure surfaced to JS is a callable JS function: invoking it forces evaluation in the closure’s captured env and returns the JS value.
The implementation is a regular JS function carrying brand-property marker __glispClosure, plus the function-literal AST and the env in which the literal was created. instanceof-style checks are not usable on a plain function, so dispatch goes through isGlispClosure.
Parameters
| Parameter | Type |
|---|---|
…args | unknown[] |
Returns
unknown
Properties
| Property | Modifier | Type |
|---|---|---|
__glispClosure | readonly | true |
ast | readonly | FnAST |
capturedEnv | readonly | Env |
TypedHostFn()
Defined in: eval.ts:349
TypedHostFn(…
args):unknown
Defined in: eval.ts:350
Parameters
| Parameter | Type |
|---|---|
…args | unknown[] |
Returns
unknown
Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
__glispTypedFn | readonly | true | - |
paramNames? | readonly | readonly string[] | Optional parameter names. When set, callers may pass keyword arguments at the call site. When unset (the default), kwargs at the call site emit a diagnostic — there’s no way to route them. |
paramTypes | readonly | readonly TypeValue[] | - |
returnType | readonly | TypeValue | - |
variadicTail? | readonly | TypeValue | Optional element type for an open trailing variadic. When set, any positional arguments past paramTypes.length are cast through this type and forwarded as additional positional args. |
TypeValue
Defined in: eval.ts:171
Host-side representation of a Glisp type. fits is the runtime predicate (“is this JS value a member of the type?”), default is the value coerceTo (and the typed-slot fallback) substitutes when a value does not fit, and shape lets compatibility checks recurse through structured types (functions, enums, refinements, parametric IOs, etc.).
Construct one via makeType / makeFunctionType rather than literal object syntax so the brand and shape stay consistent.
Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
__glispType | readonly | true | - |
apply? | readonly | (typeArgs) => TypeValue | { error: string; } | Optional type-constructor hook. When set, (T arg ...) is dispatched here with the args evaluated as types, and the result is the parameterized TypeValue. Most types do not have this; for them, a (T v) call is rejected with a hint to use (@ T v). |
default | readonly | unknown | - |
fits | readonly | (v) => boolean | - |
shape | readonly | TypeShape | - |
typeName | readonly | string | - |
Type Aliases
TypeShape
TypeShape = {
kind:"primitive"; } | {kind:"function";paramTypes:ReadonlyArray<TypeValue>;returnType:TypeValue;variadicTail?:TypeValue; } | {kind:"enum";values:ReadonlySet<unknown>; } | {base:TypeValue;kind:"refine"; } | {kind:"io";payload:TypeValue; } | {element:TypeValue;kind:"vector"; } | {elements:ReadonlyArray<TypeValue>;kind:"tuple"; } | {fields:ReadonlyMap<string,TypeValue>;kind:"record";optional:ReadonlySet<string>; }
Defined in: eval.ts:141
Structural shape of a TypeValue — recorded so type-compatibility checks can compare two types’ insides rather than just their printed names.
kind: 'primitive' is the default for opaque base types built via makeType (number, string, top, etc.); compatibility there is by === identity. The other kinds expose the constituent types so a checker can recurse: function has paramTypes / returnType, enum has its value set, refine keeps a pointer to the base.
Variables
emptyEnv
constemptyEnv:Env=null
Defined in: eval.ts:879
The empty (root) environment. Pass this to evaluate when no bindings are in scope — typically for self-contained literal / arithmetic expressions in tests or doc examples.
Functions
coerceTo()
coerceTo(
t,v):unknown
Defined in: eval.ts:222
Coerce v through type t: return v itself if t.fits(v), otherwise the type’s default. Pure — never emits diagnostics. The caller is responsible for surfacing a type mismatch when relevant (see evalCoerce and callTypedHostFn).
Parameters
| Parameter | Type |
|---|---|
t | TypeValue |
v | unknown |
Returns
unknown
evaluate()
evaluate(
ast,env):EvalResult
Defined in: eval.ts:712
Evaluate ast against env. Never throws on user errors. Returns { value, diagnostics }: value is the evaluated JS value (or the spec-defined fallback when something fails — usually () or the relevant type’s default), and diagnostics collects every mismatch / lookup failure / arity error encountered along the way.
Hosts that want strict behavior should treat any non-empty diagnostics as a failure. Hosts that want best-effort rendering (an editor mid-edit) can keep using value and surface the diagnostics in a separate channel.
Parameters
| Parameter | Type |
|---|---|
ast | AST |
env | Env |
Returns
isGlispClosure()
isGlispClosure(
v):v is GlispClosure
Defined in: eval.ts:83
Parameters
| Parameter | Type |
|---|---|
v | unknown |
Returns
v is GlispClosure
isIO()
isIO(
v):v is IO
Defined in: eval.ts:471
Narrow unknown to IO.
Parameters
| Parameter | Type |
|---|---|
v | unknown |
Returns
v is IO
isOverload()
isOverload(
v):v is OverloadValue
Defined in: eval.ts:446
Narrow unknown to OverloadValue.
Parameters
| Parameter | Type |
|---|---|
v | unknown |
Returns
v is OverloadValue
isTypedHostFn()
isTypedHostFn(
v):v is TypedHostFn
Defined in: eval.ts:420
Parameters
| Parameter | Type |
|---|---|
v | unknown |
Returns
v is TypedHostFn
isTypeValue()
isTypeValue(
v):v is TypeValue
Defined in: eval.ts:212
Parameters
| Parameter | Type |
|---|---|
v | unknown |
Returns
v is TypeValue
lookupBareName()
lookupBareName(
name,env):BindingTarget|null
Defined in: eval.ts:907
Parameters
| Parameter | Type |
|---|---|
name | string |
env | Env |
Returns
BindingTarget | null
makeClosure()
makeClosure(
ast,capturedEnv):GlispClosure
Defined in: eval.ts:70
Wrap a function-literal AST + the env it was defined in as a callable JS function (a GlispClosure). Hosts usually receive closures from the evaluator; call makeClosure directly only when constructing function values to inject from the host side.
Parameters
| Parameter | Type |
|---|---|
ast | FnAST |
capturedEnv | Env |
Returns
makeFunctionType()
makeFunctionType(
paramTypes,returnType,options?):TypeValue
Defined in: eval.ts:233
Build a function-shaped TypeValue carrying its declared parameter and return types. The runtime fits predicate accepts any callable (a function-shaped TypeValue does not constrain runtime arity); structural compatibility against another function type goes through typeFits, which compares the recorded shapes.
Parameters
| Parameter | Type |
|---|---|
paramTypes | readonly TypeValue[] |
returnType | TypeValue |
options? | { paramNames?: readonly string[]; variadicTail?: TypeValue; } |
options.paramNames? | readonly string[] |
options.variadicTail? | TypeValue |
Returns
makeTopLevel()
makeTopLevel(
bindings):Env
Defined in: eval.ts:892
Build a fresh top-level environment from a { name: ast } record. Each binding is stored as an unevaluated AST + the new frame, so:
- bindings are evaluated lazily on first lookup,
- bindings may reference each other in any order (self-referential),
- and the standard memoization (see eval.md — Cycle detection) applies.
Use this to seed an env with host-provided values; for the standard Glisp prelude, see prelude.ts.
Parameters
| Parameter | Type |
|---|---|
bindings | Readonly<Record<string, AST>> |
Returns
makeType()
makeType(
name,fits,defaultValue,shape?):TypeValue
Defined in: eval.ts:197
Build a type value: a plain branded object carrying the type’s name, fits predicate, default, and structural shape.
Type values are not callable — (T v) is rejected by the evaluator with a hint to use (@ T v) instead. The cast machinery still exists internally (typed slots, default fallback for missing args) but goes through coerceTo, not through invocation.
Parameters
| Parameter | Type |
|---|---|
name | string |
fits | (v) => boolean |
defaultValue | unknown |
shape | TypeShape |
Returns
makeTypedFn()
makeTypedFn(
paramTypes,returnType,fn,paramNames?,variadicTail?):TypedHostFn
Defined in: eval.ts:385
Wrap a plain JS function with declared parameter and return types so the evaluator can cast each argument before the call (and fill missing ones with the parameter type’s default). This is what gives (+ "str") the expected 0 rather than "strundefined" — "str" doesn’t fit number, so the cast falls back to the default 0, and the missing second argument is filled the same way.
Pass paramNames to enable kwargs at call sites — names are matched positionally against paramTypes.
Pass variadicTail to make the last position open-ended (extra args are cast through the tail type and forwarded). Callers receive every cast arg — the wrapped JS function is responsible for any folding logic.
Spec: docs/spec/types.md — default fallback timing
Parameters
| Parameter | Type |
|---|---|
paramTypes | readonly TypeValue[] |
returnType | TypeValue |
fn | (…args) => unknown |
paramNames? | readonly string[] |
variadicTail? | TypeValue |
Returns
toAst()
toAst(
value,env):AST
Defined in: eval.ts:2014
Convert a runtime value to an AST handle that, when evaluated against the provided env, yields the same value (modulo marshaling).
Strategy:
- primitives → literal AST
- vector / record → recurse over elements / fields
- GlispClosure → its captured function-literal AST
- AST handle →
`expr(quasiquote wrap) - type value → bare symbol if env binds the name, else falls back to a sym with the type’s stored name
- typed host fn → bare symbol if env binds the name, else opaque literal
- other JS function → bare symbol if env binds the name, else opaque literal
Spec: docs/spec/host-api.md — g.toAst
Parameters
| Parameter | Type |
|---|---|
value | unknown |
env | Env |
Returns
typeFits()
typeFits(
actual,expected):boolean
Defined in: eval.ts:272
Structural compatibility check: does a value of type actual fit a slot declared as expected?
expectedbeing_(top) accepts anything.- Same TypeValue identity is compatible.
- Two function types are compatible iff their param/return shapes recursively are. Param matching is invariant for now — proper contravariance can come with type inference of higher-order calls.
- Otherwise, fall back to typeName equality (covers names that resolve to identical primitives across env rebuilds).
Parameters
| Parameter | Type |
|---|---|
actual | TypeValue |
expected | TypeValue |
Returns
boolean