elly_core/

lib.rs

//! Elly — a small language layered on Muon (see `docs/elly-spec.md`).
//!
//! This crate implements the first, deliberately small subset: references,
//! application, `&` abstraction, symbols, and positional lists with
//! projection. It reads the syntax with the `muon` crate, parses that notation
//! tree into an [`Expr`], and evaluates it with a naive tree-walking
//! [`eval`](fn@eval)uator.
//!
//! ```
//! let expr = elly_core::parse("(&x x) .foo").unwrap();
//! assert_eq!(elly_core::eval(&expr).unwrap().to_display(), ".foo");
//! ```

#![no_std]

extern crate alloc;

mod ast;
mod eval;
mod load;
mod parse;
mod resolve;

pub use ast::{Expr, HomeLeaf, Pattern, ProtoRef, Text, TyKind};
pub use eval::{
    apply, apply_with, eval, eval_env, eval_main, instantiate, Builtin, Ctx, Env, EnvNode,
    HostCall, HostFn, ModuleData, ObjectData, Raised, Value,
};
pub use load::{load_module, load_module_source, Instances, LoadError, ModuleResolver, Resolved};
pub use parse::{
    is_bindable_name, parse_module, parse_program, ImportDecl, ImportSpec, ModuleName,
    ModuleSyntax, ParseError,
};
pub use resolve::{resolve, resolve_module_bodies, resolve_open, resolve_prelude};

use alloc::rc::Rc;
use alloc::vec::Vec;

// TODO: use thiserror?
// TODO: errors with spans
/// A failure at the syntax or parse stage.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Error {
    /// The syntax layer (Muon) rejected the input.
    Syntax(muon::ParseError),
    /// The input is a valid Muon tree but not a valid Elly program (this subset).
    Parse(ParseError),
}

/// Parse Elly source into an [`Expr`]: read the Muon syntax, parse that notation
/// tree into the AST, then resolve names — a free variable is rejected here (a
/// parse-time [`ParseError::UnboundName`]) rather than raising at eval.
pub fn parse(src: &str) -> Result<Expr, Error> {
    let mut expr = parse_open(src)?;
    resolve(&mut expr).map_err(Error::Parse)?;
    Ok(expr)
}

/// Parse Elly source into an [`Expr`] **without** name resolution, so free
/// variables are left in place (an *open* term). Used by tooling that wants the
/// raw AST and by the parse golden suite, which resolves open terms with
/// [`resolve_open`] (auto-binding their free names). Prefer [`parse`](fn@parse) for
/// evaluating a whole program.
pub fn parse_open(src: &str) -> Result<Expr, Error> {
    let seq = muon::parse(src).map_err(Error::Syntax)?;
    parse_program(&seq).map_err(Error::Parse)
}

/// Compile Elly **module** source into a frozen [`ModuleData`]: read the Muon
/// syntax, parse it into `import`s and `name = body` items ([`parse_module`]),
/// then resolve each body against the module's item set
/// ([`resolve_module_bodies`], turning sibling references into
/// [`Expr::ModItem`]). Compiling is purely syntactic — no body is evaluated, and
/// no import is resolved. See `docs/done/2026-08-07_elly-modules-v0.md`.
///
/// The module's imports become its leading frame slots, so source that imports
/// compiles fine here but has to be [instantiated](instantiate) against the
/// instances. Use [`load_module`] to compile and instantiate a whole import graph.
pub fn compile_module(src: &str) -> Result<Rc<ModuleData>, Error> {
    compile_module_framed(src, &[])
}

/// Compile Elly module source against a **frame**: an ordered list of names the
/// module is instantiated against — a host prelude, module-minted identities. A
/// body's reference to one resolves to a de Bruijn local whose index walks past
/// the module terminal into the frame, so it costs one indexed lookup and nothing
/// is evaluated on access.
///
/// A name in a body is looked for in the enclosing `&`/`let` binders, then the
/// module's imports, then its own items, then `frame`; a name in none of them is
/// [`ParseError::UnboundName`]. The module's **imports take the leading frame
/// slots**, so the returned [`ModuleData`]'s
/// [`frame_names`](ModuleData::frame_names) is its imports followed by `frame`,
/// and [`instantiate`] wants the import instances ahead of the values for `frame`.
/// [`ModuleData::imports`] says how many lead and what they were imported from;
/// [`load_module`] is what fills them.
///
/// [`compile_module`] is this with an empty frame.
pub fn compile_module_framed(src: &str, frame: &[Text]) -> Result<Rc<ModuleData>, Error> {
    compile_module_named(src, frame, None)
}

/// [`compile_module_framed`], recording `name` as the canonical name the code came
/// from — what `__Mod.name` reports and what [`load_module`] deduplicates
/// instances by. Only a host that resolved the source knows the name, which is why
/// the plain entry points leave it unset.
pub fn compile_module_named(
    src: &str,
    frame: &[Text],
    name: Option<ModuleName>,
) -> Result<Rc<ModuleData>, Error> {
    let seq = muon::parse(src).map_err(Error::Syntax)?;
    let syntax = parse_module(&seq).map_err(Error::Parse)?;
    let mut bindings = syntax.items;
    let mut locals = syntax.locals;
    let import_names: Vec<Text> = syntax.imports.iter().map(|i| i.name.clone()).collect();
    // The iota table is name-sorted, as the item and local tables are: the three
    // orders concatenated are the member index space a `ModItem` counts against.
    let mut iotas = syntax.iotas;
    iotas.sort_by(|a, b| a.as_str().cmp(b.as_str()));
    // `__main` is resolved with the item bodies and against the same tiers — it
    // is written in the module's own scope, so it reaches every member and every
    // frame slot. It takes no member index of its own (see `ModuleData::body`).
    let mut main = syntax.main;
    resolve_module_bodies(
        &mut bindings,
        &mut locals,
        main.as_mut(),
        &import_names,
        &iotas,
        frame,
    )
    .map_err(Error::Parse)?;
    let mut frame_names = import_names;
    frame_names.extend_from_slice(frame);
    Ok(Rc::new(ModuleData::from_bindings(
        bindings,
        locals,
        iotas.into_boxed_slice(),
        frame_names.into_boxed_slice(),
        syntax
            .imports
            .into_iter()
            .map(|i| i.spec)
            .collect::<Vec<_>>()
            .into_boxed_slice(),
        main,
        name,
    )))
}

/// Parse Elly source into an [`Expr`] resolved against a named `prelude`: names
/// in the prelude resolve to de Bruijn locals, unknown names are rejected with
/// [`ParseError::UnboundName`]. The prelude is an ordered slice of names
/// (insertion order) that forms a fixed outer frame below all lambda scopes.
/// Prefer [`parse`](fn@parse) for a whole program without a prelude.
pub fn parse_preluded(src: &str, prelude: &[Text]) -> Result<Expr, Error> {
    let mut expr = parse_open(src)?;
    resolve_prelude(&mut expr, prelude).map_err(Error::Parse)?;
    Ok(expr)
}