elly_core/

load.rs

//! Resolves and instantiates a module's import graph.
//!
//! Imports are top-level declarations; the reachable module set is fixed by source.
//! The [`ModuleResolver`] provides a module's canonical name and source, which is then
//! compiled and instantiated into the importing module's frame. Instantiated modules
//! contain unevaluated bodies (see [`crate::instantiate`]).
//!
//! ## Loading Process
//!
//! Traversal is post-order depth-first; a module is instantiated only after its imports.
//! This ensures frames contain only finished values and enforces acyclicity.
//! Cycles are detected during traversal and reported as [`LoadError::Cycle`].
//!
//! Modules are deduplicated by canonical name. All specs resolving to the same name
//! share a single instance, ensuring consistent identity across the import graph.
//!
//! [`Instances`] maps names to instances. A [`Ctx`] holds one for its lifetime,
//! together with its resolver, so loads through [`Ctx::load`] share a cache. The
//! free functions [`load_module`] and [`load_module_source`] take both explicitly.

use alloc::string::String;
use alloc::vec::Vec;
use core::cell::Ref;

use crate::eval::{instantiate, Ctx};
use crate::module::{ModuleData, ModuleName};
use crate::{Error, Value};

/// A module's canonical name and source.
///
/// The name defines the module's identity; all specs resolving to one module must
/// return the same canonical name.
pub struct Resolved {
    /// Unique name for the module.
    pub name: String,
    /// Module source.
    pub source: String,
}

/// Host-provided module loader. Maps an import spec to its canonical name and source.
///
/// Because `elly-core` is `no_std`, file I/O is handled by the host via this trait.
pub trait ModuleResolver {
    fn resolve(&self, spec: &str) -> Option<Resolved>;
}

/// Map from canonical name to instantiated module.
///
/// Deduplicates the import graph within a single [`load_module`] and acts as the
/// cache a [`Ctx`] keeps across loads. Since a name fixes the frame and imports,
/// cached instances remain valid unless dropped.
#[derive(Debug, Default)]
pub struct Instances {
    entries: Vec<(ModuleName, Value)>,
}

impl Instances {
    /// Create an empty instance map.
    pub fn new() -> Instances {
        Instances {
            entries: Vec::new(),
        }
    }

    /// Get the instance for `name`.
    pub fn get(&self, name: &str) -> Option<&Value> {
        self.entries
            .iter()
            .find(|(n, _)| n.as_str() == name)
            .map(|(_, v)| v)
    }

    /// Insert or replace the instance for `name`.
    pub fn insert(&mut self, name: ModuleName, value: Value) {
        match self.entries.iter_mut().find(|(n, _)| *n == name) {
            Some(entry) => entry.1 = value,
            None => self.entries.push((name, value)),
        }
    }

    /// Number of modules in the map.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Whether the map is empty.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Canonical names in insertion order.
    pub fn names(&self) -> impl Iterator<Item = &ModuleName> {
        self.entries.iter().map(|(n, _)| n)
    }
}

/// Compile-time module loading errors.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LoadError {
    /// Spec could not be resolved.
    NotFound { spec: String },
    /// Import cycle detected; `path` is the closing chain of names.
    Cycle { path: Vec<ModuleName> },
    /// Module failed to compile.
    Compile { name: ModuleName, error: Error },
}

impl Ctx {
    /// 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(&self, spec: &str) -> Result<Value, LoadError> {
        let mut seen = self.instances.borrow_mut();
        load_module(spec, self.resolver(), self, &mut seen)
    }

    /// 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 load_source(&self, name: &str, src: &str) -> Result<Value, LoadError> {
        let mut seen = self.instances.borrow_mut();
        load_module_source(name, src, self.resolver(), self, &mut seen)
    }

    /// The modules loaded so far, by canonical name.
    pub fn instances(&self) -> Ref<'_, Instances> {
        self.instances.borrow()
    }

    fn resolver(&self) -> &dyn ModuleResolver {
        match &self.resolver {
            Some(resolver) => resolver.as_ref(),
            None => &NoResolver,
        }
    }
}

/// The resolver of a [`Ctx`] given none: nothing resolves.
struct NoResolver;

impl ModuleResolver for NoResolver {
    fn resolve(&self, _spec: &str) -> Option<Resolved> {
        None
    }
}

/// Loads a module and its import graph: resolves, compiles, and instantiates
/// modules leaves-first, returning the instance for `spec`.
///
/// `seen` deduplicates instances and may be used as a cache. `ctx` handles
/// item ID allocation.
pub fn load_module(
    spec: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
) -> Result<Value, LoadError> {
    let mut path = Vec::new();
    load_spec(spec, resolver, ctx, seen, &mut path)
}

/// Loads a module from provided source under `name`.
///
/// Ignores and replaces any existing instance of `name` in `seen`, allowing
/// explicit reloads.
pub fn load_module_source(
    name: &str,
    src: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
) -> Result<Value, LoadError> {
    let mut path = Vec::new();
    instantiate_source(ModuleName::from(name), src, resolver, ctx, seen, &mut path)
}

/// Resolves a spec to an instance, using `seen` for deduplication.
/// Detects cycles via `path`.
fn load_spec(
    spec: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
    path: &mut Vec<ModuleName>,
) -> Result<Value, LoadError> {
    let resolved = resolver.resolve(spec).ok_or_else(|| LoadError::NotFound {
        spec: String::from(spec),
    })?;
    let name = ModuleName::from(resolved.name.as_str());
    if let Some(instance) = seen.get(name.as_str()) {
        return Ok(instance.clone());
    }
    if path.contains(&name) {
        let mut cycle = path.clone();
        cycle.push(name);
        return Err(LoadError::Cycle { path: cycle });
    }
    instantiate_source(name, &resolved.source, resolver, ctx, seen, path)
}

/// Compiles source as `name`, loads imports, and instantiates the module.
///
/// Traversal is post-order; imports are loaded before the module is instantiated,
/// ensuring frame slots contain finished modules.
fn instantiate_source(
    name: ModuleName,
    src: &str,
    resolver: &dyn ModuleResolver,
    ctx: &Ctx,
    seen: &mut Instances,
    path: &mut Vec<ModuleName>,
) -> Result<Value, LoadError> {
    let data: alloc::rc::Rc<ModuleData> = crate::compile_module_named(src, &[], Some(name.clone()))
        .map_err(|error| LoadError::Compile {
            name: name.clone(),
            error,
        })?;
    path.push(name.clone());
    let mut frame: Vec<Value> = Vec::with_capacity(data.imports().len());
    for spec in data.imports() {
        frame.push(load_spec(spec.as_str(), resolver, ctx, seen, path)?);
    }
    path.pop();
    // The module was compiled against no host frame, so its slots are exactly its
    // imports and the arity check cannot fail.
    let instance =
        instantiate(data, &frame, ctx).expect("a module's frame is exactly its own imports");
    seen.insert(name, instance.clone());
    Ok(instance)
}