cljrs_stdlib/

lib.rs

//! Built-in standard library namespaces for clojurust.
//!
//! Registers `clojure.string`, `clojure.set`, and `clojure.test` into a
//! [`GlobalEnv`] so they are available via `(require ...)` without needing
//! source files on disk.
//!
//! ## Entry points
//!
//! - [`standard_env()`] — full environment for the `cljrs` binary
//! - [`standard_env_with_paths()`] — same, plus user source paths
//! - [`register()`] — add stdlib to an existing env (e.g. for testing)

use std::sync::Arc;

use cljrs_eval::GlobalEnv;
#[cfg(not(target_arch = "wasm32"))]
use cljrs_gc::GcConfig;

mod core_async;
// io and edn use std::fs which is not available on wasm32-unknown-unknown
#[cfg(not(target_arch = "wasm32"))]
mod edn;
#[cfg(not(target_arch = "wasm32"))]
pub mod io;
mod set;
mod string;
// ── Embedded sources ──────────────────────────────────────────────────────────

const CLOJURE_TEST_SRC: &str = include_str!("clojure/test.cljrs");
const CLOJURE_STRING_SRC: &str = include_str!("clojure/string.cljrs");
const CLOJURE_SET_SRC: &str = include_str!("clojure/set.cljrs");
const CLOJURE_TEMPLATE_SRC: &str = include_str!("clojure/template.cljrs");
#[cfg(not(target_arch = "wasm32"))]
const CLOJURE_RUST_IO_SRC: &str = include_str!("clojure/rust/io.cljrs");
#[cfg(not(target_arch = "wasm32"))]
const CLOJURE_EDN_SRC: &str = include_str!("clojure/edn.cljrs");
const CLOJURE_WALK_SRC: &str = include_str!("clojure/walk.cljrs");
const CLOJURE_DATA_SRC: &str = include_str!("clojure/data.cljrs");
const COLJURE_ZIP_SRC: &str = include_str!("clojure/zip.cljrs");

// ── Macro: register a batch of native fns into a namespace ───────────────────

/// Register a slice of `(name, arity, fn)` triples as `NativeFunction` values
/// in `$globals` under namespace `$ns`.
macro_rules! register_fns {
    ($globals:expr, $ns:expr, [ $( ($name:expr, $arity:expr, $func:expr) ),* $(,)? ]) => {{
        use cljrs_gc::GcPtr;
        use cljrs_value::{NativeFn, Value};
        let ns: &str = $ns;
        $(
            {
                let nf = NativeFn::new($name, $arity, $func);
                $globals.intern(ns, std::sync::Arc::from($name), Value::NativeFunction(GcPtr::new(nf)));
            }
        )*
    }};
}

pub(crate) use register_fns;

// ── Public API ────────────────────────────────────────────────────────────────

/// Register all built-in stdlib namespaces into `globals`.
///
/// This is idempotent: calling it again does not re-evaluate sources
/// (already-loaded guard in `load_ns` prevents that), but it will
/// overwrite native fn registrations in the namespace tables.
/// In practice, call it once right after `standard_env_minimal()`.
pub fn register(globals: &Arc<GlobalEnv>) {
    // clojure.string ─ pre-register native fns, then register source for
    // the lazy (ns clojure.string) form to run on first require.
    string::register(globals, "clojure.string");
    globals.register_builtin_source("clojure.string", CLOJURE_STRING_SRC);

    // clojure.set ─ same pattern.
    set::register(globals, "clojure.set");
    globals.register_builtin_source("clojure.set", CLOJURE_SET_SRC);

    // clojure.template ─ pure Clojure, no native helpers.
    globals.register_builtin_source("clojure.template", CLOJURE_TEMPLATE_SRC);

    // clojure.test ─ pure Clojure, no native helpers.
    globals.register_builtin_source("clojure.test", CLOJURE_TEST_SRC);

    // clojure.rust.io and clojure.edn use std::fs, unavailable on wasm32.
    #[cfg(not(target_arch = "wasm32"))]
    {
        io::register(globals, "clojure.rust.io");
        globals.register_builtin_source("clojure.rust.io", CLOJURE_RUST_IO_SRC);

        edn::register(globals, "clojure.edn");
        globals.register_builtin_source("clojure.edn", CLOJURE_EDN_SRC);
    }

    // clojure.walk ─ pure Clojure, no native helpers.
    globals.register_builtin_source("clojure.walk", CLOJURE_WALK_SRC);

    // clojure.data ─ pure Clojure, no native helpers.
    globals.register_builtin_source("clojure.data", CLOJURE_DATA_SRC);

    // clojure.zip
    globals.register_builtin_source("clojure.zip", COLJURE_ZIP_SRC);
}

