blue_lang_runtime/
stdlib.rs

1//! blue's string and number core.
2//!
3//! tatara-lisp ships arithmetic, comparison, list and trig primitives and
4//! **no string operations at all** — no length, no concatenation, no case
5//! conversion, no number parsing. For a language whose surface is Ruby's, that
6//! is the largest parity gap there is: `String` is the most-used type in Ruby
7//! by a wide margin.
8//!
9//! # Why these live in blue and not in tatara-lisp
10//!
11//! The fleet rule is to extend the substrate rather than re-implement, and
12//! generic helpers belong upstream. These are not generic: the *semantics* are
13//! blue's, and they are Ruby's semantics specifically.
14//!
15//! The clearest case is `length`. Ruby's `String#length` counts **characters**;
16//! Rust's `str::len` counts **bytes**; Elixir's `String.length/1` counts
17//! grapheme clusters. Three languages, three answers, all defensible. Blue owes
18//! its users Ruby's answer, and encoding that choice into tatara-lisp would push
19//! one language's convention onto every other consumer of the substrate.
20//!
21//! Promoting a genuinely encoding-neutral core upstream later stays open; the
22//! character-counting ones are blue's by right.
23//!
24//! # Character, not byte, not grapheme
25//!
26//! Every index and length here is in **Unicode scalar values** (Rust `char`).
27//! That matches Ruby for the overwhelming majority of text and is stated rather
28//! than left to be discovered — a `length` that silently returns bytes is the
29//! bug that only appears once a user types a non-ASCII character.
30//!
31//! Grapheme clusters (Elixir's choice) would need a segmentation table; where
32//! the two differ — a family emoji, a combining accent — blue reports scalar
33//! values. `a_combining_sequence_counts_scalars_not_graphemes` pins it.
34
35use tatara_lisp_eval::ffi::Arity;
36use tatara_lisp_eval::{EvalError, Interpreter, Value};
37
38fn as_str(v: &Value, span: tatara_lisp::Span) -> Result<String, EvalError> {
39    match v {
40        Value::Str(s) => Ok(s.to_string()),
41        // A symbol is text the author wrote; accepting it makes `upcase(:ok)`
42        // work the way a Ruby programmer expects of a symbol.
43        Value::Symbol(s) | Value::Keyword(s) => Ok(s.to_string()),
44        other => Err(EvalError::type_mismatch(
45            "a string",
46            other.type_name(),
47            span,
48        )),
49    }
50}
51
52/// Render any value as text — blue's `to_s`.
53fn render(v: &Value) -> String {
54    match v {
55        Value::Nil => String::new(),
56        Value::Bool(b) => b.to_string(),
57        Value::Int(n) => n.to_string(),
58        Value::Float(x) => x.to_string(),
59        Value::Str(s) | Value::Symbol(s) | Value::Keyword(s) => s.to_string(),
60        Value::List(items) => items.iter().map(render).collect::<Vec<_>>().join(" "),
61        other => other.type_name().to_string(),
62    }
63}
64
65fn list(items: Vec<Value>) -> Value {
66    Value::List(std::sync::Arc::new(items))
67}
68
69/// Install blue's string and number core.
70pub fn install_blue_stdlib<H: 'static>(interp: &mut Interpreter<H>) {
71    // ── text ──────────────────────────────────────────────────────────
72
73    // `length` counts CHARACTERS, per Ruby. Also accepts a list, where it is
74    // the element count — Ruby's `Array#length`.
75    interp.register_fn(
76        "length",
77        Arity::Exact(1),
78        |a: &[Value], _h: &mut H, span| match &a[0] {
79            Value::List(items) => Ok(Value::Int(items.len() as i64)),
80            other => Ok(Value::Int(as_str(other, span)?.chars().count() as i64)),
81        },
82    );
83
84    interp.register_fn("to_s", Arity::Exact(1), |a: &[Value], _h: &mut H, _s| {
85        Ok(Value::Str(render(&a[0]).into()))
86    });
87
88    interp.register_fn("upcase", Arity::Exact(1), |a: &[Value], _h: &mut H, s| {
89        Ok(Value::Str(as_str(&a[0], s)?.to_uppercase().into()))
90    });
91
92    interp.register_fn("downcase", Arity::Exact(1), |a: &[Value], _h: &mut H, s| {
93        Ok(Value::Str(as_str(&a[0], s)?.to_lowercase().into()))
94    });
95
96    interp.register_fn("trim", Arity::Exact(1), |a: &[Value], _h: &mut H, s| {
97        Ok(Value::Str(as_str(&a[0], s)?.trim().into()))
98    });
99
100    // `concat(a, b)` — two-arg so it composes; `+` stays arithmetic. Ruby
101    // overloads `+` on String, but blue's `+` lowers to tatara's numeric `+`,
102    // and silently making it polymorphic would make a type error at a seam
103    // disappear into a string.
104    interp.register_fn("concat", Arity::Exact(2), |a: &[Value], _h: &mut H, _s| {
105        let mut out = render(&a[0]);
106        out.push_str(&render(&a[1]));
107        Ok(Value::Str(out.into()))
108    });
109
110    interp.register_fn("split", Arity::Exact(2), |a: &[Value], _h: &mut H, s| {
111        let text = as_str(&a[0], s)?;
112        let sep = as_str(&a[1], s)?;
113        // An empty separator splits into characters, as Ruby's `split("")`
114        // does. Rust's `split("")` yields leading/trailing empties instead,
115        // which is the wrong answer here.
116        let parts: Vec<Value> = if sep.is_empty() {
117            text.chars()
118                .map(|c| Value::Str(c.to_string().into()))
119                .collect()
120        } else {
121            text.split(sep.as_str())
122                .map(|p| Value::Str(p.into()))
123                .collect()
124        };
125        Ok(list(parts))
126    });
127
128    interp.register_fn("join", Arity::Exact(2), |a: &[Value], _h: &mut H, s| {
129        let sep = as_str(&a[1], s)?;
130        match &a[0] {
131            Value::List(items) => Ok(Value::Str(
132                items
133                    .iter()
134                    .map(render)
135                    .collect::<Vec<_>>()
136                    .join(&sep)
137                    .into(),
138            )),
139            other => Err(EvalError::type_mismatch("a list", other.type_name(), s).into()),
140        }
141    });
142
143    interp.register_fn(
144        "contains?",
145        Arity::Exact(2),
146        |a: &[Value], _h: &mut H, s| {
147            Ok(Value::Bool(as_str(&a[0], s)?.contains(&as_str(&a[1], s)?)))
148        },
149    );
150
151    interp.register_fn(
152        "starts_with?",
153        Arity::Exact(2),
154        |a: &[Value], _h: &mut H, s| {
155            Ok(Value::Bool(
156                as_str(&a[0], s)?.starts_with(&as_str(&a[1], s)?),
157            ))
158        },
159    );
160
161    interp.register_fn(
162        "ends_with?",
163        Arity::Exact(2),
164        |a: &[Value], _h: &mut H, s| {
165            Ok(Value::Bool(as_str(&a[0], s)?.ends_with(&as_str(&a[1], s)?)))
166        },
167    );
168
169    interp.register_fn("replace", Arity::Exact(3), |a: &[Value], _h: &mut H, s| {
170        Ok(Value::Str(
171            as_str(&a[0], s)?
172                .replace(&as_str(&a[1], s)?, &as_str(&a[2], s)?)
173                .into(),
174        ))
175    });
176
177    interp.register_fn("reverse", Arity::Exact(1), |a: &[Value], _h: &mut H, s| {
178        match &a[0] {
179            Value::List(items) => {
180                let mut v = items.as_ref().clone();
181                v.reverse();
182                Ok(list(v))
183            }
184            // Reversed by CHARACTER, so a multi-byte character survives. A
185            // byte-wise reverse produces invalid UTF-8.
186            other => Ok(Value::Str(
187                as_str(other, s)?.chars().rev().collect::<String>().into(),
188            )),
189        }
190    });
191
192    interp.register_fn("chars", Arity::Exact(1), |a: &[Value], _h: &mut H, s| {
193        Ok(list(
194            as_str(&a[0], s)?
195                .chars()
196                .map(|c| Value::Str(c.to_string().into()))
197                .collect(),
198        ))
199    });
200
201    // ── numbers ───────────────────────────────────────────────────────
202
203    // `to_int` RETURNS NIL on unparseable input rather than raising. Ruby's
204    // `String#to_i` answers 0 for garbage, which silently turns a parse failure
205    // into a plausible number; nil is falsy and cannot be mistaken for a
206    // result. `to_int!` is the raising form for callers who want the failure.
207    interp.register_fn(
208        "to_int",
209        Arity::Exact(1),
210        |a: &[Value], _h: &mut H, s| match &a[0] {
211            Value::Int(n) => Ok(Value::Int(*n)),
212            Value::Float(x) => Ok(Value::Int(*x as i64)),
213            other => Ok(as_str(other, s)?
214                .trim()
215                .parse::<i64>()
216                .map_or(Value::Nil, Value::Int)),
217        },
218    );
219
220    interp.register_fn(
221        "to_int!",
222        Arity::Exact(1),
223        |a: &[Value], _h: &mut H, s| match &a[0] {
224            Value::Int(n) => Ok(Value::Int(*n)),
225            Value::Float(x) => Ok(Value::Int(*x as i64)),
226            other => {
227                let text = as_str(other, s)?;
228                text.trim().parse::<i64>().map(Value::Int).map_err(|_| {
229                    EvalError::native_fn(
230                        "to_int!",
231                        "`".to_string() + &text + "` is not an integer",
232                        s,
233                    )
234                    .into()
235                })
236            }
237        },
238    );
239
240    interp.register_fn(
241        "to_float",
242        Arity::Exact(1),
243        |a: &[Value], _h: &mut H, s| match &a[0] {
244            Value::Float(x) => Ok(Value::Float(*x)),
245            Value::Int(n) => Ok(Value::Float(*n as f64)),
246            other => Ok(as_str(other, s)?
247                .trim()
248                .parse::<f64>()
249                .map_or(Value::Nil, Value::Float)),
250        },
251    );
252
253    interp.register_fn(
254        "abs",
255        Arity::Exact(1),
256        |a: &[Value], _h: &mut H, s| match &a[0] {
257            Value::Int(n) => Ok(Value::Int(n.abs())),
258            Value::Float(x) => Ok(Value::Float(x.abs())),
259            other => Err(EvalError::type_mismatch("a number", other.type_name(), s).into()),
260        },
261    );
262}
263
264#[cfg(test)]
265mod tests {
266    use super::*;
267
268    fn eval(src: &str) -> Value {
269        crate::run(src)
270            .unwrap_or_else(|e| panic!("{src:?}: {e}"))
271            .value
272    }
273
274    fn s(src: &str) -> String {
275        match eval(src) {
276            Value::Str(v) => v.to_string(),
277            other => panic!("{src:?} produced {other:?}"),
278        }
279    }
280
281    fn i(src: &str) -> i64 {
282        match eval(src) {
283            Value::Int(v) => v,
284            other => panic!("{src:?} produced {other:?}"),
285        }
286    }
287
288    /// **`length` counts CHARACTERS, as Ruby does — not bytes.** A `length`
289    /// that returns bytes is the bug that only surfaces once a user types a
290    /// non-ASCII character, which is exactly when it is hardest to trace.
291    #[test]
292    fn length_counts_characters_not_bytes() {
293        assert_eq!(i("length(\"hello\")"), 5);
294        // "héllo" is 6 bytes, 5 characters.
295        assert_eq!(i("length(\"héllo\")"), 5, "must not be 6");
296        // An emoji is 4 bytes, 1 character.
297        assert_eq!(i("length(\"😀\")"), 1, "must not be 4");
298    }
299
300    /// blue reports **scalar values**, not grapheme clusters. Elixir would say
301    /// 1 here; blue says 2. Stated and pinned rather than left to surprise.
302    #[test]
303    fn a_combining_sequence_counts_scalars_not_graphemes() {
304        // "e" + U+0301 COMBINING ACUTE — one grapheme, two scalars.
305        assert_eq!(
306            i("length(\"e\\u{301}\")"),
307            2,
308            "blue counts scalar values; Elixir's String.length would say 1"
309        );
310    }
311
312    #[test]
313    fn length_also_works_on_a_list() {
314        assert_eq!(i("length([1, 2, 3])"), 3);
315    }
316
317    #[test]
318    fn case_and_trim() {
319        assert_eq!(s("upcase(\"abc\")"), "ABC");
320        assert_eq!(s("downcase(\"ABC\")"), "abc");
321        assert_eq!(s("trim(\"  hi  \")"), "hi");
322        // Non-ASCII case works, which a byte-wise implementation would botch.
323        assert_eq!(s("upcase(\"é\")"), "É");
324    }
325
326    #[test]
327    fn concat_and_to_s() {
328        assert_eq!(s("concat(\"a\", \"b\")"), "ab");
329        assert_eq!(s("concat(\"n=\", 42)"), "n=42");
330        assert_eq!(s("to_s(42)"), "42");
331        assert_eq!(s("to_s(true)"), "true");
332    }
333
334    /// **`+` stays arithmetic.** Ruby overloads it on String, but blue's `+`
335    /// lowers to tatara's numeric `+`; making it polymorphic would let a type
336    /// error at a seam disappear into a string.
337    #[test]
338    fn plus_is_not_string_concatenation() {
339        assert!(
340            crate::run("\"a\" + \"b\"").is_err(),
341            "`+` must not silently concatenate — use concat"
342        );
343    }
344
345    #[test]
346    fn split_and_join() {
347        assert_eq!(i("length(split(\"a,b,c\", \",\"))"), 3);
348        assert_eq!(s("join(split(\"a,b,c\", \",\"), \"-\")"), "a-b-c");
349        // Ruby's `split("")` yields characters.
350        assert_eq!(i("length(split(\"abc\", \"\"))"), 3);
351    }
352
353    #[test]
354    fn predicates() {
355        assert!(matches!(
356            eval("contains?(\"hello\", \"ell\")"),
357            Value::Bool(true)
358        ));
359        assert!(matches!(
360            eval("contains?(\"hello\", \"xyz\")"),
361            Value::Bool(false)
362        ));
363        assert!(matches!(
364            eval("starts_with?(\"hello\", \"he\")"),
365            Value::Bool(true)
366        ));
367        assert!(matches!(
368            eval("ends_with?(\"hello\", \"lo\")"),
369            Value::Bool(true)
370        ));
371    }
372
373    #[test]
374    fn replace_and_chars() {
375        assert_eq!(s("replace(\"a-b-c\", \"-\", \"+\")"), "a+b+c");
376        assert_eq!(i("length(chars(\"abc\"))"), 3);
377    }
378
379    /// Reversed by character, so a multi-byte character survives. A byte-wise
380    /// reverse produces invalid UTF-8.
381    #[test]
382    fn reverse_is_character_wise() {
383        assert_eq!(s("reverse(\"abc\")"), "cba");
384        assert_eq!(s("reverse(\"héllo\")"), "olléh", "must not corrupt the é");
385    }
386
387    #[test]
388    fn reverse_also_works_on_a_list() {
389        assert_eq!(s("join(reverse([1, 2, 3]), \",\")"), "3,2,1");
390    }
391
392    /// **`to_int` answers nil on garbage, not 0.** Ruby's `String#to_i` returns
393    /// 0, which silently turns a parse failure into a plausible number — a
394    /// deliberate divergence, and the reason `to_int!` exists for callers who
395    /// want the failure loudly.
396    #[test]
397    fn to_int_is_nil_on_garbage_rather_than_zero() {
398        assert_eq!(i("to_int(\"42\")"), 42);
399        assert!(
400            matches!(eval("to_int(\"banana\")"), Value::Nil),
401            "Ruby would say 0 here; a falsy nil cannot be mistaken for a result"
402        );
403        assert!(
404            matches!(eval("to_int(\"0\")"), Value::Int(0)),
405            "and a real 0 is still a real 0 — the two must stay distinguishable"
406        );
407    }
408
409    #[test]
410    fn to_int_bang_raises_on_garbage() {
411        assert_eq!(i("to_int!(\"42\")"), 42);
412        let err = crate::run("to_int!(\"banana\")").expect_err("must raise");
413        assert!(err.to_string().contains("banana"), "must name it: {err}");
414    }
415
416    #[test]
417    fn numeric_conversions_and_abs() {
418        assert_eq!(i("to_int(3.9)"), 3);
419        assert_eq!(i("abs(0 - 5)"), 5);
420        assert!(matches!(eval("to_float(\"1.5\")"), Value::Float(_)));
421        assert!(matches!(eval("to_float(\"nope\")"), Value::Nil));
422    }
423
424    /// A wrong-typed argument is a typed error, not a silent coercion.
425    #[test]
426    fn a_non_string_argument_is_a_type_error() {
427        assert!(crate::run("upcase([1, 2])").is_err());
428        assert!(crate::run("join(\"not a list\", \",\")").is_err());
429    }
430}
blue_lang_runtime/stdlib.rs

blue_lang_runtime/
stdlib.rs
