git.iko.soy/urbit.org
on 492ae2f help sign in
urbit.org/docs/programming/core/twig/mold.md
136 lines 4.1 kB history raw
1---
2sort: 8
3---
5# Molds (`$` runes).
7A *mold* is a `gate` (function) that helps us build simple and
8rigorous data structures. (In fact, since "mold" sounds nasty,
9molds are often called "structures.")
11## Overview
13While Hoon can't check this property statically, a proper mold
14is a *rectifier*: an idempotent function across all nouns. If
15the sample of a gate has span `%noun`, and its body obeys the
16constraint that for any x, `=((mold x) (mold (mold x)))`, it's a
17rectifier and can be used as a mold.
19Twigs in the `$` family are macros designed for making molds.
20But any Hoon twig may produce a mold. (This is why `moss` is a
21synonym for `twig`).
23Many macros *bunt* a mold, producing `:per(mold $)`. This value,
24simply the result of executing the gate on the default sample,
25is a constant by definition and normally can be compiled as such.
26The range of a mold (the span of its bunt) is called its *icon*.
28Molds have two uses: defining simple and rigorous structures, and
29validating untrusted input data. Validation, though very
30important, is a rare use case. Except for direct raw input,
31it's generally a faux pas to rectify nouns at runtime -- or even
32in userspace.
34As a structure definition, a mold has three common uses. One,
35its bunt is a default value (such as the sample in a gate.) Two,
36the product of some computation is cast to its icon, both
37checking the type and regularizing it. Three, it's used as a
38building block in other molds.
40## Regular forms
42The rune prefix is `$`. Suffixes:
44### `:bank`, `$:`, "buccol", `{$bank p/(list moss)}`
46Syntax: *running*.
48The product: a rectifier gate producing the tuple `p`.
50Where `a`, `b` and `c` produce molds, `:bank(a b c)` produces a
51mold whose icon is the span `[$.a $.b $.c]`.
53### `:coat`, `$=`, "buctis", `{$coat p/@tas q/moss}`
55Syntax: *2-fixed*.
57The product: a rectifier gate producing mold `q` under label `p`.
59Where `q` produces a mold, `:coat(p q)` produces a mold whose
60icon matches the span of `:name(p $.q)`.
62### `:pick`, `$?`, "bucwut", `{$pick p/(list moss)}`
64Syntax: *running*.
66The product: a rectifier gate producing the union of the molds in
67`p`.
69Where `a`, `b`, and `c` produce molds, `:pick(a b c)` produces a
70mold whose icon matches the span of `?:(& $.a ?:(& $.b $.c))`.
72The default mold is the first item in `p`. To avoid an infinite
73loop, it has to be a termination case (such as a constant).
75### `:book`, `$%`, "buccen", `{$book p/(list moss)}`
77Syntax: *running*.
79The product: a rectifier gate producing the tagged union of the
80molds in `p`, all of which must be of the form `:bank(stem
81bulb)`, where `stem` is an atomic mold.
83`$book` has the same icon as `$pick`, but rectifies better.
85The default mold is the first item in `p`. To avoid an infinite
86loop, it has to be a termination case (such as a constant).
88### `:shoe`, `$_`, "buccab", "{$shoe p/twig}"
90Syntax: *1-fixed*.
92Expands to: `:gate(* p)`.
94A `$shoe` is not useful for rectification; it ignores its input.
95It is only useful for defaults and typechecks. Sometimes we have
96no choice but to describe by example.
98### `:lamb`, `$-`, `"buchep"`, `{$lamb p/moss q/moss}`
100Syntax: *1-fixed*.
102Expands to: `:shoe(:gate(p $.q))`.
104`$lamb` is a lambda. We shoe a trivial function from `p` to `q`.
105Like any `$shoe`, a `$lamb` is not useful for rectification (eg,
106you can't use it to typecheck cores sent over the network).
108## Irregular forms
110### Primitives
112`*` means any noun; `@` with an aura means an atom, such as `@ud`
113for unsigned decimal, or just `@` for a generic noun; `?` for
114boolean; `^` for a cell (of `*`).
116### Constants
118For a mold producing a cold atom, replace the `%` of the constant
119syntax with `$`. `%42` is the constant number `42`; `$42` is a
120function that, passed 42 or any other argument, produces `%42`.
122Similarly, `%foo` is the number `7.303.014` or `0x6f.6f66`;
123`$foo` is a function that produces `%foo`.
125`$~` produces `~`.
127### Miscellaneous
129Translation:
131```
132{a b c} :bank(a b c)
133a/b :coat(a b)
134?(a b c) :pick(a b c)
135_a :shoe(a)
136```