Struct Ctx 

pub struct Ctx { /* private fields */ }

The long-lived state of an evaluation, the equivalent of a JS realm: the unique-id source for closure identities, the builtin module cache, the environment free list, and the module loader — a resolver plus the cache of modules loaded through it (load).

A host creates one per program run, per Python realm object or per playground session, and passes &Ctx to every call. Imports are still resolved before evaluation, and loaded modules are Rc-held values. See docs/done/2026-10-02_elly-host.md.

Implementations

impl Ctx

pub fn new() -> Self

A context with a fresh id source and no module resolver, so every import fails.

pub fn with_resolver(resolver: Box<dyn ModuleResolver>) -> Self

A context whose imports are served by resolver.

impl Ctx

pub fn chunk(&self, id: ChunkId) -> Ref<'_, StaticChunk>

The chunk id of this realm.

Do not hold the reference across anything that may add a chunk: an evaluation, an application or a load.

pub fn to_sexp(&self, id: ChunkId) -> String

The s-expression of chunk id’s top module body, e.g. (app (name f) (name x)): what the parse goldens assert on.

pub fn to_json(&self, id: ChunkId) -> String

The tagged JSON of chunk id’s top module body, e.g. {"app":[{"name":"f"},{"name":"x"}]}: the playground’s AST view.

impl Ctx

pub fn parse(&self, src: &str) -> Result<ChunkId, Error>

Parse Elly source into a new chunk named __eval_N, resolving its names. Free variables cause ParseError::UnboundName.

pub fn parse_open(&self, src: &str) -> Result<ChunkId, Error>

Parse Elly source as an open term: a free name is bound into the root frame, as if given. Used by tooling and the parse golden suite; for evaluation, prefer parse.

pub fn parse_preluded( &self, src: &str, prelude: &[Text], ) -> Result<ChunkId, Error>

Parse Elly source resolved against a fixed outer frame (prelude): prelude[i] is index i of the root frame. Unknown names cause ParseError::UnboundName.

pub fn eval(&self, code: ChunkId) -> Result<Value, Raised>

Evaluate an expression chunk this realm parsed, in the empty environment.

impl Ctx

pub fn take_trace(&self, raised: &Raised) -> Trace

The trace of raised, which reached the top of an evaluation of this realm, taken out of the realm, and for a .no_match, what refuted which value.

pub fn report_raised( &self, raised: &Raised, trace: &Trace, doc: &dyn Fn(&DocSource, &str) -> DocText, style: ReportStyle, ) -> String

Reports raised, which reached the top with trace: an uncaught line, then what refuted which value and the calls it unwound through, each shown in style. doc gives the name and, if it has it, the text of a document, by its source and the name of its chunk; an anonymous document is known by the chunk’s.

impl Ctx

pub fn compile_module(&self, src: &str) -> Result<ChunkId, Error>

Compile Elly module source into a new chunk, whose top module is the module (see docs/done/2026-08-07_elly-modules-v0.md).

This is purely syntactic: bodies are resolved against the module’s members and imports are mapped to leading frame slots. No bodies are evaluated; instantiate makes an instance.

pub fn compile_module_framed( &self, src: &str, frame: &[Text], ) -> Result<ChunkId, Error>

Compile Elly module source against a frame of ordered names.

References to frame names resolve to de Bruijn locals. Lookup order: enclosing binders $\to$ imports $\to$ module items $\to$ frame. Module imports occupy the leading frame slots.

pub fn compile_module_named( &self, src: &str, frame: &[Text], name: Option<ModuleName>, ) -> Result<ChunkId, Error>

Same as compile_module_framed, but records the canonical source name used by __Mod.name and for instance deduplication. The chunk takes the name, or __module_N if there is none.

impl Ctx

pub fn load(&self, spec: &str) -> Result<Value, LoadError>

Loads a module and its import graph through this context’s resolver, returning the instance for spec. A module already in the cache is reused, so two loads that reach one module share its instance.

Without a resolver, every spec is LoadError::NotFound.

Loading is not re-entrant: nothing evaluates while a graph is instantiated, so no host callback can run a nested load.

pub fn load_source(&self, name: &str, src: &str) -> Result<Value, LoadError>

Loads a module from src under name, resolving its imports through this context’s resolver. The caller supplied the text, so it replaces whatever name held in the cache — the explicit reload.

pub fn instances(&self) -> Ref<'_, Instances>

The modules loaded so far, by canonical name.

impl Ctx

pub fn chunk_bases(&self) -> Vec<Loc>

Each chunk’s base in the realm’s offset space, in chunk order. Bases do not decrease; a chunk with no documents shares its base with the next.

pub fn ctx_span(&self, chunk: ChunkId, span: ChunkSpan) -> Option<CtxSpan>

Chunk chunk’s span span in the realm’s offset space.

pub fn node_span(&self, chunk: ChunkId, id: NodeId) -> Option<CtxSpan>

The span of node id of chunk chunk, if it was parsed.

pub fn pat_span(&self, chunk: ChunkId, id: PatId) -> Option<CtxSpan>

The span of pattern id of chunk chunk, if it was parsed.

pub fn lambda_span(&self, chunk: ChunkId, id: LambdaId) -> Option<CtxSpan>

The span of lambda id of chunk chunk, if it was parsed.

pub fn member_span( &self, chunk: ChunkId, m: ModId, index: u32, ) -> Option<CtxSpan>

The span of member index of module m of chunk chunk, if it was parsed (see StaticChunk::member_span).

pub fn locate(&self, at: Loc) -> Option<Location>

at resolved to a document and a line: the chunk is found by its base, the document and the line by the chunk’s tables. None for Loc::NONE or a position in no document.

impl Ctx

pub fn intern(&self, s: &str) -> Sym

The symbol spelled s in this realm, interning it on first use.

pub fn sym(&self, s: &str) -> Option<Sym>

The symbol spelled s, if this realm has one; interns nothing. For a host asking for a member by name: a name never interned names nothing.

pub fn text(&self, sym: Sym) -> Text

The text of sym, which must belong to this realm.

Trait Implementations

impl Default for Ctx

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Ctx

Frees the environment free list iteratively (see Ctx::free_cells).

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.