/// Prebuilt IR bundle for clojure.core (generated at build time).
/// When the `prebuild-ir` feature is enabled, this contains serialized IR
/// for all lowerable functions; otherwise it's an empty slice.
#[cfg(feature = "prebuild-ir")]
static PREBUILT_IR: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/core_ir.bin"));

/// Prebuilt IR bundle for the five cljrs.compiler.* namespaces.
/// Loaded into the IR cache after ensure_compiler_loaded() populates the
/// namespace vars so the compiler itself runs in IR mode on hot paths.
#[cfg(feature = "prebuild-ir")]
static PREBUILT_COMPILER_IR: &[u8] = include_bytes!(concat!(env!("OUT_DIR"), "/compiler_ir.bin"));

/// Load the prebuilt compiler IR bundle into the IR cache.
///
/// Called after `ensure_compiler_loaded` so that the compiler namespace vars
/// (with their runtime `ir_arity_id`s) already exist in `globals`.
/// `load_prebuilt_ir` matches bundle keys (`"ns/name:arity"`) to live arity
/// objects and stores the pre-built IR in the cache, replacing tree-walking
/// for the hot compiler code paths.
#[cfg(feature = "prebuild-ir")]
fn load_prebuilt_compiler_ir(globals: &Arc<GlobalEnv>) {
    match cljrs_ir::deserialize_bundle(PREBUILT_COMPILER_IR) {
        Ok(bundle) if !bundle.is_empty() => {
            let n = cljrs_eval::load_prebuilt_ir(globals, &bundle);
            cljrs_logging::feat_debug!(
                "ir",
                "loaded {n} prebuilt compiler IR arities from bundle ({} entries)",
                bundle.len()
            );
        }
        Ok(_) => {}
        Err(e) => {
            cljrs_logging::feat_debug!("ir", "compiler IR bundle deserialize failed: {e}");
        }
    }
}

#[cfg(not(feature = "prebuild-ir"))]
fn load_prebuilt_compiler_ir(_globals: &Arc<GlobalEnv>) {}

/// Create a `GlobalEnv` with all built-ins and stdlib registered, **without**
/// the IR lowering hook or compiler loading.
///
/// Use this in the AOT test harness and any other execution context where
/// IR generation is not needed.  It avoids populating the global `IR_CACHE`
/// with entries for test-namespace functions (entries that would never be
/// evicted and would accumulate to hundreds of MB over 233 namespaces).
/// It also skips loading the cljrs.compiler.* namespaces, saving additional
/// startup time and memory.
///
/// GC config and root tracer are still registered identically to `standard_env`.
#[cfg(not(target_arch = "wasm32"))]
pub fn standard_env_no_ir() -> Arc<GlobalEnv> {
    let globals = cljrs_eval::standard_env_minimal_no_ir();
    register(&globals);

    cljrs_gc::HEAP.set_config_from_env();
    let roots_gc = globals.clone();
    cljrs_gc::HEAP.register_root_tracer(move |visitor| {
        use cljrs_gc::GcVisitor as _;
        let namespaces = roots_gc.namespaces.read().unwrap();
        for (_name, ns_ptr) in namespaces.iter() {
            visitor.visit(ns_ptr);
        }
    });

    globals
}

