git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/programming/core/span.md
157 lines 5.8 kB history raw
1---
2sort: 7
3---
5# Type: `span`
7A `span` is a set of nouns and an interpretation of these nouns.
9## Span, mold, type: what's in a type system?
11There is no Hoon syntax for a span. The programmer never defines
12a span explicitly. It is always produced as the inferred range
13of an expression (twig).
15But we still need simple, well-formed expressions that produce
16regular and well-shaped ranges, for three reasons.
18First: in most cases, this trivial generator should be much
19simpler than the computation itself. Casting the actual result
20to its ideal shape makes sure we know what we're building.
22Second: we can define a standard form for such generators, and
23the standard form is useful. The standard form is a constructor
24function, or *mold*.
26A mold is an idempotent function (`gate`), accepting any noun.
27(An idempotent function is one such that f(f(x)) equals f(x) if
28f(x) does not crash.) The product range of the function is the
29span, or *icon*, of the mold.
31Usually we use molds purely in the first sense: as an abstract
32definition of a noun. Don't actually call a mold unless you're
33actually validating untrusted foreign data. As a beginner,
34hopefully you aren't!
36(It's also important to remember that any twig can be a mold.
37Some stems are macros designed for making molds, but a mold is
38defined by how it's used, not what it's made of. The Hoon type
39system cannot even check the mold definition, since Hoon lacks
40dependent type and therefore can't verify idempotence.)
42To summarize: a Hoon "type declaration" is the definition of a
43function, the mold. A mold and a span are different things. A
44mold is a constructor. A span defines a set of nouns, possibly
45infinite, and annotates them with semantics.
47Either mold or span could be called a "type," but not both. We
48often say "type" in Hoon. But we always mean it informally.
49Ideally, the meaning is obvious from context. ("Type" can also
50mean a `mark`, Urbit's equivalent of a MIME type.)
52## The `span` mold
54Usually in Hoon we define the semantics of a primitive by the
55state the span of all nouns that implement that primitive. We
56state this span as the icon of a mold. That mold is produced by
57a kernel arm `span`:
59```
60++ term @tas
61++ span
62 $@ $? $noun
63 $void
64 == $% {$atom p/term q/(unit atom)}
65 {$cell p/span q/span}
66 {$core p/span q/(map term span)}
67 {$face p/term q/span}
68 {$fork p/(set span)}
69 {$hold p/span q/twig}
70 ==
71```
73This is a syntactically correct Hoon twig, but treat it as
74pseudocode. If a span is an atom, it's either the atomic string
75`noun` or `void`; if a cell, it's a tuple with one of the heads
76`atom`, `cell`, `core`, etc. We'll go through each of these
77cases below.
79## `$noun` and `$void`
81`$noun` is the set of all nouns. `$void` is the set of no nouns.
83## `{$cell p/span q/span}`
85`{$cell p/span q/span}` is the set of all cells with head `p` and
86tail `q`.
88## `{$fork p/(set span)}
90`{$fork p/(set span)}` is the union of all spans in the set `p`.
92## `{$hold p/span q/twig}`
94A `$hold` span, with span `p` and twig `q`, is a lazy reference
95to the span of `(mint p q)`. In English it means: "the type of
96the product when we compile `q` against subject `p`.
98## `{$face p/term q/span}
100A `{$face p/term q/span}` wraps the label `p` around the span
101`q`. `p` is a `term` or `@tas`, an atomic ASCII string which
102obeys symbol rules: lowercase and digit only, infix hyphen,
103first character must be lowercase.
105See the [twig chapter](twig) for how labels are resolved. It's
106nontrivial.
108## `{%atom p/term q/(unit atom))}
110An `$atom` is an atom, with two twists. `q` is a `unit`, Hoon's
111equivalent of a nullable pointer or a Haskell `Maybe`. If `q`
112is `~`, null, the span is *warm*; any atom is in the span.
113If `q` is `[~ x]`, where `x` is any atom, the span is *cold*;
114its only legal value is the constant `x`.
116`p` in the atom is a terminal used as an *aura*, or soft atom
117type. Auras are a lightweight, advisory representation of the
118units, semantics, and/or syntax of an atom. An aura is an atomic
119string; Two auras are compatible if one is a prefix of the other.
121For instance, `@t` means UTF-8 text (LSB low), `@ta` means ASCII
122text, and `@tas` means an ASCII symbol. `@u` means an unsigned
123integer, `@ud` an unsigned decimal, `@ux` an unsigned
124hexadecimal. You can use a `@ud` atom as a `@u` or vice versa,
125but not as a `@tas`.
127Auras are truly soft; you can turn any aura into any other,
128statically, by casting through the empty aura `@`. Hoon is not
129dependently typed and can't statically enforce data constraints
130(for example, it can't enforce that a `@tas` is really a symbol).
132## `{$core p/span q/(map term span)}
134A `$core` is a code-data cell. The data (or *payload*) is the
135tail; the code (or *battery*) is the head. `p`, a span, is the
136span of the payload. `q`, a name-twig table, is the source code
137for the battery.
139Each twig in the battery source is compiled to a formula, with
140the core itself as the subject. The battery is a tree of these
141formulas, or *arms*. An arm is a computed attribute against its
142core.
144All code-data structures in normal languages (functions, objects,
145modules, etc) become cores in Hoon. A Hoon battery looks a bit
146like a method table, but not every arm is a "method" in the OO
147sense. An arm is a computed attribute. A method is an arm whose
148product is a Hoon function (or *gate*).
150A gate is a core with one arm, whose name is the empty symbol
151`$`, and a payload whose shape is `{sample context}`. The
152*context* is the subject in which the gate was defined; the
153*sample* is the argument.
155To call this function on an argument `x`, replace the sample (at
156tree address `6` in the core) with `x`, then compute the arm.
157(Of course, we don't mutate the noun, we make a mutant copy.)