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("(find (lambda (x) (> x 2)) (list 1 2 3 4))", "Int(3)");
199    }
200
201    #[test]
202    fn hof_every_and_any() {
203        eval_eq("(every? (lambda (x) (> x 0)) (list 1 2 3))", "Bool(true)");
204        eval_eq("(any? (lambda (x) (> x 5)) (list 1 2 3))", "Bool(false)");
205    }
206
207    #[test]
208    fn hof_remove_inverse_of_filter() {
209        let v = eval_ok("(remove (lambda (x) (= 0 (modulo x 2))) (list 1 2 3 4 5))");
210        assert_eq!(format!("{v:?}"), "[Int(1), Int(3), Int(5)]");
211    }
212
213    #[test]
214    fn hof_apply() {
215        eval_eq("(apply + (list 1 2 3 4))", "Int(10)");
216    }
217
218    // ── Pure-Lisp stdlib (install_lisp_stdlib_with) ────────────────
219
220    #[test]
221    fn lisp_compose_and_pipe() {
222        eval_eq("((compose inc inc) 5)", "Int(7)");
223        eval_eq("((pipe inc inc inc) 5)", "Int(8)");
224    }
225
226    #[test]
227    fn lisp_seq_helpers() {
228        eval_eq("(first (list 10 20 30))", "Int(10)");
229        eval_eq("(last (list 10 20 30))", "Int(30)");
230        let v = eval_ok("(rest (list 10 20 30))");
231        assert_eq!(format!("{v:?}"), "[Int(20), Int(30)]");
232    }
233
234    #[test]
235    fn lisp_range() {
236        let v = eval_ok("(range 5)");
237        assert_eq!(format!("{v:?}"), "[Int(0), Int(1), Int(2), Int(3), Int(4)]");
238    }
239
240    #[test]
241    fn lisp_concat_and_distinct() {
242        let cat = eval_ok("(concat (list 1 2) (list 3 4))");
243        assert_eq!(format!("{cat:?}"), "[Int(1), Int(2), Int(3), Int(4)]");
244        let uniq = eval_ok("(distinct (list 1 2 1 3 2 4))");
245        assert_eq!(format!("{uniq:?}"), "[Int(1), Int(2), Int(3), Int(4)]");
246    }
247
248    #[test]
249    fn lisp_numeric_helpers() {
250        eval_eq("(inc 5)", "Int(6)");
251        eval_eq("(dec 5)", "Int(4)");
252        eval_eq("(even? 4)", "Bool(true)");
253        eval_eq("(odd? 3)", "Bool(true)");
254        eval_eq("(zero? 0)", "Bool(true)");
255        eval_eq("(positive? 1)", "Bool(true)");
256        eval_eq("(negative? -1)", "Bool(true)");
257    }
258
259    #[test]
260    fn lisp_threading_macros() {
261        // `(-> 5 inc inc inc)` ≡ `(inc (inc (inc 5)))`
262        eval_eq("(-> 5 inc inc inc)", "Int(8)");
263        // `(->> 5 inc inc)` puts the value in the LAST position. inc is
264        // unary so position doesn't matter — confirms the macro fires.
265        eval_eq("(->> 5 inc inc)", "Int(7)");
266    }
267
268    // ── Clojure aliases ────────────────────────────────────────────
269
270    #[test]
271    fn alias_fn_for_lambda() {
272        eval_eq("((fn (x) (* x x)) 4)", "Int(16)");
273    }
274
275    #[test]
276    fn alias_true_false() {
277        eval_eq("true", "Bool(true)");
278        eval_eq("false", "Bool(false)");
279    }
280
281    #[test]
282    fn alias_nil_predicate() {
283        eval_eq("(nil? (list))", "Bool(true)");
284        eval_eq("(nil? (list 1))", "Bool(false)");
285    }
286
287    #[test]
288    fn alias_double_equals() {
289        eval_eq("(== 1 1)", "Bool(true)");
290        eval_eq("(== 1 2)", "Bool(false)");
291    }
292
293    #[test]
294    fn alias_next_is_rest() {
295        let v = eval_ok("(next (list 1 2 3))");
296        assert_eq!(format!("{v:?}"), "[Int(2), Int(3)]");
297    }
298
299    // ── End-to-end script-style smoke ───────────────────────────────
300
301    #[test]
302    fn end_to_end_small_pipeline() {
303        // Idiomatic "filter even, double, sum" — the smallest realistic
304        // shape that exercises filter + map + foldl/reduce in one breath.
305        eval_eq(
306            "(reduce + (map (fn (x) (* x 2)) (filter even? (range 10))))",
307            "Int(40)", // 2+4+6+8 = 20, doubled = 40
308        );
309    }
310
311    #[test]
312    fn end_to_end_threading_with_aliases() {
313        eval_eq("(-> 1 inc inc inc inc)", "Int(5)");
314    }
315}
tatara_lisp_script/stdlib/mod.rs

tatara_lisp_script/stdlib/
mod.rs
