@@ -12,9 +12,9 @@ defining the data type of a Hoon expression. Instead, the compiler
1212infers the type of a Hoon expression by calculating the range of
1313possible values of that expression.
1414
15−Working with a type in Hoon requires the use of a `mold`. Each
16−type is defined by a mold. To define a custom type, you must create
17−a custom mold.
15+Working with a type in Hoon normally requires the use of a `mold`.
16+Each type is defined by a mold. To define a custom type, you must
17+create a custom mold.
1818
1919## Molds
2020
@@ -24,56 +24,65 @@ function *f*, and *f* returns an object from the range. In Hoon we
2424can think of a `gate` as a function, where the gate's `sample` is
2525its argument.
2626
27−A `mold` is an idempotent function (i.e., gate) that takes any noun
28−as its input (i.e., its domain is the set of all nouns). An
29−idempotent function *f* is one such that, if *f(x)* terminates,
30−*f(x) = f(f(x))*. The product range of a mold is the type defined
31−by that mold. That is, each mold's type is the set of possible
32−outputs of that mold.
27+A `mold` is an idempotent function whose domain is the set of all
28+nouns. (That is, it's an idempotent gate that takes any noun for its
29+sample.) An idempotent function *f* is one such that, if *f(x)*
30+terminates, *f(x) = f(f(x))*. The product range of a mold is the
31+type defined by that mold. That is, each mold's type is the set of
32+possible outputs of that mold.
3333
3434Essentially, molds are constructor functions. You can pass a mold
3535any data you like, and the product is guaranteed be of the type
3636defined by that mold. Molds are the perfect tool for validating
37−untrusted foreign data: just call the relevant mold with that data.
38−But this use case is unusual for beginners; otherwise you shouldn't
39−call molds directly.
37+untrusted foreign data. Just call the relevant mold with that data
38+and check that the input equals the output. This is one reason why
39+molds must be idempotent; if the untrusted data is of the correct
40+type, passing it to the mold shouldn't change it. But this use case
41+is unusual for beginners; in normal practice you shouldn't call
42+molds directly.
4043
4144More frequently, molds are used when we want to `cast`. We use a
4245cast when we want the Hoon compiler's type-checker to test whether
4346a Hoon expression is guaranteed to evaluate to a product of the
4447desired type. If it isn't, then the compiler will halt with a
45−`nest-fail` crash. Proper Hoon code will include a cast for each
46−gate.
48+`nest-fail` crash. Proper Hoon code will include a cast for the
49+product type of each gate.
4750
4851The `^` family of runes is for casting. In particular, `^-` allows
4952us to cast with a mold. For example, we can cast for an `atom` using
5053the `@` mold as follows:
5154
5255```
53−^-(@ 17)
56+^- @
57+17
5458```
5559
5660Evaluating the above in `dojo` should return 17, because 17 is of
5761the type `atom`. On the other hand,
5862
5963```
60−^-(@ [17 18])
64+^- @
65+[17 18]
6166```
6267
6368...this should result in a `nest-fail`, because `[17 18]` is a cell,
6469not an atom.
6570
66−See the documentation on the `^` family of runes for more information
67−on casts. See the documentation on the `$` family of runes for
68−building molds. (Also check out the irregular `,` operator.)
71+See the documentation on the [`^` family](../twig/ket-cast/) of runes
72+for more information on casts. See the documentation on the
73+[`$` family](../twig/buc-mold/) of runes for building molds.
74+(Also check out the irregular `,` operator.)
6975
7076## `type`: a set of types
7177
72−Below is the mold for `type`, written in Hoon. This mold's range is
73−the set of all types. (Don't let yourself get too dizzy thinking
74−about it! Strictly speaking, the range is of trees of type-*labels*
75−used by the compiler's type-checker. We don't mess around with
76−set-theoretic paradoxes.)
78+Below is the mold for `type`, which effectively defines all the types
79+available in Hoon.
80+
81+Strictly speaking, this mold defines the tree data structure the Hoon
82+compiler uses to represent type information. It has a label for each
83+of the base types, and it's recursive, so a complex type is
84+represented as a nested combination of base types and various other
85+odds and ends.
7786
7887You haven't seen this syntax before, and we haven't explained it yet;
7988just treat it as pseudocode.
@@ -96,9 +105,9 @@ section.
96105 ==
97106```
98107
99−If a type is an atom, it's labelled with either the atomic string
100−`%noun` or `%void`; if a cell, it's labelled with a tuple with one of
101−the heads `%atom`, `%cell`, `%core`, etc. We'll go through each of
108+If the `type`-tree is an atom, it's either a `%noun` or a `%void`; if
109+the `type`-tree is a cell, it's a tuple with one of the heads `%atom`,
110+`%cell`, `%core`, etc. We'll go through each of these cases below.
102111these cases below.
103112
104113### `?($noun $void)`
@@ -110,12 +119,12 @@ for the empty set.
110119
111120### `{$cell p/type q/type}`
112121
113−`[%cell p/type q/type]` is for the set of all cells with head `p` and
122+`[%cell p=type q=type]` is for the set of all cells with head `p` and
114123tail `q`.
115124
116125### `{$fork p/(set type)}`
117126
118−`[%fork p/(set type)]` is for the union of all types in the set `p`.
127+`[%fork p=(set type)]` is for the union of all types in the set `p`.
119128
120129### `{$hold p/type q/hoon}`
121130
@@ -123,14 +132,17 @@ A `%hold` type, with type `p` and hoon `q`, is a lazy reference
123132to the type of `(mint p q)`. In English, it means: "the type of
124133the product when we compile `q` against subject `p`."
125134
135+Note that this means we can have parsed Hoon AST data in the
136+`type`-tree.
137+
126138### `{$face p/term q/type}`
127139
128−A `[%face p/term q/type]` wraps the label `p` around the type
140+A `[%face p=term q=type]` wraps the label `p` around the type
129141`q`. `p` is a `term` or `@tas`, an atomic ASCII string which
130142obeys symbol rules: lowercase and digit only, infix hyphen,
131143first character must be lowercase.
132144
133−See [`:limb`](../twig/limb/limb) for how labels are resolved. It's
145+See [`%limb`](../twig/limb/limb) for how labels are resolved. It's
134146nontrivial.
135147
136148### `{%atom p/term q/(unit atom))}`