Crate elly_core 

Elly — a small language layered on Muon (see docs/elly-spec.md).

This crate implements a subset including references, application, & abstraction, symbols, and positional lists with projection. It uses the muon crate for syntax, parsing into an Expr which is then evaluated by a tree-walking evaluator.

let expr = elly_core::parse("(&x x) .foo").unwrap();
assert_eq!(elly_core::eval(&expr).unwrap().to_display(), ".foo");

Structs

Ctx

Evaluation context threaded through the tree-walker: includes the unique-id source for closure identities and the builtin module cache. It does not hold a module registry or loader; imports are resolved before evaluation (crate::load_module), and loaded modules are Rc-held values.

Env

A shared, persistent environment: a nameless cons list of the running activation’s bindings (innermost first) on top of the closure’s captured Frame. A resolved reference (Expr::Local) reaches its value by walking its de Bruijn index over next links and cloning the cell’s value — a pointer chase without name comparison or per-link cloning. Indices beyond the consed cells land in the frame array. The resolver (resolve.rs) assigns each reference the exact number of cells between it and its binder.

EnvRef

A shared reference to an EnvNode: every handle on a node — an Env link, a Value::Module, an iota’s or object’s prototype — goes through it.

HostFn

A host function: a native callback provided by the embedder, behind the Rc a Value::HostFn carries.

ImportDecl

One import declaration: the name the importing module reaches the instance by, and the spec its host resolver is handed.

Instances

Map from canonical name to instantiated module.

ModuleData

A loaded module containing an immutable, name-sorted table of unevaluated item bodies. Built by crate::compile_module and stored in an Rc. Sibling references are compiled to Expr::ModItem and resolved via the home module in the environment (crate::eval_env::EnvNode::Module), ensuring the value heap remains acyclic. See docs/done/2026-08-07_elly-modules-v0.md.

ObjectData

An object: a payload and the prototype that defines its type. A Value::Object is an Rc pointer to ObjectData.

Resolved

A module’s canonical name and source.

Enums

Builtin

A native builtin operation in the reserved __ namespace. All are curried.

EnvNode

One link of the environment list: a single binding carrying its val inline, or the frame that terminates the walk. The empty environment is None. Env is an Option<EnvRef>, utilizing the null-pointer niche to remain one word wide, avoiding allocation and refcount traffic when ending a chain. Lambda activations cons one Cons per bound name (zero for binder-less heads); partial application environments share the consed prefix via Rc. References are resolved to de Bruijn indices against this list’s shape.

Error

A failure at the syntax or parse stage.

Expr

An Elly expression for the initial subset. Strings and records are deferred per the spec.

HomeLeaf

Home-module leaf types: the module itself (Self), construction (#Self(…)), or payload read (x.Self). These share the same resolution machinery (one walk to the terminal) and differ only in their eval result.

LoadError

Compile-time module loading errors.

ParseError

A parse failure: the input is a valid Muon tree but not a well-formed Elly program in this subset.

Pattern

A pattern: the left-hand side of a binding (&<pat> …, let (<pat> = …), or a __match clause). Matched by the evaluator’s native matcher (match_pattern in eval.rs). Bind/Discard are irrefutable.

ProtoRef

Prototype used in as <Proto> patterns.

Raised

Value unwinding through the single error channel (see docs/elly-spec.md).

TyKind

Value kinds with builtin module prototypes, allowing as <Proto> to compile to a discriminant test (see ProtoRef::Kind).

Value

A runtime value.

Traits

ModuleResolver

Host-provided module loader. Maps an import spec to its canonical name and source.

Functions

apply

Apply a value to a single argument — the public entry point behind a host’s “call this value” surface (e.g. the Python bindings’ elly.Fun.__call__).

apply_with

Applies a value to a single argument using a caller-supplied Ctx. This ensures identities minted by the call continue the provided context’s ID source rather than restarting at zero. Required for hosts that manage callables across multiple apply calls to avoid ID collisions.

compile_module

Compile Elly module source into ModuleData.

compile_module_framed

Compile Elly module source against a frame of ordered names.

compile_module_named

Same as compile_module_framed, but records the canonical source name used by __Mod.name and for instance deduplication.

eval

Evaluate an expression in the empty environment.

eval_env

Evaluates an expression in a given environment and context. Public entry point for host evaluation (e.g., elly.Env.eval).

eval_main

Evaluates the __main body of a module instance in its own environment. Returns Ok(None) if no body is declared (e.g., a library).

instantiate

Instantiates a compiled module, creating its Module terminal and returning it as a Value::Module.

is_bindable_name

Whether name can be bound and referenced from source as a plain name.

load_module

Loads a module and its import graph: resolves, compiles, and instantiates modules leaves-first, returning the instance for spec.

load_module_source

Loads a module from provided source under name.

parse

Parse Elly source into an Expr with name resolution. Free variables cause ParseError::UnboundName.

parse_module

Parse a module source’s top-level sequence into its declarations.

parse_open

Parse Elly source into an Expr without resolution (open term). Used by tooling and the parse golden suite. For evaluation, prefer parse.

parse_preluded

Parse Elly source into an Expr resolved against a fixed outer frame (prelude). Unknown names cause ParseError::UnboundName.

parse_program

Parse a program (single top-level chain) to an expression.

resolve

Resolve a program against an empty scope; free names are rejected as ParseError::UnboundName. Rewrites expr in place (names → de Bruijn locals).

resolve_module_bodies

Resolve a module’s bodies in place. Item names are sorted to provide a stable index space for order-independent mutual recursion.

resolve_open

Resolve an open term: free names are auto-bound below the whole scope.

resolve_prelude

Resolve expr against a named outer prelude. References to prelude[i] become index i of the root frame.

Type Aliases

HostCall

The contract a host callback signs: a whole call’s arguments — exactly arity of them, since the evaluator gathers before it fires — plus the Ctx, answering a value or a Raised.

ImportSpec

What a module’s source writes to name an import — a path, a package-qualified name. Its grammar belongs to the host resolver, not to Elly.

ModuleName

What a resolver answers a spec with: one name per module, however many specs reach it. Module instances are deduplicated by this name, so a resolver that returns the spec unchanged would hand back two instances of one module for "./foo" and "foo" (see crate::load_module).

Text

An owned, cheap-clone text leaf using hipstr’s Local (Rc) backend. Short strings (≤ 23 bytes on 64-bit) are inlined; longer strings use a shared Rc<str> slice. This ensures Expr and Value are 'static and independent of the Muon source. Host tags are stored via [Text::from_static].