/// Create a `GlobalEnv` with all built-ins and stdlib registered.
///
/// Prefer this over `cljrs_eval::standard_env()` in the `cljrs` binary so that
/// stdlib namespaces are loaded lazily (only on first `require`) instead of
/// eagerly at startup.
#[cfg(not(target_arch = "wasm32"))]
pub fn standard_env() -> Arc<GlobalEnv> {
    let globals = cljrs_eval::standard_env_minimal();
    register(&globals);

    // Configure GC with default limits and register namespace bindings as roots.
    // Without this, the GC never fires (no config → no soft-limit check).
    // standard_env_with_paths_and_config() overrides the config but reuses this tracer.
    cljrs_gc::HEAP.set_config_from_env();
    let roots_gc = globals.clone();
    cljrs_gc::HEAP.register_root_tracer(move |visitor| {
        use cljrs_gc::GcVisitor as _;
        let namespaces = roots_gc.namespaces.read().unwrap();
        for (_name, ns_ptr) in namespaces.iter() {
            visitor.visit(ns_ptr);
        }
    });

    // Try loading prebuilt IR first (skips compiler loading entirely).
    #[cfg(feature = "prebuild-ir")]
    {
        match cljrs_ir::deserialize_bundle(PREBUILT_IR) {
            Ok(bundle) if !bundle.is_empty() => {
                // Register compiler sources (needed for any functions not in the
                // prebuilt bundle, and for user code that triggers IR lowering).
                cljrs_eval::register_compiler_sources(&globals);

                let loaded = cljrs_eval::load_prebuilt_ir(&globals, &bundle);
                cljrs_logging::feat_debug!(
                    "ir",
                    "loaded {loaded} prebuilt IR arities from bundle ({} entries)",
                    bundle.len()
                );

                // Still load the compiler on a background thread so new user
                // functions can be eagerly lowered at definition time.
                // Once loaded, populate the IR cache with prebuilt compiler IR
                // so the compiler itself runs in IR mode on hot paths.
                let g = globals.clone();
                let _ = std::thread::Builder::new()
                    .stack_size(16 * 1024 * 1024)
                    .spawn(move || {
                        let mut env = cljrs_eval::Env::new(g.clone(), "user");
                        if cljrs_eval::ensure_compiler_loaded(&g, &mut env) {
                            load_prebuilt_compiler_ir(&g);
                        }
                    });

                return globals;
            }
            _ => {
                // Empty or corrupt bundle — fall through to runtime lowering.
            }
        }
    }

    // Fallback: register and load compiler namespaces so IR lowering is
    // available at runtime. Loading runs on a thread with a large stack
    // because the Clojure compiler sources are deeply recursive.
    cljrs_eval::register_compiler_sources(&globals);
    {
        let g = globals.clone();
        let _ = std::thread::Builder::new()
            .stack_size(16 * 1024 * 1024)
            .spawn(move || {
                let mut env = cljrs_eval::Env::new(g.clone(), "user");
                if cljrs_eval::ensure_compiler_loaded(&g, &mut env) {
                    load_prebuilt_compiler_ir(&g);
                }
            })
            .and_then(|h| h.join().map_err(|_| std::io::Error::other("join failed")));
    }

    globals
}

/// Like [`standard_env()`] but also sets user source paths for `require`.
#[cfg(not(target_arch = "wasm32"))]
pub fn standard_env_with_paths(source_paths: Vec<std::path::PathBuf>) -> Arc<GlobalEnv> {
    let globals = standard_env();
    globals.set_source_paths(source_paths);
    globals
}

