tatara_lisp_script/stdlib/
mod.rs

1//! The tatara-script stdlib. Each module registers a family of FFI
2//! primitives on `Interpreter<ScriptCtx>`; `install_stdlib` is the
3//! single entry point — call after `Interpreter::new()`.
4//!
5//! `install_stdlib` also calls `tatara_lisp_eval::install_primitives`,
6//! `install_hof`, and `install_map` up front so arithmetic, comparison,
7//! list primitives (`+`, `-`, `=`, `car`, `cdr`, `cons`, `list`, …) AND
8//! higher-order list ops (`map`, `filter`, `reduce`, `foldl`, `foldr`,
9//! `for-each`, `apply`, `find`, `every?`, `any?`, `partition`,
10//! `group-by`, `sort-by`, `iterate`, `take-while`, `drop-while`,
11//! `remove`, `count-if`, `find-index`, `scan-left`, `repeatedly`,
12//! `some`) and `(map …)` constructors / accessors are available to any
13//! script. Without these, `Interpreter::new()` is intentionally bare —
14//! the evaluator leaves primitive registration to the embedder, and
15//! historically `install_stdlib` here only wired primitives so HOFs
16//! were silently absent at script runtime.
17//!
18//! Anything beyond these (Lisp-source stdlib like `compose`, `pipe`,
19//! `->`, `->>`, `defflow`, `dotimes`, `distinct`, `group-by` helpers)
20//! lives in `tatara-lisp-eval::install_lisp_stdlib_with` and requires a
21//! host context — it's deliberately NOT installed here today since
22//! tatara-script's per-script ScriptCtx isn't available at
23//! install-time. Call `install_lisp_stdlib_with` from your binary if
24//! you need it.
25
26use tatara_lisp_eval::{
27    install_hof, install_lisp_stdlib_with, install_map, install_primitives, Interpreter,
28};
29
30use crate::script_ctx::ScriptCtx;
31
32// Core scripting families
33pub mod cli;
34pub mod crypto_extra;
35pub mod dns;
36pub mod encoding;
37pub mod env;
38pub mod fs;
39pub mod hash;
40pub mod http;
41pub mod http_server;
42pub mod io;
43pub mod json;
44pub mod kube;
45pub mod list_ext;
46pub mod log;
47pub mod module;
48pub mod os;
49pub mod process;
50pub mod regex;
51pub mod sops;
52pub mod string;
53pub mod string_ext;
54pub mod time;
55pub mod toml;
56pub mod uuid;
57pub mod yaml;
58
59/// Install every stdlib family. Three layers, in order:
60///
61///   1. Rust primitives (`install_primitives`): arithmetic, comparison,
62///      list/string/IO — `+`, `=`, `car`, `cons`, `length`, `reverse`,
63///      `string-format`, `print-line`, `read-file`, …
64///   2. Higher-order Rust primitives (`install_hof`): `map`, `filter`,
65///      `reduce`, `foldl`, `foldr`, `for-each`, `apply`, `find`,
66///      `every?`, `any?`, `partition`, `group-by`, `sort-by`,
67///      `iterate`, `take-while`, `drop-while`, `remove`, `count-if`,
68///      `find-index`, `scan-left`, `repeatedly`, `some`.
69///   3. Typed map/dict primitives (`install_map`): `(map ...)` value
70///      constructor + accessors (alist-get, etc.).
71///
72/// Then the FFI families (cli/fs/http/json/regex/sops/...).
73/// Finally, the pure-Lisp stdlib (`install_lisp_stdlib_with`) which adds
74/// `compose`, `pipe`, `->`, `->>`, `when-let`, `dotimes`, `dolist`,
75/// `defflow`, `inc`, `dec`, `even?`, `odd?`, `first`/`second`/`third`,
76/// `range`, `zip`, `interleave`, `flatten`, `distinct`, `max-by`,
77/// `min-by`, `partial`, `juxt`, `tap`, `not=`, `some?`, `not-empty?`.
78///
79/// Scripts see the full Clojure-flavored environment without calling
80/// any of these installers themselves.
81pub fn install_stdlib(interp: &mut Interpreter<ScriptCtx>, ctx: &mut ScriptCtx) {
82    install_primitives(interp);
83    install_hof(interp);
84    install_map(interp);
85    cli::install(interp);
86    crypto_extra::install(interp);
87    dns::install(interp);
88    encoding::install(interp);
89    env::install(interp);
90    fs::install(interp);
91    hash::install(interp);
92    http::install(interp);
93    http_server::install(interp);
94    io::install(interp);
95    kube::install(interp);
96    json::install(interp);
97    list_ext::install(interp);
98    log::install(interp);
99    module::install(interp);
100    os::install(interp);
101    process::install(interp);
102    regex::install(interp);
103    sops::install(interp);
104    string::install(interp);
105    string_ext::install(interp);
106    time::install(interp);
107    toml::install(interp);
108    uuid::install(interp);
109    yaml::install(interp);
110    // Pure-Lisp layer LAST — it depends on every Rust primitive above
111    // (compose calls foldr, juxt calls map, threading macros use list?,
112    // etc.). Loading earlier would error on unbound primitives.
113    install_lisp_stdlib_with(interp, ctx);
114}
115
116#[cfg(test)]
117mod surface_tests {
118    //! Surface-area regression tests for `install_stdlib`.
119    //!
120    //! Every name in this module is something a script writer reasonably
121    //! expects to be in scope after `install_stdlib`. If one of these
122    //! tests fails, it means a previously-claimed primitive is gone — a
123    //! breaking change for every consumer .tlisp file in the org.
124    //!
125    //! Categories covered:
126    //!   1. Core Rust primitives (`+`, `=`, `car`, `cons`, `length`, `modulo`, `abs`, `min`, `max`, …)
127    //!   2. Higher-order Rust primitives (`map`, `filter`, `reduce`, `foldl`, `foldr`, `for-each`, `apply`, `find`, `every?`, `any?`, `partition`, `group-by`, `sort-by`, `iterate`, `take-while`, `drop-while`, `remove`)
128    //!   3. Pure-Lisp stdlib: identity / comp / pipe / partial / juxt / tap, `->` / `->>` threading, `when-let` / `if-let` / `dotimes` / `dolist`, sequence helpers (first/second/third/rest/last/butlast, range, repeat-list, concat, member?, position, zip, interleave, intersperse, flatten, distinct, max-by, min-by), numeric helpers (inc, dec, zero?, positive?, negative?, even?, odd?), predicates (not=, some?, not-empty?)
129    //!   4. Clojure-flavored aliases (`fn`, `true`, `false`, `mod`, `rem`, `nil?`, `==`, `next`).
130
131    use crate::{eval_str, Value};
132
133    /// Helper: eval and assert against a stringified result.
134    fn eval_eq(src: &str, expected: &str) {
135        let v = eval_str(src).expect(src);
136        assert_eq!(format!("{v:?}"), expected, "src: {src}");
137    }
138
139    fn eval_ok(src: &str) -> Value {
140        eval_str(src).unwrap_or_else(|e| panic!("eval failed for {src:?}: {e}"))
141    }
142
143    // ── Core primitives ─────────────────────────────────────────────
144
145    #[test]
146    fn arith_modulo_and_friends() {
147        // The `mod`/`rem` aliases must agree with the canonical `modulo`.
148        eval_eq("(modulo 7 3)", "Int(1)");
149        eval_eq("(mod 7 3)", "Int(1)");
150        eval_eq("(rem 7 3)", "Int(1)");
151    }
152
153    #[test]
154    fn arith_min_max_abs() {
155        eval_eq("(min 1 2 3)", "Int(1)");
156        eval_eq("(max 1 2 3)", "Int(3)");
157        eval_eq("(abs -5)", "Int(5)");
158    }
159
160    #[test]
161    fn list_primitives() {
162        eval_eq("(car (list 1 2 3))", "Int(1)");
163        eval_eq("(length (list 1 2 3 4))", "Int(4)");
164    }
165
166    // ── Higher-order Rust primitives (install_hof) ─────────────────
167
168    #[test]
169    fn hof_filter_evens() {
170        // The headline regression: filter MUST be bound after install_stdlib.
171        let v = eval_ok("(filter (lambda (x) (= 0 (modulo x 2))) (list 1 2 3 4 5))");
172        assert_eq!(format!("{v:?}"), "[Int(2), Int(4)]");
173    }
174
175    #[test]
176    fn hof_map_double() {
177        let v = eval_ok("(map (lambda (x) (* x 2)) (list 1 2 3))");
178        assert_eq!(format!("{v:?}"), "[Int(2), Int(4), Int(6)]");
179    }
180
181    #[test]
182    fn hof_foldl_sum() {
183        eval_eq("(foldl + 0 (list 1 2 3 4 5))", "Int(15)");
184    }
185
186    #[test]
187    fn hof_foldr_sum() {
188        eval_eq("(foldr + 0 (list 1 2 3 4 5))", "Int(15)");
189    }
190
191    #[test]
192    fn hof_reduce_sum() {
193        eval_eq("(reduce + (list 1 2 3 4 5))", "Int(15)");
194    }
195
196    #[test]
197    fn hof_find_first_match() {
198        eval_eq(
199            "(find (lambda (x) (> x 2)) (list 1 2 3 4))",
200            "Int(3)",
201        );
202    }
203
204    #[test]
205    fn hof_every_and_any() {
206        eval_eq("(every? (lambda (x) (> x 0)) (list 1 2 3))", "Bool(true)");
207        eval_eq("(any? (lambda (x) (> x 5)) (list 1 2 3))", "Bool(false)");
208    }
209
210    #[test]
211    fn hof_remove_inverse_of_filter() {
212        let v = eval_ok("(remove (lambda (x) (= 0 (modulo x 2))) (list 1 2 3 4 5))");
213        assert_eq!(format!("{v:?}"), "[Int(1), Int(3), Int(5)]");
214    }
215
216    #[test]
217    fn hof_apply() {
218        eval_eq("(apply + (list 1 2 3 4))", "Int(10)");
219    }
220
221    // ── Pure-Lisp stdlib (install_lisp_stdlib_with) ────────────────
222
223    #[test]
224    fn lisp_compose_and_pipe() {
225        eval_eq("((compose inc inc) 5)", "Int(7)");
226        eval_eq("((pipe inc inc inc) 5)", "Int(8)");
227    }
228
229    #[test]
230    fn lisp_seq_helpers() {
231        eval_eq("(first (list 10 20 30))", "Int(10)");
232        eval_eq("(last (list 10 20 30))", "Int(30)");
233        let v = eval_ok("(rest (list 10 20 30))");
234        assert_eq!(format!("{v:?}"), "[Int(20), Int(30)]");
235    }
236
237    #[test]
238    fn lisp_range() {
239        let v = eval_ok("(range 5)");
240        assert_eq!(format!("{v:?}"), "[Int(0), Int(1), Int(2), Int(3), Int(4)]");
241    }
242
243    #[test]
244    fn lisp_concat_and_distinct() {
245        let cat = eval_ok("(concat (list 1 2) (list 3 4))");
246        assert_eq!(format!("{cat:?}"), "[Int(1), Int(2), Int(3), Int(4)]");
247        let uniq = eval_ok("(distinct (list 1 2 1 3 2 4))");
248        assert_eq!(format!("{uniq:?}"), "[Int(1), Int(2), Int(3), Int(4)]");
249    }
250
251    #[test]
252    fn lisp_numeric_helpers() {
253        eval_eq("(inc 5)", "Int(6)");
254        eval_eq("(dec 5)", "Int(4)");
255        eval_eq("(even? 4)", "Bool(true)");
256        eval_eq("(odd? 3)", "Bool(true)");
257        eval_eq("(zero? 0)", "Bool(true)");
258        eval_eq("(positive? 1)", "Bool(true)");
259        eval_eq("(negative? -1)", "Bool(true)");
260    }
261
262    #[test]
263    fn lisp_threading_macros() {
264        // `(-> 5 inc inc inc)` ≡ `(inc (inc (inc 5)))`
265        eval_eq("(-> 5 inc inc inc)", "Int(8)");
266        // `(->> 5 inc inc)` puts the value in the LAST position. inc is
267        // unary so position doesn't matter — confirms the macro fires.
268        eval_eq("(->> 5 inc inc)", "Int(7)");
269    }
270
271    // ── Clojure aliases ────────────────────────────────────────────
272
273    #[test]
274    fn alias_fn_for_lambda() {
275        eval_eq("((fn (x) (* x x)) 4)", "Int(16)");
276    }
277
278    #[test]
279    fn alias_true_false() {
280        eval_eq("true", "Bool(true)");
281        eval_eq("false", "Bool(false)");
282    }
283
284    #[test]
285    fn alias_nil_predicate() {
286        eval_eq("(nil? (list))", "Bool(true)");
287        eval_eq("(nil? (list 1))", "Bool(false)");
288    }
289
290    #[test]
291    fn alias_double_equals() {
292        eval_eq("(== 1 1)", "Bool(true)");
293        eval_eq("(== 1 2)", "Bool(false)");
294    }
295
296    #[test]
297    fn alias_next_is_rest() {
298        let v = eval_ok("(next (list 1 2 3))");
299        assert_eq!(format!("{v:?}"), "[Int(2), Int(3)]");
300    }
301
302    // ── End-to-end script-style smoke ───────────────────────────────
303
304    #[test]
305    fn end_to_end_small_pipeline() {
306        // Idiomatic "filter even, double, sum" — the smallest realistic
307        // shape that exercises filter + map + foldl/reduce in one breath.
308        eval_eq(
309            "(reduce + (map (fn (x) (* x 2)) (filter even? (range 10))))",
310            "Int(40)", // 2+4+6+8 = 20, doubled = 40
311        );
312    }
313
314    #[test]
315    fn end_to_end_threading_with_aliases() {
316        eval_eq(
317            "(-> 1 inc inc inc inc)",
318            "Int(5)",
319        );
320    }
321}
tatara_lisp_script/stdlib/mod.rs

tatara_lisp_script/stdlib/
mod.rs
