git.iko.soy/urbit.org
on 4a847c9 help sign in
urbit.org/docs/programming/learning/core/span.md
118 lines 4.1 kB history raw
1---
2sort: 7
3---
5# Type: `span`
7A `span` is a type as most languages define it: a set of values
8and a semantic interpretation of these values.
10## `mold`: type (as constructor)
12Why isn't `span` called "type"? Because Hoon also has a `mold`,
13a completely different concept that could also be called a "type."
14Hoon has no syntax for declaring spans. Spans are always created
15by `mint`, using type inference.
17But we do want to define data structures with regular shapes. A
18*mold* is an idempotent function (`gate`), accepting any noun.
19The span of our structure is the result set of this function.
21In theory, either molds or spans could be called "types." In
22practice, they're both called "types." The T-word has to stay
23informal: it can't be banned, and it's already confusing enough.
25## `span`: definition
27This twig defines a mold named `span`, whose icon is the set of
28all spans. Don't worry about the syntax yet:
30```
31++ span
32 $@ $? $noun
33 $void
34 == $% {$atom p/term q/(unit atom)}
35 {$cell p/span q/span}
36 {$core p/span q/(map term span)}
37 {$face p/term q/span}
38 {$fork p/(set span)}
39 {$hold p/span q/twig}
40 ==
41```
43## `$noun` and `$void`
45`$noun` is the set of all nouns. `$void` is the set of
46no nouns.
48## `{$cell p/span q/span}`
50`{$cell p/span q/span}` is the set of all cells with head `p` and
51tail `q`.
53## `{$fork p/(set span)}
55`{$fork p/(set span)}` is the union of all spans in the set `p`.
57## `{$hold p/span q/twig}`
59A `$hold` span, with span `p` and twig `q`, is a lazy reference
60to the span of `(mint p q)`. In English it means: "the type of
61the product when we compile `q` with the subject `p`. (Hoon is
62a strict language and the Hoon compiler is written in Hoon, so
63laziness has to be implemented manually.)
65## `{$face p/term q/span}
67A `{$face p/term q/span}` wraps the label `p` around the span
68`q`. See the twig section for how labels are resolved.
70## `{%atom p/term q/(unit atom))}
72An `$atom` is an atom, with two twists. `q` is a `unit`, Hoon's
73equivalent of `Maybe` in Haskell or a nullable in Rust. If `q`
74is `~`, null, the span is *warm*; any atom is in the span.
75If `q` is `[~ x]`, where `x` is any atom, the span is *cold*;
76its only legal value is the constnat `x`.
78`p` in the atom is a terminal used as an *aura*, or soft atom
79type. Auras are a lightweight, advisory representation of the
80units, semantics, and/or syntax of an atom. Two auras are
81compatible if one is a prefix of the other.
83For instance, `@t` means UTF-8 text (LSB low), `@ta` means ASCII
84text, and `@tas` means an ASCII symbol. `@u` means an unsigned
85integer, `@ud` an unsigned decimal, `@ux` an unsigned
86hexadecimal. You can use a `@ud` atom as a `@u` or vice versa,
87but not as a `@tas`.
89Auras are truly soft; you can turn any aura into any other,
90statically, by casting through the empty aura `@`. Hoon is not
91dependently typed and can't enforce data constraints.
93## `{$core p/span q/(map term span)}
95A `$core` is a code-data cell. The data (or *payload*) is the
96tail; the code (or *battery*) is the head. `p`, a span, is the
97span of the payload. `q`, a name-twig table, is the source code
98for the battery.
100Each twig in the battery source is compiled to a formula, with
101the core itself as the subject. The battery is a tree of these
102formulas, or *arms*. An arm is a computed attribute against its
103core.
105All code-data structures in normal languages (functions, objects,
106modules, etc) become cores in Hoon. A Hoon battery looks a bit
107like a method table, but not every arm is a "method" in the OO
108sense. An arm is a computed attribute. A method is an arm whose
109product is a Hoon function (or *gate*).
111A gate is a core with one arm, whose name is the empty symbol
112`$`, and a payload whose shape is `{sample context}`. The
113*context* is the subject in which the gate was defined; the
114*sample* is the argument.
116To call this function on an argument `x`, replace the sample (at
117tree address `6` in the core) with `x`, then compute the arm.
118(Of course, we don't mutate the noun, we make a mutant copy.)