/// Like [`standard_env_with_paths()`] but also sets GC configuration.
#[cfg(not(target_arch = "wasm32"))]
pub fn standard_env_with_paths_and_config(
    source_paths: Vec<std::path::PathBuf>,
    gc_config: Arc<GcConfig>,
) -> Arc<GlobalEnv> {
    let globals = standard_env();
    globals.set_source_paths(source_paths);
    globals.set_gc_config(gc_config.clone());
    // Override the default GC config set by standard_env() with the custom limits.
    // The root tracer is already registered by standard_env().
    cljrs_gc::HEAP.set_config(gc_config);
    globals
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use cljrs_eval::{Env, EvalResult, eval};
    use cljrs_reader::Parser;
    use cljrs_value::Value;

    fn make_env() -> (Arc<GlobalEnv>, Env) {
        let globals = standard_env();
        let env = Env::new(globals.clone(), "user");
        (globals, env)
    }

    #[allow(clippy::result_large_err)]
    fn run(src: &str, env: &mut Env) -> EvalResult {
        let mut parser = Parser::new(src.to_string(), "<test>".to_string());
        let forms = parser.parse_all().expect("parse error");
        let mut result = Value::Nil;
        for form in forms {
            result = eval(&form, env)?;
        }
        Ok(result)
    }

    // ── clojure.string ────────────────────────────────────────────────────────

    #[test]
    fn test_string_upper_lower() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        assert_eq!(
            run("(str/upper-case \"hello\")", &mut env).unwrap(),
            Value::string("HELLO")
        );
        assert_eq!(
            run("(str/lower-case \"WORLD\")", &mut env).unwrap(),
            Value::string("world")
        );
    }

    #[test]
    fn test_string_trim() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        assert_eq!(
            run("(str/trim \"  hello  \")", &mut env).unwrap(),
            Value::string("hello")
        );
        assert_eq!(
            run("(str/triml \"  hi\")", &mut env).unwrap(),
            Value::string("hi")
        );
        assert_eq!(
            run("(str/trimr \"hi  \")", &mut env).unwrap(),
            Value::string("hi")
        );
    }

    #[test]
    fn test_string_predicates() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        assert_eq!(
            run("(str/blank? \"  \")", &mut env).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            run("(str/blank? \"x\")", &mut env).unwrap(),
            Value::Bool(false)
        );
        assert_eq!(
            run("(str/starts-with? \"hello\" \"hel\")", &mut env).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            run("(str/ends-with? \"hello\" \"llo\")", &mut env).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            run("(str/includes? \"hello\" \"ell\")", &mut env).unwrap(),
            Value::Bool(true)
        );
    }

    #[test]
    fn test_string_replace() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        assert_eq!(
            run("(str/replace \"aabbcc\" \"bb\" \"XX\")", &mut env).unwrap(),
            Value::string("aaXXcc")
        );
        assert_eq!(
            run("(str/replace-first \"aabbcc\" \"a\" \"X\")", &mut env).unwrap(),
            Value::string("Xabbcc")
        );
    }

    #[test]
    fn test_string_split_join() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        let v = run("(str/split \"a,b,c\" \",\")", &mut env).unwrap();
        assert!(matches!(v, Value::Vector(_)));
        assert_eq!(
            run("(str/join \"-\" [\"a\" \"b\" \"c\"])", &mut env).unwrap(),
            Value::string("a-b-c")
        );
    }

    #[test]
    fn test_string_capitalize() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        assert_eq!(
            run("(str/capitalize \"hello world\")", &mut env).unwrap(),
            Value::string("Hello world")
        );
    }

    #[test]
    fn test_string_split_lines() {
        let (_, mut env) = make_env();
        run("(require '[clojure.string :as str])", &mut env).unwrap();
        let v = run("(str/split-lines \"a\\nb\\nc\")", &mut env).unwrap();
        assert!(matches!(v, Value::Vector(_)));
    }

    // ── clojure.set ───────────────────────────────────────────────────────────

    #[test]
    fn test_set_union() {
        let (_, mut env) = make_env();
        run("(require '[clojure.set :as s])", &mut env).unwrap();
        let v = run("(s/union #{1 2} #{2 3})", &mut env).unwrap();
        match v {
            Value::Set(s) => assert_eq!(s.count(), 3),
            other => panic!("expected set, got {other:?}"),
        }
    }

    #[test]
    fn test_set_intersection() {
        let (_, mut env) = make_env();
        run("(require '[clojure.set :as s])", &mut env).unwrap();
        let v = run("(s/intersection #{1 2 3} #{2 3 4})", &mut env).unwrap();
        match v {
            Value::Set(s) => assert_eq!(s.count(), 2),
            other => panic!("expected set, got {other:?}"),
        }
    }

    #[test]
    fn test_set_difference() {
        let (_, mut env) = make_env();
        run("(require '[clojure.set :as s])", &mut env).unwrap();
        let v = run("(s/difference #{1 2 3} #{2 3})", &mut env).unwrap();
        match v {
            Value::Set(s) => assert_eq!(s.count(), 1),
            other => panic!("expected set, got {other:?}"),
        }
    }

    #[test]
    fn test_set_subset_superset() {
        let (_, mut env) = make_env();
        run("(require '[clojure.set :as s])", &mut env).unwrap();
        assert_eq!(
            run("(s/subset? #{1 2} #{1 2 3})", &mut env).unwrap(),
            Value::Bool(true)
        );
        assert_eq!(
            run("(s/superset? #{1 2 3} #{1 2})", &mut env).unwrap(),
            Value::Bool(true)
        );
    }

    #[test]
    fn test_set_map_invert() {
        let (_, mut env) = make_env();
        run("(require '[clojure.set :as s])", &mut env).unwrap();
        let v = run("(s/map-invert {:a 1 :b 2})", &mut env).unwrap();
        assert!(matches!(v, Value::Map(_)));
    }

    // ── clojure.test (via stdlib registry) ───────────────────────────────────

    #[test]
    fn test_clojure_test_lazy_load() {
        // Run on a thread with adequate stack: the `is` macro expansion
        // triggers eager IR lowering, which calls the Clojure compiler
        // (deeply recursive — needs more than the default 2MB test thread stack).
        std::thread::Builder::new()
            .stack_size(16 * 1024 * 1024)
            .spawn(|| {
                let (_, mut env) = make_env();
                // clojure.test is NOT pre-loaded in standard_env_minimal();
                // it should load lazily from the registry.
                run(
                    "(require '[clojure.test :refer [is deftest run-tests]])",
                    &mut env,
                )
                .unwrap();
                let v = run("(is (= 1 1))", &mut env).unwrap();
                assert_eq!(v, Value::Bool(true));
            })
            .unwrap()
            .join()
            .unwrap();
    }
}