Skip to main content

elly_core/
builtins.rs

1//! Native builtins of the reserved `__` namespace: the [`Builtin`] enum, its
2//! names and arities, and the [`MODULES`] table grouping them into modules.
3//! Running one is the evaluator's (`eval/builtin.rs`).
4
5use crate::sym::{self, Sym};
6
7/// A native builtin operation in the reserved `__` namespace. All are curried.
8// NOTE: keep this enum sorted and documented, this is user-facing docs.
9#[allow(clippy::enum_variant_names)]
10#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
11pub enum Builtin {
12    /// The builtin module `Bool`: the iotas `Bool.false` / `Bool.true` and their logic.
13    Bool,
14
15    /// `Bool.and : (Bool, Bool) -> Bool`
16    BoolAnd,
17
18    /// `Bool.false : Bool`, also the bare `__false`.
19    BoolFalse,
20
21    /// `Bool.not : Bool -> Bool`
22    BoolNot,
23
24    /// `Bool.or : (Bool, Bool) -> Bool`
25    BoolOr,
26
27    /// `Bool.true : Bool`, also the bare `__true`.
28    BoolTrue,
29
30    /// `__eq : (a, b, () -> c, () -> c) -> c`: the first thunk if `a == b`, else the second.
31    ///
32    /// Structural for data, by identity for callables and iterators.
33    Eq,
34
35    /// The builtin module `Err`: raising and catching.
36    Err,
37
38    /// `Err.catch : (e -> a, () -> a) -> a`: runs the thunk; a raised `e` goes to the handler.
39    ///
40    /// Step signals pass through.
41    ErrCatch,
42
43    /// `Err.raise : e -> a`
44    ErrRaise,
45
46    /// The builtin module `Fun`, the prototype of every callable kind. No items yet.
47    Fun,
48
49    /// The builtin module `Int`, the prototype of integers.
50    Int,
51
52    /// `Int.add : (Int, Int) -> Int`
53    IntAdd,
54
55    /// `Int.count : iterable -> Int`: drains it, counting the elements.
56    IntCount,
57
58    /// `Int.divrem : (Int, Int) -> #[Int, Int]`: Euclidean `#[quotient, remainder]`.
59    ///
60    /// Raises `.div_by_zero`.
61    IntDivrem,
62
63    /// `Int.eq : (Int, Int) -> Bool`
64    IntEq,
65
66    /// `Int.ge : (Int, Int) -> Bool`
67    IntGe,
68
69    /// `Int.gt : (Int, Int) -> Bool`
70    IntGt,
71
72    /// `Int.le : (Int, Int) -> Bool`
73    IntLe,
74
75    /// `Int.lt : (Int, Int) -> Bool`
76    IntLt,
77
78    /// `Int.mul : (Int, Int) -> Int`
79    IntMul,
80
81    /// `Int.parse : Str -> Int`: decimal, `0x` or `0b`, with `_` separators.
82    ///
83    /// Raises `.cannot_parse_int`.
84    IntParse,
85
86    /// `Int.pow : (Int, Int) -> Int`: raises `.negative_exponent`.
87    IntPow,
88
89    /// `Int.range : (Int, Int) -> Iter Int`: `m … n - 1`.
90    IntRange,
91
92    /// `Int.str : Int -> Str`: signed decimal.
93    IntStr,
94
95    /// `Int.sub : (Int, Int) -> Int`
96    IntSub,
97
98    /// `Int.upto : Int -> Iter Int`: `Int.range(0, n)`.
99    IntUpto,
100
101    /// The builtin module `Iter`, the prototype of iterators: the cursor
102    /// methods, the loops, the drains and the step signals.
103    Iter,
104
105    /// `it.__break : Iter a -> b`: ends `it`'s loop.
106    IterBreak,
107
108    /// `it.__continue : Iter a -> b`: ends the step, producing nothing.
109    IterContinue,
110
111    /// `Iter.each : (a -> b, iterable a) -> Iter b`: lazy.
112    IterEach,
113
114    /// `Iter.empty : iterable -> Bool`
115    IterEmpty,
116
117    /// `Iter.eq : (iterable, iterable) -> Bool`: same length and `__eq` elements.
118    IterEq,
119
120    /// `Iter.fold : (s, (Iter a, s) -> s, iterable a) -> s`: eager.
121    IterFold,
122
123    /// `Iter.for : (Iter a -> b, iterable a) -> Iter b`: the step gets a cursor; lazy.
124    IterFor,
125
126    /// `Iter.get : Iter a -> a`: raises `.iter_end`.
127    IterGet,
128
129    /// `Iter.index : iterable a -> Iter #[Int, a]`
130    IterIndex,
131
132    /// `Iter.next : Iter a -> Iter a`: raises `.iter_end`.
133    IterNext,
134
135    /// `__iter : iterable a -> Iter a`: a list, string, map, integer, `Bool` or iterator.
136    IterOf,
137
138    /// `it.__return : (Iter a, b) -> c`: ends the step with `b`.
139    IterReturn,
140
141    /// `Iter.run : iterable -> ()`: drains it for its effects.
142    IterRun,
143
144    /// `it.__yield : (Iter a, iterable b) -> c`: ends the step, producing each
145    /// element of the iterable.
146    ///
147    /// Raises `.yield_in_fold` in a fold.
148    IterYield,
149
150    /// `Iter.zip : (iterable a, iterable b) -> Iter #[a, b]`: ends with the shorter.
151    IterZip,
152
153    /// The builtin module `List`, the prototype of lists.
154    List,
155
156    /// `List.append : (List a, List a) -> List a`
157    ListAppend,
158
159    /// `List.from : iterable a -> List a`
160    ListFrom,
161
162    /// `List.get : (List a, Int) -> a`: raises `.projection_out_of_range`.
163    ListGet,
164
165    /// `List.iter : List a -> Iter a`
166    ListIter,
167
168    /// `List.size : List a -> Int`
169    ListSize,
170
171    /// `List.split : (Int, List a) -> #[List a, List a]`: the first `n`, and the rest.
172    ListSplit,
173
174    /// `List.with : (List a, Int, a) -> List a`: replaces one element.
175    ListWith,
176
177    /// The builtin module `Map`, the prototype of maps.
178    Map,
179
180    /// `Map.cat : (Map, Map) -> Map`: the second wins on a shared key.
181    MapCat,
182
183    /// `Map.from : iterable #[k, v] -> Map`: raises `.not_a_pair`.
184    MapFrom,
185
186    /// `Map.get : (Map, k) -> v`: raises `.missing_key`.
187    MapGet,
188
189    /// `Map.gets : (Map, List k) -> List v`: raises `.missing_key`.
190    MapGets,
191
192    /// `Map.iter : Map -> Iter #[k, v]`: in unspecified order.
193    MapIter,
194
195    /// `Map.merge : (Map, Map, (k, #[] | #[v], #[] | #[v]) -> #[] | #[v]) -> Map`
196    ///
197    /// Over the union of keys; `#[]` is absent.
198    MapMerge,
199
200    /// `Map.nil : Map`: the empty map.
201    MapNil,
202
203    /// `Map.size : Map -> Int`
204    MapSize,
205
206    /// `Map.with : (Map, k, v) -> Map`
207    MapWith,
208
209    /// `Map.without : (Map, k) -> Map`
210    MapWithout,
211
212    /// `Map.zip : (iterable k, iterable v) -> Map`: `Map.from(Iter.zip(ks, vs))`.
213    MapZip,
214
215    /// `__match : (List (a -> b), a) -> b`: the first clause that does not refute.
216    Match,
217
218    /// The builtin module `Mod`: reflection on modules.
219    Mod,
220
221    /// `Mod.exports : Mod -> List Sym`: exported item names, sorted.
222    ///
223    /// Raises `.not_a_module`.
224    ModExports,
225
226    /// `Mod.name : Mod -> Str`
227    ModName,
228
229    /// Desugaring of `#Self <value>`, not a user-visible builtin.
230    ObjNew,
231
232    /// Desugaring of `<expr>.Self` or `Self <pat>`, not a user-visible builtin.
233    ///
234    /// Raises `.foreign_object` on an object of another prototype, so a
235    /// module unwraps only its own objects.
236    ObjValue,
237
238    /// `__proto : a -> Mod`: the prototype of any value.
239    Proto,
240
241    /// `__repr : a -> Str`: the display string of any value.
242    ///
243    /// Matches [`to_display`](crate::Value::to_display).
244    Repr,
245
246    /// The builtin module `Str`, the prototype of strings.
247    Str,
248
249    /// `Str.from : iterable Int -> Str`: from codepoints.
250    ///
251    /// Raises `.not_an_int` or `.bad_codepoint`.
252    StrFrom,
253
254    /// `Str.iter : Str -> Iter Int`, also `Str.chars`: the codepoints.
255    StrIter,
256
257    /// The builtin module `Sym`, the prototype of symbols.
258    Sym,
259
260    /// `Sym.from : Str -> Sym`: raises `.bad_symbol` unless one Muon `<sym>` segment.
261    SymFrom,
262
263    /// `Sym.str : Sym -> Str`: the name without the dot.
264    SymStr,
265
266    /// The builtin module `__Unit`, the prototype of `()`. No items.
267    Unit,
268}
269
270/// A builtin module's item table: `(item name, the builtin it names)`, **sorted
271/// by name** — and so by [`Sym`], since fixed ids follow text order: the order a
272/// module's members take in a chunk, and what [`member`](Builtin::member)
273/// binary-searches.
274pub(crate) type Members = &'static [(Sym, Builtin)];
275
276/// A builtin module's `const` declarations — its **iotas** — as name-sorted fixed
277/// symbols. Only [`__Bool`](Builtin::Bool) has any today; every other module's is
278/// empty. The names are the module's iotas in the `Elly` chunk, which is what an iota's
279/// `<const .name>` rendering reads (see [`Value::write_display`]).
280pub(crate) type Iotas = &'static [Sym];
281
282/// The **builtin modules**, in cache-slot order (see [`Ctx::builtin_module`]):
283/// the 0-arity builtin naming each module, its shadowable bare alias, and its
284/// items. The `__<Ns>_<op>` naming convention the flat builtins used to spell out
285/// lives here instead — `__Int.add` is the module `__Int`'s item `add` — so this
286/// table is the whole of the `__` namespace's structure.
287///
288/// `__match`, `__eq` and `__proto` are not in it: they cut across kinds and
289/// belong to no module.
290pub(crate) const MODULES: &[(Builtin, Sym, Members, Iotas)] = &[
291    (
292        Builtin::Int,
293        Sym::MOD_INT,
294        &[
295            (Sym::ADD, Builtin::IntAdd),
296            (Sym::COUNT, Builtin::IntCount),
297            (Sym::DIVREM, Builtin::IntDivrem),
298            (Sym::EQ, Builtin::IntEq),
299            (Sym::GE, Builtin::IntGe),
300            (Sym::GT, Builtin::IntGt),
301            (Sym::LE, Builtin::IntLe),
302            (Sym::LT, Builtin::IntLt),
303            (Sym::MUL, Builtin::IntMul),
304            (Sym::PARSE, Builtin::IntParse),
305            (Sym::POW, Builtin::IntPow),
306            (Sym::RANGE, Builtin::IntRange),
307            (Sym::STR, Builtin::IntStr),
308            (Sym::SUB, Builtin::IntSub),
309            (Sym::UPTO, Builtin::IntUpto),
310        ],
311        &[],
312    ),
313    (
314        Builtin::Iter,
315        Sym::MOD_ITER,
316        &[
317            (Sym::SIG_BREAK, Builtin::IterBreak),
318            (Sym::SIG_CONTINUE, Builtin::IterContinue),
319            (Sym::SIG_RETURN, Builtin::IterReturn),
320            (Sym::SIG_YIELD, Builtin::IterYield),
321            (Sym::EACH, Builtin::IterEach),
322            (Sym::EMPTY, Builtin::IterEmpty),
323            (Sym::EQ, Builtin::IterEq),
324            (Sym::FOLD, Builtin::IterFold),
325            (Sym::FOR, Builtin::IterFor),
326            (Sym::GET, Builtin::IterGet),
327            (Sym::INDEX, Builtin::IterIndex),
328            (Sym::NEXT, Builtin::IterNext),
329            (Sym::RUN, Builtin::IterRun),
330            (Sym::ZIP, Builtin::IterZip),
331        ],
332        &[],
333    ),
334    (
335        Builtin::Str,
336        Sym::MOD_STR,
337        &[
338            // `chars` names the same builtin as `iter`.
339            (Sym::CHARS, Builtin::StrIter),
340            (Sym::FROM, Builtin::StrFrom),
341            (Sym::ITER, Builtin::StrIter),
342        ],
343        &[],
344    ),
345    (
346        Builtin::Sym,
347        Sym::MOD_SYM,
348        &[(Sym::FROM, Builtin::SymFrom), (Sym::STR, Builtin::SymStr)],
349        &[],
350    ),
351    (
352        Builtin::List,
353        Sym::MOD_LIST,
354        &[
355            (Sym::APPEND, Builtin::ListAppend),
356            (Sym::FROM, Builtin::ListFrom),
357            (Sym::GET, Builtin::ListGet),
358            (Sym::ITER, Builtin::ListIter),
359            (Sym::SIZE, Builtin::ListSize),
360            (Sym::SPLIT, Builtin::ListSplit),
361            (Sym::WITH, Builtin::ListWith),
362        ],
363        &[],
364    ),
365    (
366        Builtin::Map,
367        Sym::MOD_MAP,
368        &[
369            (Sym::CAT, Builtin::MapCat),
370            (Sym::FROM, Builtin::MapFrom),
371            (Sym::GET, Builtin::MapGet),
372            (Sym::GETS, Builtin::MapGets),
373            (Sym::ITER, Builtin::MapIter),
374            (Sym::MERGE, Builtin::MapMerge),
375            (Sym::NIL, Builtin::MapNil),
376            (Sym::SIZE, Builtin::MapSize),
377            (Sym::WITH, Builtin::MapWith),
378            (Sym::WITHOUT, Builtin::MapWithout),
379            (Sym::ZIP, Builtin::MapZip),
380        ],
381        &[],
382    ),
383    (
384        Builtin::Err,
385        Sym::MOD_ERR,
386        &[
387            (Sym::CATCH, Builtin::ErrCatch),
388            (Sym::RAISE, Builtin::ErrRaise),
389        ],
390        &[],
391    ),
392    (
393        Builtin::Mod,
394        Sym::MOD_MOD,
395        &[
396            (Sym::EXPORTS, Builtin::ModExports),
397            (Sym::NAME, Builtin::ModName),
398        ],
399        &[],
400    ),
401    // The two-iota boolean module. `true` / `false` are both iotas (`const`
402    // declarations, populating the iota table for rendering) and items that
403    // re-export them — the same double declaration a user's `false = const` makes
404    // — so `Bool.true` resolves through the ordinary member path while `__true`
405    // names the iota directly. The iotas are name-sorted: `false` is index 0,
406    // `true` index 1 (see [`bool_value`]).
407    (
408        Builtin::Bool,
409        Sym::MOD_BOOL,
410        &[
411            (Sym::AND, Builtin::BoolAnd),
412            (Sym::FALSE, Builtin::BoolFalse),
413            (Sym::NOT, Builtin::BoolNot),
414            (Sym::OR, Builtin::BoolOr),
415            (Sym::TRUE, Builtin::BoolTrue),
416        ],
417        &[Sym::FALSE, Sym::TRUE],
418    ),
419    // No items yet, and a module all the same: it is the prototype the three
420    // callable kinds answer `__proto` with (see [`Builtin::Fun`]).
421    (Builtin::Fun, Sym::MOD_FUN, &[], &[]),
422    // Likewise item-less: the nominal type of the unit value `()`.
423    (Builtin::Unit, Sym::MOD_UNIT, &[], &[]),
424];
425
426/// How many builtin modules there are — the width of the [`Ctx`] cache.
427pub(crate) const NMODULES: usize = MODULES.len();
428
429/// Value kinds with builtin module prototypes, allowing `as <Proto>` to
430/// compile to a discriminant test (see [`Pat::TypeKind`]).
431#[derive(Debug, Clone, Copy, PartialEq, Eq)]
432pub enum TyKind {
433    Int,
434    Sym,
435    Str,
436    List,
437    Map,
438    Fun,
439    /// Module value (prototype `__Mod`).
440    Mod,
441    /// Unit value (prototype `__Unit`).
442    Unit,
443    /// Boolean (iota of `__Bool`).
444    Bool,
445    /// Iterator (prototype `__Iter`).
446    Iter,
447}
448
449impl TyKind {
450    /// Spelling used in `as <Proto>` surface and dumps.
451    pub fn name(self) -> &'static str {
452        match self {
453            TyKind::Int => "Int",
454            TyKind::Sym => "Sym",
455            TyKind::Str => "Str",
456            TyKind::List => "List",
457            TyKind::Map => "Map",
458            TyKind::Fun => "Fun",
459            TyKind::Mod => "Mod",
460            TyKind::Unit => "Unit",
461            TyKind::Bool => "Bool",
462            TyKind::Iter => "Iter",
463        }
464    }
465}
466
467impl Builtin {
468    /// Every nameable builtin in declaration order; the source of truth for
469    /// tooling enumerating the `__` namespace. Keep in sync with the enum.
470    ///
471    /// [`ObjNew`](Builtin::ObjNew) and [`ObjValue`](Builtin::ObjValue) are
472    /// omitted as no name resolves to them; they only render via [`name`](Builtin::name).
473    pub const ALL: &'static [Builtin] = &[
474        Builtin::IntAdd,
475        Builtin::IntSub,
476        Builtin::IntMul,
477        Builtin::IntPow,
478        Builtin::IntDivrem,
479        Builtin::IntEq,
480        Builtin::IntLt,
481        Builtin::IntLe,
482        Builtin::IntGt,
483        Builtin::IntGe,
484        Builtin::ErrRaise,
485        Builtin::ErrCatch,
486        Builtin::Match,
487        Builtin::ListSize,
488        Builtin::ListGet,
489        Builtin::ListAppend,
490        Builtin::ListWith,
491        Builtin::ListSplit,
492        Builtin::Eq,
493        Builtin::MapNil,
494        Builtin::MapWith,
495        Builtin::MapGet,
496        Builtin::MapGets,
497        Builtin::MapMerge,
498        Builtin::MapCat,
499        Builtin::MapWithout,
500        Builtin::MapSize,
501        Builtin::IntStr,
502        Builtin::IntParse,
503        Builtin::SymFrom,
504        Builtin::SymStr,
505        Builtin::ModName,
506        Builtin::ModExports,
507        Builtin::Proto,
508        Builtin::Repr,
509        Builtin::IterOf,
510        Builtin::IterGet,
511        Builtin::IterNext,
512        Builtin::IterEmpty,
513        Builtin::IterIndex,
514        Builtin::IterZip,
515        Builtin::IterEq,
516        Builtin::IterRun,
517        Builtin::IterEach,
518        Builtin::IterFor,
519        Builtin::IterFold,
520        Builtin::IterContinue,
521        Builtin::IterBreak,
522        Builtin::IterReturn,
523        Builtin::IterYield,
524        Builtin::ListIter,
525        Builtin::MapIter,
526        Builtin::StrIter,
527        Builtin::IntUpto,
528        Builtin::IntRange,
529        Builtin::IntCount,
530        Builtin::ListFrom,
531        Builtin::StrFrom,
532        Builtin::MapFrom,
533        Builtin::MapZip,
534        Builtin::Int,
535        Builtin::Iter,
536        Builtin::Str,
537        Builtin::Sym,
538        Builtin::List,
539        Builtin::Map,
540        Builtin::Err,
541        Builtin::Mod,
542        Builtin::Bool,
543        Builtin::BoolTrue,
544        Builtin::BoolFalse,
545        Builtin::BoolAnd,
546        Builtin::BoolOr,
547        Builtin::BoolNot,
548        Builtin::Fun,
549        Builtin::Unit,
550    ];
551
552    /// Resolves a `__`-name to its builtin: a bare name (`__eq`), a builtin
553    /// module (`__Int`), or a module member in dotted form (`__Int.add`).
554    ///
555    /// Since Muon symbols cannot contain dots, the parser reaches members via
556    /// [`member`](Self::member) after folding. This method is used by tooling and
557    /// the `Builtin::ALL` round-trip.
558    pub fn from_name(name: &str) -> Option<Builtin> {
559        if let Some((ns, item)) = name.split_once('.') {
560            return Builtin::from_name(ns)?.member(sym::fixed(item)?);
561        }
562        Some(match name {
563            "__match" => Builtin::Match,
564            "__eq" => Builtin::Eq,
565            "__proto" => Builtin::Proto,
566            "__repr" => Builtin::Repr,
567            "__iter" => Builtin::IterOf,
568            // The two boolean iotas name themselves in the closed `__` namespace,
569            // beside `Bool.true` / `Bool.false`: one Muon `<sym>` each, so a
570            // comparand (`&(= __true)`) can name one where the dotted member is
571            // two items. Both spellings fold to the same op, hence the same iota.
572            "__true" => Builtin::BoolTrue,
573            "__false" => Builtin::BoolFalse,
574            "__Int" => Builtin::Int,
575            "__Iter" => Builtin::Iter,
576            "__Str" => Builtin::Str,
577            "__Sym" => Builtin::Sym,
578            "__List" => Builtin::List,
579            "__Map" => Builtin::Map,
580            "__Err" => Builtin::Err,
581            "__Mod" => Builtin::Mod,
582            "__Bool" => Builtin::Bool,
583            "__Fun" => Builtin::Fun,
584            "__Unit" => Builtin::Unit,
585            _ => return None,
586        })
587    }
588
589    /// The builtin module this bare alias names (e.g. `Int` → `__Int`).
590    /// Aliases are the resolver's bottom tier (the prelude), consulted last to
591    /// ensure they are shadowed by lexical bindings.
592    pub fn from_alias(name: Sym) -> Option<Builtin> {
593        MODULES
594            .iter()
595            .find(|(_, alias, _, _)| *alias == name)
596            .map(|(op, _, _, _)| *op)
597    }
598
599    /// The items of this builtin module, or `None` if not a module.
600    pub(crate) fn items(self) -> Option<Members> {
601        MODULES
602            .iter()
603            .find(|(op, _, _, _)| *op == self)
604            .map(|(_, _, items, _)| *items)
605    }
606
607    /// The cache slot for this builtin module in a [`Ctx`], or `None`.
608    /// Positional and stable for the life of the process.
609    pub(crate) fn module_slot(self) -> Option<usize> {
610        MODULES.iter().position(|(op, _, _, _)| *op == self)
611    }
612
613    /// The item of this builtin module matching `name`, if any. Returns `None`
614    /// if the name is not held or the builtin is not a module. Safe to call on
615    /// any callee of a call spine.
616    pub fn member(self, name: Sym) -> Option<Builtin> {
617        let items = self.items()?;
618        items
619            .binary_search_by_key(&name, |(item, _)| *item)
620            .ok()
621            .map(|i| items[i].1)
622    }
623
624    /// The value kind this builtin module is the prototype of, enabling `as <Proto>`
625    /// patterns to compile to discriminant tests. Returns `None` if not a module
626    /// or for `__Err` (no value has `__Err` as its prototype).
627    pub fn proto_kind(self) -> Option<TyKind> {
628        Some(match self {
629            Builtin::Int => TyKind::Int,
630            Builtin::Str => TyKind::Str,
631            Builtin::Sym => TyKind::Sym,
632            Builtin::List => TyKind::List,
633            Builtin::Map => TyKind::Map,
634            Builtin::Mod => TyKind::Mod,
635            Builtin::Fun => TyKind::Fun,
636            Builtin::Unit => TyKind::Unit,
637            Builtin::Bool => TyKind::Bool,
638            Builtin::Iter => TyKind::Iter,
639            _ => return None,
640        })
641    }
642
643    /// Number of arguments the op consumes before firing. Arity 0 ops are bare
644    /// values that fire on reference (e.g. `__Map.nil` or builtin modules).
645    pub(crate) fn arity(self) -> usize {
646        match self {
647            Builtin::MapNil
648            | Builtin::Int
649            | Builtin::Str
650            | Builtin::Sym
651            | Builtin::List
652            | Builtin::Map
653            | Builtin::Err
654            | Builtin::Mod
655            | Builtin::Iter
656            | Builtin::Bool
657            // The two boolean iotas are values: they fire on reference.
658            | Builtin::BoolTrue
659            | Builtin::BoolFalse
660            | Builtin::Fun
661            | Builtin::Unit => 0,
662            Builtin::Proto
663            | Builtin::Repr
664            | Builtin::ErrRaise
665            | Builtin::ListSize
666            | Builtin::MapSize
667            | Builtin::IntStr
668            | Builtin::IntParse
669            | Builtin::SymFrom
670            | Builtin::SymStr
671            | Builtin::BoolNot
672            | Builtin::ModName
673            | Builtin::ModExports
674            | Builtin::IterOf
675            | Builtin::IterGet
676            | Builtin::IterNext
677            | Builtin::IterEmpty
678            | Builtin::IterIndex
679            | Builtin::IterRun
680            | Builtin::IterContinue
681            | Builtin::IterBreak
682            | Builtin::ListIter
683            | Builtin::MapIter
684            | Builtin::StrIter
685            | Builtin::IntUpto
686            | Builtin::IntCount
687            | Builtin::ListFrom
688            | Builtin::StrFrom
689            | Builtin::MapFrom => 1,
690            Builtin::IntAdd
691            | Builtin::IntSub
692            | Builtin::IntMul
693            | Builtin::IntPow
694            | Builtin::IntDivrem
695            | Builtin::IntEq
696            | Builtin::IntLt
697            | Builtin::IntLe
698            | Builtin::IntGt
699            | Builtin::IntGe
700            | Builtin::BoolAnd
701            | Builtin::BoolOr
702            | Builtin::IterZip
703            | Builtin::IterEq
704            | Builtin::IntRange
705            | Builtin::MapZip
706            | Builtin::IterEach
707            | Builtin::IterFor
708            | Builtin::IterReturn
709            | Builtin::IterYield => 2,
710            // `__match clauses val`: strict in the clause list and the subject.
711            // `__new proto data` / `__value proto obj` — the prototype is the
712            // first argument, and the home-module leaf has already supplied it.
713            Builtin::ObjNew
714            | Builtin::ObjValue
715            | Builtin::Match
716            | Builtin::ErrCatch
717            | Builtin::ListGet
718            | Builtin::ListAppend
719            | Builtin::ListSplit
720            | Builtin::MapGet
721            | Builtin::MapGets
722            | Builtin::MapCat
723            | Builtin::MapWithout => 2,
724            Builtin::ListWith
725            | Builtin::MapWith
726            | Builtin::MapMerge
727            | Builtin::IterFold => 3,
728            Builtin::Eq => 4,
729        }
730    }
731
732    /// Whether argument `i` is a callback that is only ever applied, never stored.
733    /// Literals in such positions use [`Plan::Chain`](crate::code::Plan::Chain) to share the defining
734    /// environment instead of copying a frame.
735    ///
736    /// Must stay in sync with [`invoke`]: arguments listed here must only be
737    /// reached via `apply1`/`apply_n`.
738    pub(crate) fn applies_arg(self, i: usize) -> bool {
739        match self {
740            // `__Err.catch handler thunk` — both are run by the catch.
741            Builtin::ErrCatch => i == 0 || i == 1,
742            // `__eq a b then else` — one of the two branches is forced.
743            Builtin::Eq => i == 2 || i == 3,
744            // `__Map.merge m1 m2 f` — the merge callback.
745            Builtin::MapMerge => i == 2,
746            // `__Iter.fold state f xs` — the step. `__Iter.each` / `__Iter.for`
747            // store theirs in the lazy iterator they return.
748            Builtin::IterFold => i == 1,
749            _ => false,
750        }
751    }
752
753    /// Whether argument `i` is a list of callbacks applied in order (e.g.
754    /// `__match` clauses). Literal abstractions in such lists use [`Plan::Chain`](crate::code::Plan::Chain).
755    pub(crate) fn applies_elements_of(self, i: usize) -> bool {
756        matches!(self, Builtin::Match) && i == 0
757    }
758
759    /// The reserved `__`-name for this builtin. Module members are dotted
760    /// (e.g. `__Int.add`).
761    pub fn name(self) -> &'static str {
762        match self {
763            Builtin::IntAdd => "__Int.add",
764            Builtin::IntSub => "__Int.sub",
765            Builtin::IntMul => "__Int.mul",
766            Builtin::IntPow => "__Int.pow",
767            Builtin::IntDivrem => "__Int.divrem",
768            Builtin::IntEq => "__Int.eq",
769            Builtin::IntLt => "__Int.lt",
770            Builtin::IntLe => "__Int.le",
771            Builtin::IntGt => "__Int.gt",
772            Builtin::IntGe => "__Int.ge",
773            Builtin::ErrRaise => "__Err.raise",
774            Builtin::ErrCatch => "__Err.catch",
775            Builtin::Match => "__match",
776            Builtin::ListSize => "__List.size",
777            Builtin::ListGet => "__List.get",
778            Builtin::ListAppend => "__List.append",
779            Builtin::ListWith => "__List.with",
780            Builtin::ListSplit => "__List.split",
781            Builtin::Eq => "__eq",
782            Builtin::MapNil => "__Map.nil",
783            Builtin::MapWith => "__Map.with",
784            Builtin::MapGet => "__Map.get",
785            Builtin::MapGets => "__Map.gets",
786            Builtin::MapMerge => "__Map.merge",
787            Builtin::MapCat => "__Map.cat",
788            Builtin::MapWithout => "__Map.without",
789            Builtin::MapSize => "__Map.size",
790            Builtin::IntStr => "__Int.str",
791            Builtin::IntParse => "__Int.parse",
792            Builtin::SymFrom => "__Sym.from",
793            Builtin::SymStr => "__Sym.str",
794            Builtin::ModName => "__Mod.name",
795            Builtin::ModExports => "__Mod.exports",
796            Builtin::Proto => "__proto",
797            Builtin::Repr => "__repr",
798            Builtin::IterOf => "__iter",
799            Builtin::IterGet => "__Iter.get",
800            Builtin::IterNext => "__Iter.next",
801            Builtin::IterEmpty => "__Iter.empty",
802            Builtin::IterIndex => "__Iter.index",
803            Builtin::IterZip => "__Iter.zip",
804            Builtin::IterEq => "__Iter.eq",
805            Builtin::IterRun => "__Iter.run",
806            Builtin::IterEach => "__Iter.each",
807            Builtin::IterFor => "__Iter.for",
808            Builtin::IterFold => "__Iter.fold",
809            Builtin::IterContinue => "__Iter.__continue",
810            Builtin::IterBreak => "__Iter.__break",
811            Builtin::IterReturn => "__Iter.__return",
812            Builtin::IterYield => "__Iter.__yield",
813            Builtin::ListIter => "__List.iter",
814            Builtin::MapIter => "__Map.iter",
815            Builtin::StrIter => "__Str.iter",
816            Builtin::IntUpto => "__Int.upto",
817            Builtin::IntRange => "__Int.range",
818            Builtin::IntCount => "__Int.count",
819            Builtin::ListFrom => "__List.from",
820            Builtin::StrFrom => "__Str.from",
821            Builtin::MapFrom => "__Map.from",
822            Builtin::MapZip => "__Map.zip",
823            // The two capabilities render under the leaf that produced them —
824            // there is no other way to hold one, so this is the name a reader
825            // wrote (see [`ALL`](Builtin::ALL) for why they are not in it).
826            Builtin::ObjNew => "__new",
827            Builtin::ObjValue => "__value",
828            Builtin::Int => "__Int",
829            Builtin::Str => "__Str",
830            Builtin::Sym => "__Sym",
831            Builtin::List => "__List",
832            Builtin::Map => "__Map",
833            Builtin::Err => "__Err",
834            Builtin::Mod => "__Mod",
835            Builtin::Iter => "__Iter",
836            Builtin::Bool => "__Bool",
837            // The members render dotted, as every module member does; `__true` /
838            // `__false` are the extra bare spellings [`from_name`](Self::from_name)
839            // also accepts, the way `Int` aliases `__Int`.
840            Builtin::BoolTrue => "__Bool.true",
841            Builtin::BoolFalse => "__Bool.false",
842            Builtin::BoolAnd => "__Bool.and",
843            Builtin::BoolOr => "__Bool.or",
844            Builtin::BoolNot => "__Bool.not",
845            Builtin::Fun => "__Fun",
846            Builtin::Unit => "__Unit",
847        }
848    }
849}