seqc/
builtins.rs

1//! Built-in word signatures for Seq
2//!
3//! Defines the stack effects for all runtime built-in operations.
4//!
5//! Uses declarative macros to minimize boilerplate. The `builtin!` macro
6//! supports a Forth-like notation: `(a Type1 Type2 -- a Type3)` where:
7//! - `a` is the row variable (representing "rest of stack")
8//! - Concrete types: `Int`, `String`, `Float`
9//! - Type variables: single uppercase letters like `T`, `U`, `V`
10
11use crate::types::{Effect, SideEffect, StackType, Type};
12use std::collections::HashMap;
13use std::sync::LazyLock;
14
15/// Convert a type token to a Type expression
16macro_rules! ty {
17    (Int) => {
18        Type::Int
19    };
20    (Bool) => {
21        Type::Bool
22    };
23    (String) => {
24        Type::String
25    };
26    (Float) => {
27        Type::Float
28    };
29    (Symbol) => {
30        Type::Symbol
31    };
32    (Channel) => {
33        Type::Channel
34    };
35    // Single uppercase letter = type variable
36    (T) => {
37        Type::Var("T".to_string())
38    };
39    (U) => {
40        Type::Var("U".to_string())
41    };
42    (V) => {
43        Type::Var("V".to_string())
44    };
45    (W) => {
46        Type::Var("W".to_string())
47    };
48    (K) => {
49        Type::Var("K".to_string())
50    };
51    (M) => {
52        Type::Var("M".to_string())
53    };
54    (Q) => {
55        Type::Var("Q".to_string())
56    };
57    // Multi-char type variables (T1, T2, etc.)
58    (T1) => {
59        Type::Var("T1".to_string())
60    };
61    (T2) => {
62        Type::Var("T2".to_string())
63    };
64    (T3) => {
65        Type::Var("T3".to_string())
66    };
67    (T4) => {
68        Type::Var("T4".to_string())
69    };
70    (V2) => {
71        Type::Var("V2".to_string())
72    };
73    (M2) => {
74        Type::Var("M2".to_string())
75    };
76    (Acc) => {
77        Type::Var("Acc".to_string())
78    };
79}
80
81/// Build a stack type from row variable 'a' plus pushed types
82macro_rules! stack {
83    // Just the row variable
84    (a) => {
85        StackType::RowVar("a".to_string())
86    };
87    // Row variable with one type pushed
88    (a $t1:tt) => {
89        StackType::RowVar("a".to_string()).push(ty!($t1))
90    };
91    // Row variable with two types pushed
92    (a $t1:tt $t2:tt) => {
93        StackType::RowVar("a".to_string())
94            .push(ty!($t1))
95            .push(ty!($t2))
96    };
97    // Row variable with three types pushed
98    (a $t1:tt $t2:tt $t3:tt) => {
99        StackType::RowVar("a".to_string())
100            .push(ty!($t1))
101            .push(ty!($t2))
102            .push(ty!($t3))
103    };
104    // Row variable with four types pushed
105    (a $t1:tt $t2:tt $t3:tt $t4:tt) => {
106        StackType::RowVar("a".to_string())
107            .push(ty!($t1))
108            .push(ty!($t2))
109            .push(ty!($t3))
110            .push(ty!($t4))
111    };
112    // Row variable with five types pushed
113    (a $t1:tt $t2:tt $t3:tt $t4:tt $t5:tt) => {
114        StackType::RowVar("a".to_string())
115            .push(ty!($t1))
116            .push(ty!($t2))
117            .push(ty!($t3))
118            .push(ty!($t4))
119            .push(ty!($t5))
120    };
121    // Row variable 'b' (used in some signatures)
122    (b) => {
123        StackType::RowVar("b".to_string())
124    };
125    (b $t1:tt) => {
126        StackType::RowVar("b".to_string()).push(ty!($t1))
127    };
128    (b $t1:tt $t2:tt) => {
129        StackType::RowVar("b".to_string())
130            .push(ty!($t1))
131            .push(ty!($t2))
132    };
133}
134
135/// Define a builtin signature with Forth-like stack effect notation
136///
137/// Usage: `builtin!(sigs, "name", (a Type1 Type2 -- a Type3));`
138macro_rules! builtin {
139    // (a -- a)
140    ($sigs:ident, $name:expr, (a -- a)) => {
141        $sigs.insert($name.to_string(), Effect::new(stack!(a), stack!(a)));
142    };
143    // (a -- a T)
144    ($sigs:ident, $name:expr, (a -- a $o1:tt)) => {
145        $sigs.insert($name.to_string(), Effect::new(stack!(a), stack!(a $o1)));
146    };
147    // (a -- a T U)
148    ($sigs:ident, $name:expr, (a -- a $o1:tt $o2:tt)) => {
149        $sigs.insert($name.to_string(), Effect::new(stack!(a), stack!(a $o1 $o2)));
150    };
151    // (a T -- a)
152    ($sigs:ident, $name:expr, (a $i1:tt -- a)) => {
153        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1), stack!(a)));
154    };
155    // (a T -- a U)
156    ($sigs:ident, $name:expr, (a $i1:tt -- a $o1:tt)) => {
157        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1), stack!(a $o1)));
158    };
159    // (a T -- a U V)
160    ($sigs:ident, $name:expr, (a $i1:tt -- a $o1:tt $o2:tt)) => {
161        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1), stack!(a $o1 $o2)));
162    };
163    // (a T U -- a)
164    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt -- a)) => {
165        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2), stack!(a)));
166    };
167    // (a T U -- a V)
168    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt -- a $o1:tt)) => {
169        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2), stack!(a $o1)));
170    };
171    // (a T U -- a V W)
172    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt -- a $o1:tt $o2:tt)) => {
173        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2), stack!(a $o1 $o2)));
174    };
175    // (a T U -- a V W X)
176    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt -- a $o1:tt $o2:tt $o3:tt)) => {
177        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2), stack!(a $o1 $o2 $o3)));
178    };
179    // (a T U -- a V W X Y)
180    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt -- a $o1:tt $o2:tt $o3:tt $o4:tt)) => {
181        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2), stack!(a $o1 $o2 $o3 $o4)));
182    };
183    // (a T U V -- a)
184    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt -- a)) => {
185        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3), stack!(a)));
186    };
187    // (a T U V -- a W)
188    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt -- a $o1:tt)) => {
189        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3), stack!(a $o1)));
190    };
191    // (a T U V -- a W X)
192    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt -- a $o1:tt $o2:tt)) => {
193        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3), stack!(a $o1 $o2)));
194    };
195    // (a T U V -- a W X Y)
196    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt -- a $o1:tt $o2:tt $o3:tt)) => {
197        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3), stack!(a $o1 $o2 $o3)));
198    };
199    // (a T U V W -- a X)
200    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt $i4:tt -- a $o1:tt)) => {
201        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3 $i4), stack!(a $o1)));
202    };
203    // (a T U V W X -- a Y)
204    ($sigs:ident, $name:expr, (a $i1:tt $i2:tt $i3:tt $i4:tt $i5:tt -- a $o1:tt)) => {
205        $sigs.insert($name.to_string(), Effect::new(stack!(a $i1 $i2 $i3 $i4 $i5), stack!(a $o1)));
206    };
207}
208
209/// Define multiple builtins with the same signature
210/// Note: Can't use a generic macro due to tt repetition issues, so we use specific helpers
211macro_rules! builtins_int_int_to_int {
212    ($sigs:ident, $($name:expr),+ $(,)?) => {
213        $(
214            builtin!($sigs, $name, (a Int Int -- a Int));
215        )+
216    };
217}
218
219macro_rules! builtins_int_int_to_bool {
220    ($sigs:ident, $($name:expr),+ $(,)?) => {
221        $(
222            builtin!($sigs, $name, (a Int Int -- a Bool));
223        )+
224    };
225}
226
227macro_rules! builtins_bool_bool_to_bool {
228    ($sigs:ident, $($name:expr),+ $(,)?) => {
229        $(
230            builtin!($sigs, $name, (a Bool Bool -- a Bool));
231        )+
232    };
233}
234
235macro_rules! builtins_int_to_int {
236    ($sigs:ident, $($name:expr),+ $(,)?) => {
237        $(
238            builtin!($sigs, $name, (a Int -- a Int));
239        )+
240    };
241}
242
243macro_rules! builtins_string_to_string {
244    ($sigs:ident, $($name:expr),+ $(,)?) => {
245        $(
246            builtin!($sigs, $name, (a String -- a String));
247        )+
248    };
249}
250
251macro_rules! builtins_float_float_to_float {
252    ($sigs:ident, $($name:expr),+ $(,)?) => {
253        $(
254            builtin!($sigs, $name, (a Float Float -- a Float));
255        )+
256    };
257}
258
259macro_rules! builtins_float_float_to_bool {
260    ($sigs:ident, $($name:expr),+ $(,)?) => {
261        $(
262            builtin!($sigs, $name, (a Float Float -- a Bool));
263        )+
264    };
265}
266
267/// Get the stack effect signature for a built-in word
268pub fn builtin_signature(name: &str) -> Option<Effect> {
269    let signatures = builtin_signatures();
270    signatures.get(name).cloned()
271}
272
273/// Get all built-in word signatures
274pub fn builtin_signatures() -> HashMap<String, Effect> {
275    let mut sigs = HashMap::new();
276
277    // =========================================================================
278    // I/O Operations
279    // =========================================================================
280
281    builtin!(sigs, "io.write", (a String -- a)); // Write without newline
282    builtin!(sigs, "io.write-line", (a String -- a));
283    builtin!(sigs, "io.read-line", (a -- a String Bool)); // Returns line + success flag
284    builtin!(sigs, "io.read-line+", (a -- a String Int)); // DEPRECATED: use io.read-line instead
285    builtin!(sigs, "io.read-n", (a Int -- a String Int)); // Read N bytes, returns bytes + status
286
287    // =========================================================================
288    // Command-line Arguments
289    // =========================================================================
290
291    builtin!(sigs, "args.count", (a -- a Int));
292    builtin!(sigs, "args.at", (a Int -- a String));
293
294    // =========================================================================
295    // File Operations
296    // =========================================================================
297
298    builtin!(sigs, "file.slurp", (a String -- a String Bool)); // returns (content success) - errors are values
299    builtin!(sigs, "file.exists?", (a String -- a Bool));
300    builtin!(sigs, "file.spit", (a String String -- a Bool)); // (content path -- success)
301    builtin!(sigs, "file.append", (a String String -- a Bool)); // (content path -- success)
302    builtin!(sigs, "file.delete", (a String -- a Bool));
303    builtin!(sigs, "file.size", (a String -- a Int Bool)); // (path -- size success)
304
305    // Directory operations
306    builtin!(sigs, "dir.exists?", (a String -- a Bool));
307    builtin!(sigs, "dir.make", (a String -- a Bool));
308    builtin!(sigs, "dir.delete", (a String -- a Bool));
309    builtin!(sigs, "dir.list", (a String -- a V Bool)); // V = List variant
310
311    // file.for-each-line+: Complex quotation type - defined manually
312    sigs.insert(
313        "file.for-each-line+".to_string(),
314        Effect::new(
315            StackType::RowVar("a".to_string())
316                .push(Type::String)
317                .push(Type::Quotation(Box::new(Effect::new(
318                    StackType::RowVar("a".to_string()).push(Type::String),
319                    StackType::RowVar("a".to_string()),
320                )))),
321            StackType::RowVar("a".to_string())
322                .push(Type::String)
323                .push(Type::Bool),
324        ),
325    );
326
327    // =========================================================================
328    // Type Conversions
329    // =========================================================================
330
331    builtin!(sigs, "int->string", (a Int -- a String));
332    builtin!(sigs, "int->float", (a Int -- a Float));
333    builtin!(sigs, "float->int", (a Float -- a Int));
334    builtin!(sigs, "float->string", (a Float -- a String));
335    builtin!(sigs, "string->int", (a String -- a Int Bool)); // value + success flag
336    builtin!(sigs, "string->float", (a String -- a Float Bool)); // value + success flag
337    builtin!(sigs, "char->string", (a Int -- a String));
338    builtin!(sigs, "symbol->string", (a Symbol -- a String));
339    builtin!(sigs, "string->symbol", (a String -- a Symbol));
340
341    // =========================================================================
342    // Integer Arithmetic ( a Int Int -- a Int )
343    // =========================================================================
344
345    builtins_int_int_to_int!(sigs, "i.add", "i.subtract", "i.multiply");
346    builtins_int_int_to_int!(sigs, "i.+", "i.-", "i.*");
347
348    // Division operations return ( a Int Int -- a Int Bool ) for error handling
349    builtin!(sigs, "i.divide", (a Int Int -- a Int Bool));
350    builtin!(sigs, "i.modulo", (a Int Int -- a Int Bool));
351    builtin!(sigs, "i./", (a Int Int -- a Int Bool));
352    builtin!(sigs, "i.%", (a Int Int -- a Int Bool));
353
354    // =========================================================================
355    // Integer Comparison ( a Int Int -- a Bool )
356    // =========================================================================
357
358    builtins_int_int_to_bool!(sigs, "i.=", "i.<", "i.>", "i.<=", "i.>=", "i.<>");
359    builtins_int_int_to_bool!(sigs, "i.eq", "i.lt", "i.gt", "i.lte", "i.gte", "i.neq");
360
361    // =========================================================================
362    // Boolean Operations ( a Bool Bool -- a Bool )
363    // =========================================================================
364
365    builtins_bool_bool_to_bool!(sigs, "and", "or");
366    builtin!(sigs, "not", (a Bool -- a Bool));
367
368    // =========================================================================
369    // Bitwise Operations
370    // =========================================================================
371
372    builtins_int_int_to_int!(sigs, "band", "bor", "bxor", "shl", "shr");
373    builtins_int_to_int!(sigs, "bnot", "popcount", "clz", "ctz");
374    builtin!(sigs, "int-bits", (a -- a Int));
375
376    // =========================================================================
377    // Stack Operations (Polymorphic)
378    // =========================================================================
379
380    builtin!(sigs, "dup", (a T -- a T T));
381    builtin!(sigs, "drop", (a T -- a));
382    builtin!(sigs, "swap", (a T U -- a U T));
383    builtin!(sigs, "over", (a T U -- a T U T));
384    builtin!(sigs, "rot", (a T U V -- a U V T));
385    builtin!(sigs, "nip", (a T U -- a U));
386    builtin!(sigs, "tuck", (a T U -- a U T U));
387    builtin!(sigs, "2dup", (a T U -- a T U T U));
388    builtin!(sigs, "3drop", (a T U V -- a));
389
390    // pick and roll: Type approximations (see detailed comments below)
391    // pick: ( ..a T Int -- ..a T T ) - copies value at depth n to top
392    builtin!(sigs, "pick", (a T Int -- a T T));
393    // roll: ( ..a T Int -- ..a T ) - rotates n+1 items, bringing depth n to top
394    builtin!(sigs, "roll", (a T Int -- a T));
395
396    // =========================================================================
397    // Aux Stack Operations (word-local temporary storage)
398    // Note: actual aux stack effects are handled specially by the typechecker.
399    // These signatures describe only the main stack effects.
400    // =========================================================================
401
402    builtin!(sigs, ">aux", (a T -- a));
403    builtin!(sigs, "aux>", (a -- a T));
404
405    // =========================================================================
406    // Channel Operations (CSP-style concurrency)
407    // Errors are values, not crashes - all ops return success flags
408    // =========================================================================
409
410    builtin!(sigs, "chan.make", (a -- a Channel));
411    builtin!(sigs, "chan.send", (a T Channel -- a Bool)); // returns success flag
412    builtin!(sigs, "chan.receive", (a Channel -- a T Bool)); // returns value and success flag
413    builtin!(sigs, "chan.close", (a Channel -- a));
414    builtin!(sigs, "chan.yield", (a - -a));
415
416    // =========================================================================
417    // Quotation/Control Flow Operations
418    // =========================================================================
419
420    // call: Polymorphic - accepts Quotation or Closure
421    // Uses type variable Q to represent "something callable"
422    sigs.insert(
423        "call".to_string(),
424        Effect::new(
425            StackType::RowVar("a".to_string()).push(Type::Var("Q".to_string())),
426            StackType::RowVar("b".to_string()),
427        ),
428    );
429
430    // cond: Multi-way conditional (variable arity)
431    sigs.insert(
432        "cond".to_string(),
433        Effect::new(
434            StackType::RowVar("a".to_string()),
435            StackType::RowVar("b".to_string()),
436        ),
437    );
438
439    // strand.spawn: ( a Quotation -- a Int ) - spawn a concurrent strand
440    // The quotation can have any stack effect - it runs independently
441    sigs.insert(
442        "strand.spawn".to_string(),
443        Effect::new(
444            StackType::RowVar("a".to_string()).push(Type::Quotation(Box::new(Effect::new(
445                StackType::RowVar("spawn_in".to_string()),
446                StackType::RowVar("spawn_out".to_string()),
447            )))),
448            StackType::RowVar("a".to_string()).push(Type::Int),
449        ),
450    );
451
452    // strand.weave: ( a Quotation -- a handle ) - create a woven strand (generator)
453    // The quotation receives (WeaveCtx, first_resume_value) and must thread WeaveCtx through.
454    // Returns a handle (WeaveCtx) for use with strand.resume.
455    sigs.insert(
456        "strand.weave".to_string(),
457        Effect::new(
458            StackType::RowVar("a".to_string()).push(Type::Quotation(Box::new(Effect::new(
459                StackType::RowVar("weave_in".to_string()),
460                StackType::RowVar("weave_out".to_string()),
461            )))),
462            StackType::RowVar("a".to_string()).push(Type::Var("handle".to_string())),
463        ),
464    );
465
466    // strand.resume: ( a handle b -- a handle b Bool ) - resume weave with value
467    // Takes handle and value to send, returns (handle, yielded_value, has_more)
468    sigs.insert(
469        "strand.resume".to_string(),
470        Effect::new(
471            StackType::RowVar("a".to_string())
472                .push(Type::Var("handle".to_string()))
473                .push(Type::Var("b".to_string())),
474            StackType::RowVar("a".to_string())
475                .push(Type::Var("handle".to_string()))
476                .push(Type::Var("b".to_string()))
477                .push(Type::Bool),
478        ),
479    );
480
481    // yield: ( a ctx b -- a ctx b | Yield b ) - yield value and receive resume value
482    // The WeaveCtx must be passed explicitly and threaded through.
483    // The Yield effect indicates this word produces yield semantics.
484    sigs.insert(
485        "yield".to_string(),
486        Effect::with_effects(
487            StackType::RowVar("a".to_string())
488                .push(Type::Var("ctx".to_string()))
489                .push(Type::Var("b".to_string())),
490            StackType::RowVar("a".to_string())
491                .push(Type::Var("ctx".to_string()))
492                .push(Type::Var("b".to_string())),
493            vec![SideEffect::Yield(Box::new(Type::Var("b".to_string())))],
494        ),
495    );
496
497    // strand.weave-cancel: ( a handle -- a ) - cancel a weave and release its resources
498    // Use this to clean up a weave that won't be resumed to completion.
499    // This prevents resource leaks from abandoned weaves.
500    sigs.insert(
501        "strand.weave-cancel".to_string(),
502        Effect::new(
503            StackType::RowVar("a".to_string()).push(Type::Var("handle".to_string())),
504            StackType::RowVar("a".to_string()),
505        ),
506    );
507
508    // =========================================================================
509    // TCP Operations
510    // =========================================================================
511
512    // TCP operations return Bool for error handling
513    builtin!(sigs, "tcp.listen", (a Int -- a Int Bool));
514    builtin!(sigs, "tcp.accept", (a Int -- a Int Bool));
515    builtin!(sigs, "tcp.read", (a Int -- a String Bool));
516    builtin!(sigs, "tcp.write", (a String Int -- a Bool));
517    builtin!(sigs, "tcp.close", (a Int -- a Bool));
518
519    // =========================================================================
520    // OS Operations
521    // =========================================================================
522
523    builtin!(sigs, "os.getenv", (a String -- a String Bool));
524    builtin!(sigs, "os.home-dir", (a -- a String Bool));
525    builtin!(sigs, "os.current-dir", (a -- a String Bool));
526    builtin!(sigs, "os.path-exists", (a String -- a Bool));
527    builtin!(sigs, "os.path-is-file", (a String -- a Bool));
528    builtin!(sigs, "os.path-is-dir", (a String -- a Bool));
529    builtin!(sigs, "os.path-join", (a String String -- a String));
530    builtin!(sigs, "os.path-parent", (a String -- a String Bool));
531    builtin!(sigs, "os.path-filename", (a String -- a String Bool));
532    builtin!(sigs, "os.exit", (a Int -- a)); // Never returns, but typed as identity
533    builtin!(sigs, "os.name", (a -- a String));
534    builtin!(sigs, "os.arch", (a -- a String));
535
536    // =========================================================================
537    // Signal Handling (Unix signals)
538    // =========================================================================
539
540    builtin!(sigs, "signal.trap", (a Int -- a));
541    builtin!(sigs, "signal.received?", (a Int -- a Bool));
542    builtin!(sigs, "signal.pending?", (a Int -- a Bool));
543    builtin!(sigs, "signal.default", (a Int -- a));
544    builtin!(sigs, "signal.ignore", (a Int -- a));
545    builtin!(sigs, "signal.clear", (a Int -- a));
546    // Signal constants (platform-correct values)
547    builtin!(sigs, "signal.SIGINT", (a -- a Int));
548    builtin!(sigs, "signal.SIGTERM", (a -- a Int));
549    builtin!(sigs, "signal.SIGHUP", (a -- a Int));
550    builtin!(sigs, "signal.SIGPIPE", (a -- a Int));
551    builtin!(sigs, "signal.SIGUSR1", (a -- a Int));
552    builtin!(sigs, "signal.SIGUSR2", (a -- a Int));
553    builtin!(sigs, "signal.SIGCHLD", (a -- a Int));
554    builtin!(sigs, "signal.SIGALRM", (a -- a Int));
555    builtin!(sigs, "signal.SIGCONT", (a -- a Int));
556
557    // =========================================================================
558    // Terminal Operations (raw mode, character I/O, dimensions)
559    // =========================================================================
560
561    builtin!(sigs, "terminal.raw-mode", (a Bool -- a));
562    builtin!(sigs, "terminal.read-char", (a -- a Int));
563    builtin!(sigs, "terminal.read-char?", (a -- a Int));
564    builtin!(sigs, "terminal.width", (a -- a Int));
565    builtin!(sigs, "terminal.height", (a -- a Int));
566    builtin!(sigs, "terminal.flush", (a - -a));
567
568    // =========================================================================
569    // String Operations
570    // =========================================================================
571
572    builtin!(sigs, "string.concat", (a String String -- a String));
573    builtin!(sigs, "string.length", (a String -- a Int));
574    builtin!(sigs, "string.byte-length", (a String -- a Int));
575    builtin!(sigs, "string.char-at", (a String Int -- a Int));
576    builtin!(sigs, "string.substring", (a String Int Int -- a String));
577    builtin!(sigs, "string.find", (a String String -- a Int));
578    builtin!(sigs, "string.split", (a String String -- a V)); // Returns Variant (list)
579    builtin!(sigs, "string.contains", (a String String -- a Bool));
580    builtin!(sigs, "string.starts-with", (a String String -- a Bool));
581    builtin!(sigs, "string.empty?", (a String -- a Bool));
582    builtin!(sigs, "string.equal?", (a String String -- a Bool));
583
584    // Symbol operations
585    builtin!(sigs, "symbol.=", (a Symbol Symbol -- a Bool));
586
587    // String transformations
588    builtins_string_to_string!(
589        sigs,
590        "string.trim",
591        "string.chomp",
592        "string.to-upper",
593        "string.to-lower",
594        "string.json-escape"
595    );
596
597    // =========================================================================
598    // Encoding Operations
599    // =========================================================================
600
601    builtin!(sigs, "encoding.base64-encode", (a String -- a String));
602    builtin!(sigs, "encoding.base64-decode", (a String -- a String Bool));
603    builtin!(sigs, "encoding.base64url-encode", (a String -- a String));
604    builtin!(sigs, "encoding.base64url-decode", (a String -- a String Bool));
605    builtin!(sigs, "encoding.hex-encode", (a String -- a String));
606    builtin!(sigs, "encoding.hex-decode", (a String -- a String Bool));
607
608    // =========================================================================
609    // Crypto Operations
610    // =========================================================================
611
612    builtin!(sigs, "crypto.sha256", (a String -- a String));
613    builtin!(sigs, "crypto.hmac-sha256", (a String String -- a String));
614    builtin!(sigs, "crypto.constant-time-eq", (a String String -- a Bool));
615    builtin!(sigs, "crypto.random-bytes", (a Int -- a String));
616    builtin!(sigs, "crypto.random-int", (a Int Int -- a Int));
617    builtin!(sigs, "crypto.uuid4", (a -- a String));
618    builtin!(sigs, "crypto.aes-gcm-encrypt", (a String String -- a String Bool));
619    builtin!(sigs, "crypto.aes-gcm-decrypt", (a String String -- a String Bool));
620    builtin!(sigs, "crypto.pbkdf2-sha256", (a String String Int -- a String Bool));
621    builtin!(sigs, "crypto.ed25519-keypair", (a -- a String String));
622    builtin!(sigs, "crypto.ed25519-sign", (a String String -- a String Bool));
623    builtin!(sigs, "crypto.ed25519-verify", (a String String String -- a Bool));
624
625    // =========================================================================
626    // HTTP Client Operations
627    // =========================================================================
628
629    builtin!(sigs, "http.get", (a String -- a M));
630    builtin!(sigs, "http.post", (a String String String -- a M));
631    builtin!(sigs, "http.put", (a String String String -- a M));
632    builtin!(sigs, "http.delete", (a String -- a M));
633
634    // =========================================================================
635    // Regular Expression Operations
636    // =========================================================================
637
638    // Regex operations return Bool for error handling (invalid regex)
639    builtin!(sigs, "regex.match?", (a String String -- a Bool));
640    builtin!(sigs, "regex.find", (a String String -- a String Bool));
641    builtin!(sigs, "regex.find-all", (a String String -- a V Bool));
642    builtin!(sigs, "regex.replace", (a String String String -- a String Bool));
643    builtin!(sigs, "regex.replace-all", (a String String String -- a String Bool));
644    builtin!(sigs, "regex.captures", (a String String -- a V Bool));
645    builtin!(sigs, "regex.split", (a String String -- a V Bool));
646    builtin!(sigs, "regex.valid?", (a String -- a Bool));
647
648    // =========================================================================
649    // Compression Operations
650    // =========================================================================
651
652    builtin!(sigs, "compress.gzip", (a String -- a String Bool));
653    builtin!(sigs, "compress.gzip-level", (a String Int -- a String Bool));
654    builtin!(sigs, "compress.gunzip", (a String -- a String Bool));
655    builtin!(sigs, "compress.zstd", (a String -- a String Bool));
656    builtin!(sigs, "compress.zstd-level", (a String Int -- a String Bool));
657    builtin!(sigs, "compress.unzstd", (a String -- a String Bool));
658
659    // =========================================================================
660    // Variant Operations
661    // =========================================================================
662
663    builtin!(sigs, "variant.field-count", (a V -- a Int));
664    builtin!(sigs, "variant.tag", (a V -- a Symbol));
665    builtin!(sigs, "variant.field-at", (a V Int -- a T));
666    builtin!(sigs, "variant.append", (a V T -- a V2));
667    builtin!(sigs, "variant.last", (a V -- a T));
668    builtin!(sigs, "variant.init", (a V -- a V2));
669
670    // Type-safe variant constructors with fixed arity (symbol tags for SON support)
671    builtin!(sigs, "variant.make-0", (a Symbol -- a V));
672    builtin!(sigs, "variant.make-1", (a T1 Symbol -- a V));
673    builtin!(sigs, "variant.make-2", (a T1 T2 Symbol -- a V));
674    builtin!(sigs, "variant.make-3", (a T1 T2 T3 Symbol -- a V));
675    builtin!(sigs, "variant.make-4", (a T1 T2 T3 T4 Symbol -- a V));
676    // variant.make-5 through variant.make-12 defined manually (macro only supports up to 5 inputs)
677    for n in 5..=12 {
678        let mut input = StackType::RowVar("a".to_string());
679        for i in 1..=n {
680            input = input.push(Type::Var(format!("T{}", i)));
681        }
682        input = input.push(Type::Symbol);
683        let output = StackType::RowVar("a".to_string()).push(Type::Var("V".to_string()));
684        sigs.insert(format!("variant.make-{}", n), Effect::new(input, output));
685    }
686
687    // Aliases for dynamic variant construction (SON-friendly names)
688    builtin!(sigs, "wrap-0", (a Symbol -- a V));
689    builtin!(sigs, "wrap-1", (a T1 Symbol -- a V));
690    builtin!(sigs, "wrap-2", (a T1 T2 Symbol -- a V));
691    builtin!(sigs, "wrap-3", (a T1 T2 T3 Symbol -- a V));
692    builtin!(sigs, "wrap-4", (a T1 T2 T3 T4 Symbol -- a V));
693    // wrap-5 through wrap-12 defined manually
694    for n in 5..=12 {
695        let mut input = StackType::RowVar("a".to_string());
696        for i in 1..=n {
697            input = input.push(Type::Var(format!("T{}", i)));
698        }
699        input = input.push(Type::Symbol);
700        let output = StackType::RowVar("a".to_string()).push(Type::Var("V".to_string()));
701        sigs.insert(format!("wrap-{}", n), Effect::new(input, output));
702    }
703
704    // =========================================================================
705    // List Operations (Higher-order combinators for Variants)
706    // =========================================================================
707
708    // List construction and access
709    builtin!(sigs, "list.make", (a -- a V));
710    builtin!(sigs, "list.push", (a V T -- a V));
711    builtin!(sigs, "list.push!", (a V T -- a V));
712    builtin!(sigs, "list.get", (a V Int -- a T Bool));
713    builtin!(sigs, "list.set", (a V Int T -- a V Bool));
714
715    builtin!(sigs, "list.length", (a V -- a Int));
716    builtin!(sigs, "list.empty?", (a V -- a Bool));
717
718    // list.map: ( a Variant Quotation -- a Variant )
719    // Quotation: ( b T -- b U )
720    sigs.insert(
721        "list.map".to_string(),
722        Effect::new(
723            StackType::RowVar("a".to_string())
724                .push(Type::Var("V".to_string()))
725                .push(Type::Quotation(Box::new(Effect::new(
726                    StackType::RowVar("b".to_string()).push(Type::Var("T".to_string())),
727                    StackType::RowVar("b".to_string()).push(Type::Var("U".to_string())),
728                )))),
729            StackType::RowVar("a".to_string()).push(Type::Var("V2".to_string())),
730        ),
731    );
732
733    // list.filter: ( a Variant Quotation -- a Variant )
734    // Quotation: ( b T -- b Bool )
735    sigs.insert(
736        "list.filter".to_string(),
737        Effect::new(
738            StackType::RowVar("a".to_string())
739                .push(Type::Var("V".to_string()))
740                .push(Type::Quotation(Box::new(Effect::new(
741                    StackType::RowVar("b".to_string()).push(Type::Var("T".to_string())),
742                    StackType::RowVar("b".to_string()).push(Type::Bool),
743                )))),
744            StackType::RowVar("a".to_string()).push(Type::Var("V2".to_string())),
745        ),
746    );
747
748    // list.fold: ( a Variant init Quotation -- a result )
749    // Quotation: ( b Acc T -- b Acc )
750    sigs.insert(
751        "list.fold".to_string(),
752        Effect::new(
753            StackType::RowVar("a".to_string())
754                .push(Type::Var("V".to_string()))
755                .push(Type::Var("Acc".to_string()))
756                .push(Type::Quotation(Box::new(Effect::new(
757                    StackType::RowVar("b".to_string())
758                        .push(Type::Var("Acc".to_string()))
759                        .push(Type::Var("T".to_string())),
760                    StackType::RowVar("b".to_string()).push(Type::Var("Acc".to_string())),
761                )))),
762            StackType::RowVar("a".to_string()).push(Type::Var("Acc".to_string())),
763        ),
764    );
765
766    // list.each: ( a Variant Quotation -- a )
767    // Quotation: ( b T -- b )
768    sigs.insert(
769        "list.each".to_string(),
770        Effect::new(
771            StackType::RowVar("a".to_string())
772                .push(Type::Var("V".to_string()))
773                .push(Type::Quotation(Box::new(Effect::new(
774                    StackType::RowVar("b".to_string()).push(Type::Var("T".to_string())),
775                    StackType::RowVar("b".to_string()),
776                )))),
777            StackType::RowVar("a".to_string()),
778        ),
779    );
780
781    // =========================================================================
782    // Map Operations (Dictionary with O(1) lookup)
783    // =========================================================================
784
785    builtin!(sigs, "map.make", (a -- a M));
786    builtin!(sigs, "map.get", (a M K -- a V Bool)); // returns (value success) - errors are values, not crashes
787    builtin!(sigs, "map.set", (a M K V -- a M2));
788    builtin!(sigs, "map.has?", (a M K -- a Bool));
789    builtin!(sigs, "map.remove", (a M K -- a M2));
790    builtin!(sigs, "map.keys", (a M -- a V));
791    builtin!(sigs, "map.values", (a M -- a V));
792    builtin!(sigs, "map.size", (a M -- a Int));
793    builtin!(sigs, "map.empty?", (a M -- a Bool));
794
795    // =========================================================================
796    // Float Arithmetic ( a Float Float -- a Float )
797    // =========================================================================
798
799    builtins_float_float_to_float!(sigs, "f.add", "f.subtract", "f.multiply", "f.divide");
800    builtins_float_float_to_float!(sigs, "f.+", "f.-", "f.*", "f./");
801
802    // =========================================================================
803    // Float Comparison ( a Float Float -- a Bool )
804    // =========================================================================
805
806    builtins_float_float_to_bool!(sigs, "f.=", "f.<", "f.>", "f.<=", "f.>=", "f.<>");
807    builtins_float_float_to_bool!(sigs, "f.eq", "f.lt", "f.gt", "f.lte", "f.gte", "f.neq");
808
809    // =========================================================================
810    // Test Framework
811    // =========================================================================
812
813    builtin!(sigs, "test.init", (a String -- a));
814    builtin!(sigs, "test.finish", (a - -a));
815    builtin!(sigs, "test.has-failures", (a -- a Bool));
816    builtin!(sigs, "test.assert", (a Bool -- a));
817    builtin!(sigs, "test.assert-not", (a Bool -- a));
818    builtin!(sigs, "test.assert-eq", (a Int Int -- a));
819    builtin!(sigs, "test.assert-eq-str", (a String String -- a));
820    builtin!(sigs, "test.fail", (a String -- a));
821    builtin!(sigs, "test.pass-count", (a -- a Int));
822    builtin!(sigs, "test.fail-count", (a -- a Int));
823
824    // Time operations
825    builtin!(sigs, "time.now", (a -- a Int));
826    builtin!(sigs, "time.nanos", (a -- a Int));
827    builtin!(sigs, "time.sleep-ms", (a Int -- a));
828
829    // SON serialization
830    builtin!(sigs, "son.dump", (a T -- a String));
831    builtin!(sigs, "son.dump-pretty", (a T -- a String));
832
833    // Stack introspection (for REPL)
834    // stack.dump prints all values and clears the stack
835    sigs.insert(
836        "stack.dump".to_string(),
837        Effect::new(
838            StackType::RowVar("a".to_string()), // Consumes any stack
839            StackType::RowVar("b".to_string()), // Returns empty stack (different row var)
840        ),
841    );
842
843    sigs
844}
845
846/// Get documentation for a built-in word
847pub fn builtin_doc(name: &str) -> Option<&'static str> {
848    BUILTIN_DOCS.get(name).copied()
849}
850
851/// Get all built-in word documentation (cached with LazyLock for performance)
852pub fn builtin_docs() -> &'static HashMap<&'static str, &'static str> {
853    &BUILTIN_DOCS
854}
855
856/// Lazily initialized documentation for all built-in words
857static BUILTIN_DOCS: LazyLock<HashMap<&'static str, &'static str>> = LazyLock::new(|| {
858    let mut docs = HashMap::new();
859
860    // I/O Operations
861    docs.insert(
862        "io.write",
863        "Write a string to stdout without a trailing newline.",
864    );
865    docs.insert(
866        "io.write-line",
867        "Write a string to stdout followed by a newline.",
868    );
869    docs.insert(
870        "io.read-line",
871        "Read a line from stdin. Returns (line, success).",
872    );
873    docs.insert(
874        "io.read-line+",
875        "DEPRECATED: Use io.read-line instead. Read a line from stdin. Returns (line, status_code).",
876    );
877    docs.insert(
878        "io.read-n",
879        "Read N bytes from stdin. Returns (bytes, status_code).",
880    );
881
882    // Command-line Arguments
883    docs.insert("args.count", "Get the number of command-line arguments.");
884    docs.insert("args.at", "Get the command-line argument at index N.");
885
886    // File Operations
887    docs.insert(
888        "file.slurp",
889        "Read entire file contents. Returns (content, success).",
890    );
891    docs.insert("file.exists?", "Check if a file exists at the given path.");
892    docs.insert(
893        "file.spit",
894        "Write string to file (creates or overwrites). Returns success.",
895    );
896    docs.insert(
897        "file.append",
898        "Append string to file (creates if needed). Returns success.",
899    );
900    docs.insert("file.delete", "Delete a file. Returns success.");
901    docs.insert(
902        "file.size",
903        "Get file size in bytes. Returns (size, success).",
904    );
905    docs.insert(
906        "file.for-each-line+",
907        "Execute a quotation for each line in a file.",
908    );
909
910    // Directory Operations
911    docs.insert(
912        "dir.exists?",
913        "Check if a directory exists at the given path.",
914    );
915    docs.insert(
916        "dir.make",
917        "Create a directory (and parent directories if needed). Returns success.",
918    );
919    docs.insert("dir.delete", "Delete an empty directory. Returns success.");
920    docs.insert(
921        "dir.list",
922        "List directory contents. Returns (list-of-names, success).",
923    );
924
925    // Type Conversions
926    docs.insert(
927        "int->string",
928        "Convert an integer to its string representation.",
929    );
930    docs.insert(
931        "int->float",
932        "Convert an integer to a floating-point number.",
933    );
934    docs.insert("float->int", "Truncate a float to an integer.");
935    docs.insert(
936        "float->string",
937        "Convert a float to its string representation.",
938    );
939    docs.insert(
940        "string->int",
941        "Parse a string as an integer. Returns (value, success).",
942    );
943    docs.insert(
944        "string->float",
945        "Parse a string as a float. Returns (value, success).",
946    );
947    docs.insert(
948        "char->string",
949        "Convert a Unicode codepoint to a single-character string.",
950    );
951    docs.insert(
952        "symbol->string",
953        "Convert a symbol to its string representation.",
954    );
955    docs.insert("string->symbol", "Intern a string as a symbol.");
956
957    // Integer Arithmetic
958    docs.insert("i.add", "Add two integers.");
959    docs.insert("i.subtract", "Subtract second integer from first.");
960    docs.insert("i.multiply", "Multiply two integers.");
961    docs.insert("i.divide", "Integer division (truncates toward zero).");
962    docs.insert("i.modulo", "Integer modulo (remainder after division).");
963    docs.insert("i.+", "Add two integers.");
964    docs.insert("i.-", "Subtract second integer from first.");
965    docs.insert("i.*", "Multiply two integers.");
966    docs.insert("i./", "Integer division (truncates toward zero).");
967    docs.insert("i.%", "Integer modulo (remainder after division).");
968
969    // Integer Comparison
970    docs.insert("i.=", "Test if two integers are equal.");
971    docs.insert("i.<", "Test if first integer is less than second.");
972    docs.insert("i.>", "Test if first integer is greater than second.");
973    docs.insert(
974        "i.<=",
975        "Test if first integer is less than or equal to second.",
976    );
977    docs.insert(
978        "i.>=",
979        "Test if first integer is greater than or equal to second.",
980    );
981    docs.insert("i.<>", "Test if two integers are not equal.");
982    docs.insert("i.eq", "Test if two integers are equal.");
983    docs.insert("i.lt", "Test if first integer is less than second.");
984    docs.insert("i.gt", "Test if first integer is greater than second.");
985    docs.insert(
986        "i.lte",
987        "Test if first integer is less than or equal to second.",
988    );
989    docs.insert(
990        "i.gte",
991        "Test if first integer is greater than or equal to second.",
992    );
993    docs.insert("i.neq", "Test if two integers are not equal.");
994
995    // Boolean Operations
996    docs.insert("and", "Logical AND of two booleans.");
997    docs.insert("or", "Logical OR of two booleans.");
998    docs.insert("not", "Logical NOT of a boolean.");
999
1000    // Bitwise Operations
1001    docs.insert("band", "Bitwise AND of two integers.");
1002    docs.insert("bor", "Bitwise OR of two integers.");
1003    docs.insert("bxor", "Bitwise XOR of two integers.");
1004    docs.insert("bnot", "Bitwise NOT (complement) of an integer.");
1005    docs.insert("shl", "Shift left by N bits.");
1006    docs.insert("shr", "Shift right by N bits (arithmetic).");
1007    docs.insert("popcount", "Count the number of set bits.");
1008    docs.insert("clz", "Count leading zeros.");
1009    docs.insert("ctz", "Count trailing zeros.");
1010    docs.insert("int-bits", "Push the bit width of integers (64).");
1011
1012    // Stack Operations
1013    docs.insert("dup", "Duplicate the top stack value.");
1014    docs.insert("drop", "Remove the top stack value.");
1015    docs.insert("swap", "Swap the top two stack values.");
1016    docs.insert("over", "Copy the second value to the top.");
1017    docs.insert("rot", "Rotate the top three values (third to top).");
1018    docs.insert("nip", "Remove the second value from the stack.");
1019    docs.insert("tuck", "Copy the top value below the second.");
1020    docs.insert("2dup", "Duplicate the top two values.");
1021    docs.insert("3drop", "Remove the top three values.");
1022    docs.insert("pick", "Copy the value at depth N to the top.");
1023    docs.insert("roll", "Rotate N+1 items, bringing depth N to top.");
1024
1025    // Aux Stack Operations
1026    docs.insert(
1027        ">aux",
1028        "Move top of stack to word-local aux stack. Must be balanced with aux> before word returns.",
1029    );
1030    docs.insert(
1031        "aux>",
1032        "Move top of aux stack back to main stack. Requires a matching >aux.",
1033    );
1034
1035    // Channel Operations
1036    docs.insert(
1037        "chan.make",
1038        "Create a new channel for inter-strand communication.",
1039    );
1040    docs.insert(
1041        "chan.send",
1042        "Send a value on a channel. Returns success flag.",
1043    );
1044    docs.insert(
1045        "chan.receive",
1046        "Receive a value from a channel. Returns (value, success).",
1047    );
1048    docs.insert("chan.close", "Close a channel.");
1049    docs.insert("chan.yield", "Yield control to the scheduler.");
1050
1051    // Control Flow
1052    docs.insert("call", "Call a quotation or closure.");
1053    docs.insert(
1054        "cond",
1055        "Multi-way conditional: test clauses until one succeeds.",
1056    );
1057
1058    // Concurrency
1059    docs.insert(
1060        "strand.spawn",
1061        "Spawn a concurrent strand. Returns strand ID.",
1062    );
1063    docs.insert(
1064        "strand.weave",
1065        "Create a generator/coroutine. Returns handle.",
1066    );
1067    docs.insert(
1068        "strand.resume",
1069        "Resume a weave with a value. Returns (handle, value, has_more).",
1070    );
1071    docs.insert(
1072        "yield",
1073        "Yield a value from a weave and receive resume value.",
1074    );
1075    docs.insert(
1076        "strand.weave-cancel",
1077        "Cancel a weave and release its resources.",
1078    );
1079
1080    // TCP Operations
1081    docs.insert(
1082        "tcp.listen",
1083        "Start listening on a port. Returns (socket_id, success).",
1084    );
1085    docs.insert(
1086        "tcp.accept",
1087        "Accept a connection. Returns (client_id, success).",
1088    );
1089    docs.insert(
1090        "tcp.read",
1091        "Read data from a socket. Returns (string, success).",
1092    );
1093    docs.insert("tcp.write", "Write data to a socket. Returns success.");
1094    docs.insert("tcp.close", "Close a socket. Returns success.");
1095
1096    // OS Operations
1097    docs.insert(
1098        "os.getenv",
1099        "Get environment variable. Returns (value, exists).",
1100    );
1101    docs.insert(
1102        "os.home-dir",
1103        "Get user's home directory. Returns (path, success).",
1104    );
1105    docs.insert(
1106        "os.current-dir",
1107        "Get current working directory. Returns (path, success).",
1108    );
1109    docs.insert("os.path-exists", "Check if a path exists.");
1110    docs.insert("os.path-is-file", "Check if path is a regular file.");
1111    docs.insert("os.path-is-dir", "Check if path is a directory.");
1112    docs.insert("os.path-join", "Join two path components.");
1113    docs.insert(
1114        "os.path-parent",
1115        "Get parent directory. Returns (path, success).",
1116    );
1117    docs.insert(
1118        "os.path-filename",
1119        "Get filename component. Returns (name, success).",
1120    );
1121    docs.insert("os.exit", "Exit the program with a status code.");
1122    docs.insert(
1123        "os.name",
1124        "Get the operating system name (e.g., \"macos\", \"linux\").",
1125    );
1126    docs.insert(
1127        "os.arch",
1128        "Get the CPU architecture (e.g., \"aarch64\", \"x86_64\").",
1129    );
1130
1131    // Signal Handling
1132    docs.insert(
1133        "signal.trap",
1134        "Trap a signal: set internal flag on receipt instead of default action.",
1135    );
1136    docs.insert(
1137        "signal.received?",
1138        "Check if signal was received and clear the flag. Returns Bool.",
1139    );
1140    docs.insert(
1141        "signal.pending?",
1142        "Check if signal is pending without clearing the flag. Returns Bool.",
1143    );
1144    docs.insert(
1145        "signal.default",
1146        "Restore the default handler for a signal.",
1147    );
1148    docs.insert(
1149        "signal.ignore",
1150        "Ignore a signal entirely (useful for SIGPIPE in servers).",
1151    );
1152    docs.insert(
1153        "signal.clear",
1154        "Clear the pending flag for a signal without checking it.",
1155    );
1156    docs.insert("signal.SIGINT", "SIGINT constant (Ctrl+C interrupt).");
1157    docs.insert("signal.SIGTERM", "SIGTERM constant (termination request).");
1158    docs.insert("signal.SIGHUP", "SIGHUP constant (hangup detected).");
1159    docs.insert("signal.SIGPIPE", "SIGPIPE constant (broken pipe).");
1160    docs.insert(
1161        "signal.SIGUSR1",
1162        "SIGUSR1 constant (user-defined signal 1).",
1163    );
1164    docs.insert(
1165        "signal.SIGUSR2",
1166        "SIGUSR2 constant (user-defined signal 2).",
1167    );
1168    docs.insert("signal.SIGCHLD", "SIGCHLD constant (child status changed).");
1169    docs.insert("signal.SIGALRM", "SIGALRM constant (alarm clock).");
1170    docs.insert("signal.SIGCONT", "SIGCONT constant (continue if stopped).");
1171
1172    // Terminal Operations
1173    docs.insert(
1174        "terminal.raw-mode",
1175        "Enable/disable raw terminal mode. In raw mode: no line buffering, no echo, Ctrl+C read as byte 3.",
1176    );
1177    docs.insert(
1178        "terminal.read-char",
1179        "Read a single byte from stdin (blocking). Returns 0-255 on success, -1 on EOF/error.",
1180    );
1181    docs.insert(
1182        "terminal.read-char?",
1183        "Read a single byte from stdin (non-blocking). Returns 0-255 if available, -1 otherwise.",
1184    );
1185    docs.insert(
1186        "terminal.width",
1187        "Get terminal width in columns. Returns 80 if unknown.",
1188    );
1189    docs.insert(
1190        "terminal.height",
1191        "Get terminal height in rows. Returns 24 if unknown.",
1192    );
1193    docs.insert(
1194        "terminal.flush",
1195        "Flush stdout. Use after writing escape sequences or partial lines.",
1196    );
1197
1198    // String Operations
1199    docs.insert("string.concat", "Concatenate two strings.");
1200    docs.insert("string.length", "Get the character length of a string.");
1201    docs.insert("string.byte-length", "Get the byte length of a string.");
1202    docs.insert(
1203        "string.char-at",
1204        "Get Unicode codepoint at character index.",
1205    );
1206    docs.insert(
1207        "string.substring",
1208        "Extract substring from start index with length.",
1209    );
1210    docs.insert(
1211        "string.find",
1212        "Find substring. Returns index or -1 if not found.",
1213    );
1214    docs.insert("string.split", "Split string by delimiter. Returns a list.");
1215    docs.insert("string.contains", "Check if string contains a substring.");
1216    docs.insert(
1217        "string.starts-with",
1218        "Check if string starts with a prefix.",
1219    );
1220    docs.insert("string.empty?", "Check if string is empty.");
1221    docs.insert("string.equal?", "Check if two strings are equal.");
1222    docs.insert("string.trim", "Remove leading and trailing whitespace.");
1223    docs.insert("string.chomp", "Remove trailing newline.");
1224    docs.insert("string.to-upper", "Convert to uppercase.");
1225    docs.insert("string.to-lower", "Convert to lowercase.");
1226    docs.insert("string.json-escape", "Escape special characters for JSON.");
1227    docs.insert("symbol.=", "Check if two symbols are equal.");
1228
1229    // Encoding Operations
1230    docs.insert(
1231        "encoding.base64-encode",
1232        "Encode a string to Base64 (standard alphabet with padding).",
1233    );
1234    docs.insert(
1235        "encoding.base64-decode",
1236        "Decode a Base64 string. Returns (decoded, success).",
1237    );
1238    docs.insert(
1239        "encoding.base64url-encode",
1240        "Encode to URL-safe Base64 (no padding). Suitable for JWTs and URLs.",
1241    );
1242    docs.insert(
1243        "encoding.base64url-decode",
1244        "Decode URL-safe Base64. Returns (decoded, success).",
1245    );
1246    docs.insert(
1247        "encoding.hex-encode",
1248        "Encode a string to lowercase hexadecimal.",
1249    );
1250    docs.insert(
1251        "encoding.hex-decode",
1252        "Decode a hexadecimal string. Returns (decoded, success).",
1253    );
1254
1255    // Crypto Operations
1256    docs.insert(
1257        "crypto.sha256",
1258        "Compute SHA-256 hash of a string. Returns 64-char hex digest.",
1259    );
1260    docs.insert(
1261        "crypto.hmac-sha256",
1262        "Compute HMAC-SHA256 signature. ( message key -- signature )",
1263    );
1264    docs.insert(
1265        "crypto.constant-time-eq",
1266        "Timing-safe string comparison. Use for comparing signatures/tokens.",
1267    );
1268    docs.insert(
1269        "crypto.random-bytes",
1270        "Generate N cryptographically secure random bytes as hex string.",
1271    );
1272    docs.insert(
1273        "crypto.random-int",
1274        "Generate uniform random integer in [min, max). ( min max -- Int ) Uses rejection sampling to avoid modulo bias.",
1275    );
1276    docs.insert("crypto.uuid4", "Generate a random UUID v4 string.");
1277    docs.insert(
1278        "crypto.aes-gcm-encrypt",
1279        "Encrypt with AES-256-GCM. ( plaintext hex-key -- ciphertext success )",
1280    );
1281    docs.insert(
1282        "crypto.aes-gcm-decrypt",
1283        "Decrypt AES-256-GCM ciphertext. ( ciphertext hex-key -- plaintext success )",
1284    );
1285    docs.insert(
1286        "crypto.pbkdf2-sha256",
1287        "Derive key from password. ( password salt iterations -- hex-key success ) Min 1000 iterations, 100000+ recommended.",
1288    );
1289    docs.insert(
1290        "crypto.ed25519-keypair",
1291        "Generate Ed25519 keypair. ( -- public-key private-key ) Both as 64-char hex strings.",
1292    );
1293    docs.insert(
1294        "crypto.ed25519-sign",
1295        "Sign message with Ed25519 private key. ( message private-key -- signature success ) Signature is 128-char hex.",
1296    );
1297    docs.insert(
1298        "crypto.ed25519-verify",
1299        "Verify Ed25519 signature. ( message signature public-key -- valid )",
1300    );
1301
1302    // HTTP Client Operations
1303    docs.insert(
1304        "http.get",
1305        "HTTP GET request. ( url -- response-map ) Map has status, body, ok, error.",
1306    );
1307    docs.insert(
1308        "http.post",
1309        "HTTP POST request. ( url body content-type -- response-map )",
1310    );
1311    docs.insert(
1312        "http.put",
1313        "HTTP PUT request. ( url body content-type -- response-map )",
1314    );
1315    docs.insert(
1316        "http.delete",
1317        "HTTP DELETE request. ( url -- response-map )",
1318    );
1319
1320    // Regular Expression Operations
1321    docs.insert(
1322        "regex.match?",
1323        "Check if pattern matches anywhere in string. ( text pattern -- bool )",
1324    );
1325    docs.insert(
1326        "regex.find",
1327        "Find first match. ( text pattern -- matched success )",
1328    );
1329    docs.insert(
1330        "regex.find-all",
1331        "Find all matches. ( text pattern -- list success )",
1332    );
1333    docs.insert(
1334        "regex.replace",
1335        "Replace first match. ( text pattern replacement -- result success )",
1336    );
1337    docs.insert(
1338        "regex.replace-all",
1339        "Replace all matches. ( text pattern replacement -- result success )",
1340    );
1341    docs.insert(
1342        "regex.captures",
1343        "Extract capture groups. ( text pattern -- groups success )",
1344    );
1345    docs.insert(
1346        "regex.split",
1347        "Split string by pattern. ( text pattern -- list success )",
1348    );
1349    docs.insert(
1350        "regex.valid?",
1351        "Check if pattern is valid regex. ( pattern -- bool )",
1352    );
1353
1354    // Compression Operations
1355    docs.insert(
1356        "compress.gzip",
1357        "Compress string with gzip. Returns base64-encoded data. ( data -- compressed success )",
1358    );
1359    docs.insert(
1360        "compress.gzip-level",
1361        "Compress with gzip at level 1-9. ( data level -- compressed success )",
1362    );
1363    docs.insert(
1364        "compress.gunzip",
1365        "Decompress gzip data. ( base64-data -- decompressed success )",
1366    );
1367    docs.insert(
1368        "compress.zstd",
1369        "Compress string with zstd. Returns base64-encoded data. ( data -- compressed success )",
1370    );
1371    docs.insert(
1372        "compress.zstd-level",
1373        "Compress with zstd at level 1-22. ( data level -- compressed success )",
1374    );
1375    docs.insert(
1376        "compress.unzstd",
1377        "Decompress zstd data. ( base64-data -- decompressed success )",
1378    );
1379
1380    // Variant Operations
1381    docs.insert(
1382        "variant.field-count",
1383        "Get the number of fields in a variant.",
1384    );
1385    docs.insert(
1386        "variant.tag",
1387        "Get the tag (constructor name) of a variant.",
1388    );
1389    docs.insert("variant.field-at", "Get the field at index N.");
1390    docs.insert(
1391        "variant.append",
1392        "Append a value to a variant (creates new).",
1393    );
1394    docs.insert("variant.last", "Get the last field of a variant.");
1395    docs.insert("variant.init", "Get all fields except the last.");
1396    docs.insert("variant.make-0", "Create a variant with 0 fields.");
1397    docs.insert("variant.make-1", "Create a variant with 1 field.");
1398    docs.insert("variant.make-2", "Create a variant with 2 fields.");
1399    docs.insert("variant.make-3", "Create a variant with 3 fields.");
1400    docs.insert("variant.make-4", "Create a variant with 4 fields.");
1401    docs.insert("variant.make-5", "Create a variant with 5 fields.");
1402    docs.insert("variant.make-6", "Create a variant with 6 fields.");
1403    docs.insert("variant.make-7", "Create a variant with 7 fields.");
1404    docs.insert("variant.make-8", "Create a variant with 8 fields.");
1405    docs.insert("variant.make-9", "Create a variant with 9 fields.");
1406    docs.insert("variant.make-10", "Create a variant with 10 fields.");
1407    docs.insert("variant.make-11", "Create a variant with 11 fields.");
1408    docs.insert("variant.make-12", "Create a variant with 12 fields.");
1409    docs.insert("wrap-0", "Create a variant with 0 fields (alias).");
1410    docs.insert("wrap-1", "Create a variant with 1 field (alias).");
1411    docs.insert("wrap-2", "Create a variant with 2 fields (alias).");
1412    docs.insert("wrap-3", "Create a variant with 3 fields (alias).");
1413    docs.insert("wrap-4", "Create a variant with 4 fields (alias).");
1414    docs.insert("wrap-5", "Create a variant with 5 fields (alias).");
1415    docs.insert("wrap-6", "Create a variant with 6 fields (alias).");
1416    docs.insert("wrap-7", "Create a variant with 7 fields (alias).");
1417    docs.insert("wrap-8", "Create a variant with 8 fields (alias).");
1418    docs.insert("wrap-9", "Create a variant with 9 fields (alias).");
1419    docs.insert("wrap-10", "Create a variant with 10 fields (alias).");
1420    docs.insert("wrap-11", "Create a variant with 11 fields (alias).");
1421    docs.insert("wrap-12", "Create a variant with 12 fields (alias).");
1422
1423    // List Operations
1424    docs.insert("list.make", "Create an empty list.");
1425    docs.insert("list.push", "Push a value onto a list. Returns new list.");
1426    docs.insert(
1427        "list.push!",
1428        "Push a value onto a list in place. Faster than list.push in loops.",
1429    );
1430    docs.insert("list.get", "Get value at index. Returns (value, success).");
1431    docs.insert("list.set", "Set value at index. Returns (list, success).");
1432    docs.insert("list.length", "Get the number of elements in a list.");
1433    docs.insert("list.empty?", "Check if a list is empty.");
1434    docs.insert(
1435        "list.map",
1436        "Apply quotation to each element. Returns new list.",
1437    );
1438    docs.insert("list.filter", "Keep elements where quotation returns true.");
1439    docs.insert("list.fold", "Reduce list with accumulator and quotation.");
1440    docs.insert(
1441        "list.each",
1442        "Execute quotation for each element (side effects).",
1443    );
1444
1445    // Map Operations
1446    docs.insert("map.make", "Create an empty map.");
1447    docs.insert("map.get", "Get value for key. Returns (value, success).");
1448    docs.insert("map.set", "Set key to value. Returns new map.");
1449    docs.insert("map.has?", "Check if map contains a key.");
1450    docs.insert("map.remove", "Remove a key. Returns new map.");
1451    docs.insert("map.keys", "Get all keys as a list.");
1452    docs.insert("map.values", "Get all values as a list.");
1453    docs.insert("map.size", "Get the number of key-value pairs.");
1454    docs.insert("map.empty?", "Check if map is empty.");
1455
1456    // Float Arithmetic
1457    docs.insert("f.add", "Add two floats.");
1458    docs.insert("f.subtract", "Subtract second float from first.");
1459    docs.insert("f.multiply", "Multiply two floats.");
1460    docs.insert("f.divide", "Divide first float by second.");
1461    docs.insert("f.+", "Add two floats.");
1462    docs.insert("f.-", "Subtract second float from first.");
1463    docs.insert("f.*", "Multiply two floats.");
1464    docs.insert("f./", "Divide first float by second.");
1465
1466    // Float Comparison
1467    docs.insert("f.=", "Test if two floats are equal.");
1468    docs.insert("f.<", "Test if first float is less than second.");
1469    docs.insert("f.>", "Test if first float is greater than second.");
1470    docs.insert("f.<=", "Test if first float is less than or equal.");
1471    docs.insert("f.>=", "Test if first float is greater than or equal.");
1472    docs.insert("f.<>", "Test if two floats are not equal.");
1473    docs.insert("f.eq", "Test if two floats are equal.");
1474    docs.insert("f.lt", "Test if first float is less than second.");
1475    docs.insert("f.gt", "Test if first float is greater than second.");
1476    docs.insert("f.lte", "Test if first float is less than or equal.");
1477    docs.insert("f.gte", "Test if first float is greater than or equal.");
1478    docs.insert("f.neq", "Test if two floats are not equal.");
1479
1480    // Test Framework
1481    docs.insert(
1482        "test.init",
1483        "Initialize the test framework with a test name.",
1484    );
1485    docs.insert("test.finish", "Finish testing and print results.");
1486    docs.insert("test.has-failures", "Check if any tests have failed.");
1487    docs.insert("test.assert", "Assert that a boolean is true.");
1488    docs.insert("test.assert-not", "Assert that a boolean is false.");
1489    docs.insert("test.assert-eq", "Assert that two integers are equal.");
1490    docs.insert("test.assert-eq-str", "Assert that two strings are equal.");
1491    docs.insert("test.fail", "Mark a test as failed with a message.");
1492    docs.insert("test.pass-count", "Get the number of passed assertions.");
1493    docs.insert("test.fail-count", "Get the number of failed assertions.");
1494
1495    // Time Operations
1496    docs.insert("time.now", "Get current Unix timestamp in seconds.");
1497    docs.insert(
1498        "time.nanos",
1499        "Get high-resolution monotonic time in nanoseconds.",
1500    );
1501    docs.insert("time.sleep-ms", "Sleep for N milliseconds.");
1502
1503    // Serialization
1504    docs.insert("son.dump", "Serialize any value to SON format (compact).");
1505    docs.insert(
1506        "son.dump-pretty",
1507        "Serialize any value to SON format (pretty-printed).",
1508    );
1509
1510    // Stack Introspection
1511    docs.insert(
1512        "stack.dump",
1513        "Print all stack values and clear the stack (REPL).",
1514    );
1515
1516    docs
1517});
1518
1519#[cfg(test)]
1520mod tests {
1521    use super::*;
1522
1523    #[test]
1524    fn test_builtin_signature_write_line() {
1525        let sig = builtin_signature("io.write-line").unwrap();
1526        // ( ..a String -- ..a )
1527        let (rest, top) = sig.inputs.clone().pop().unwrap();
1528        assert_eq!(top, Type::String);
1529        assert_eq!(rest, StackType::RowVar("a".to_string()));
1530        assert_eq!(sig.outputs, StackType::RowVar("a".to_string()));
1531    }
1532
1533    #[test]
1534    fn test_builtin_signature_i_add() {
1535        let sig = builtin_signature("i.add").unwrap();
1536        // ( ..a Int Int -- ..a Int )
1537        let (rest, top) = sig.inputs.clone().pop().unwrap();
1538        assert_eq!(top, Type::Int);
1539        let (rest2, top2) = rest.pop().unwrap();
1540        assert_eq!(top2, Type::Int);
1541        assert_eq!(rest2, StackType::RowVar("a".to_string()));
1542
1543        let (rest3, top3) = sig.outputs.clone().pop().unwrap();
1544        assert_eq!(top3, Type::Int);
1545        assert_eq!(rest3, StackType::RowVar("a".to_string()));
1546    }
1547
1548    #[test]
1549    fn test_builtin_signature_dup() {
1550        let sig = builtin_signature("dup").unwrap();
1551        // Input: ( ..a T )
1552        assert_eq!(
1553            sig.inputs,
1554            StackType::Cons {
1555                rest: Box::new(StackType::RowVar("a".to_string())),
1556                top: Type::Var("T".to_string())
1557            }
1558        );
1559        // Output: ( ..a T T )
1560        let (rest, top) = sig.outputs.clone().pop().unwrap();
1561        assert_eq!(top, Type::Var("T".to_string()));
1562        let (rest2, top2) = rest.pop().unwrap();
1563        assert_eq!(top2, Type::Var("T".to_string()));
1564        assert_eq!(rest2, StackType::RowVar("a".to_string()));
1565    }
1566
1567    #[test]
1568    fn test_all_builtins_have_signatures() {
1569        let sigs = builtin_signatures();
1570
1571        // Verify all expected builtins have signatures
1572        assert!(sigs.contains_key("io.write-line"));
1573        assert!(sigs.contains_key("io.read-line"));
1574        assert!(sigs.contains_key("int->string"));
1575        assert!(sigs.contains_key("i.add"));
1576        assert!(sigs.contains_key("dup"));
1577        assert!(sigs.contains_key("swap"));
1578        assert!(sigs.contains_key("chan.make"));
1579        assert!(sigs.contains_key("chan.send"));
1580        assert!(sigs.contains_key("chan.receive"));
1581        assert!(
1582            sigs.contains_key("string->float"),
1583            "string->float should be a builtin"
1584        );
1585        assert!(
1586            sigs.contains_key("signal.trap"),
1587            "signal.trap should be a builtin"
1588        );
1589    }
1590
1591    #[test]
1592    fn test_all_docs_have_signatures() {
1593        let sigs = builtin_signatures();
1594        let docs = builtin_docs();
1595
1596        for name in docs.keys() {
1597            assert!(
1598                sigs.contains_key(*name),
1599                "Builtin '{}' has documentation but no signature",
1600                name
1601            );
1602        }
1603    }
1604
1605    #[test]
1606    fn test_all_signatures_have_docs() {
1607        let sigs = builtin_signatures();
1608        let docs = builtin_docs();
1609
1610        for name in sigs.keys() {
1611            assert!(
1612                docs.contains_key(name.as_str()),
1613                "Builtin '{}' has signature but no documentation",
1614                name
1615            );
1616        }
1617    }
1618}
seqc/builtins.rs

seqc/
builtins.rs
