git.iko.soy/urbit.org
on 14ceff4 help sign in
urbit.org/docs/hoon/basic.md
189 lines 6.6 kB history raw
1---
2sort: 5
3next: true
4title: Basic types
5---
7# Basic types
9A `span` is a set of nouns and an interpretation of these nouns.
10Officially, we don't use the word "type" in Hoon. But if we had
11to say "type," it would mean `span`.
13## Span and mold
15There is no Hoon syntax for a span. The programmer never defines
16a span explicitly. It is always produced as the inferred range
17of an expression (twig).
19But we still need simple, well-formed expressions that produce
20regular and well-shaped ranges, for three reasons.
22First: in most cases, this trivial generator should be much
23simpler than the computation itself. Casting the actual result
24to its ideal shape makes sure we know what we're building.
26Second: we can define a standard form for such generators, and
27the standard form is useful. The standard form is a constructor
28function, or *mold*.
30A mold is an idempotent function (`gate`), accepting any noun.
31(An idempotent function is one such that *f(f(x))* equals *f(x)*
32if *f(x)* terminates.) The product range of the function is the
33span, or *icon*, of the mold.
35Usually we use molds purely in the first sense: as an abstract
36definition of a noun. Don't actually call a mold unless you're
37actually validating untrusted foreign data. As a beginner,
38hopefully you aren't!
40## The `span` mold (simplified)
42Usually in Hoon we define the semantics of a primitive by the
43state the span of all nouns that implement that primitive. We
44state this span as the icon of a mold. That mold is produced by
45a kernel arm `span`:
47This is a slightly simplified version of `span`. We'll undo and
48explain the simplifications below.
50```
51++ term @tas
52++ span
53 $@ $? $noun
54 $void
55 == $% {$atom p/term q/(unit atom)}
56 {$cell p/span q/span}
57 {$core p/span q/(map term twig)}
58 {$face p/term q/span}
59 {$fork p/(set span)}
60 {$hold p/span q/twig}
61 ==
62```
64This is a syntactically correct Hoon twig, but treat it as
65pseudocode. If a span is an atom, it's either the atomic string
66`noun` or `void`; if a cell, it's a tuple with one of the heads
67`atom`, `cell`, `core`, etc. We'll go through each of these
68cases below.
70### `$noun` and `$void`
72`$noun` is the set of all nouns. `$void` is the set of no nouns.
74### `{$cell p/span q/span}`
76`{$cell p/span q/span}` is the set of all cells with head `p` and
77tail `q`.
79### `{$fork p/(set span)}
81`{$fork p/(set span)}` is the union of all spans in the set `p`.
83### `{$hold p/span q/twig}`
85A `$hold` span, with span `p` and twig `q`, is a lazy reference
86to the span of `(mint p q)`. In English it means: "the type of
87the product when we compile `q` against subject `p`.
89This is "manual laziness." Hoon is a strict language, so we have
90to express
92### `{$face p/term q/span}
94A `{$face p/term q/span}` wraps the label `p` around the span
95`q`. `p` is a `term` or `@tas`, an atomic ASCII string which
96obeys symbol rules: lowercase and digit only, infix hyphen,
97first character must be lowercase.
99See [`:limb`](twig/limb/limb) for how labels are resolved. It's
100nontrivial.
102### `{%atom p/term q/(unit atom))}
104An `$atom` is an atom, with two twists. `q` is a `unit`, Hoon's
105equivalent of a nullable pointer or a Haskell `Maybe`. If `q`
106is `~`, null, the span is *warm*; any atom is in the span.
107If `q` is `[~ x]`, where `x` is any atom, the span is *cold*;
108its only legal value is the constant `x`.
110`p` in the atom is a terminal used as an *aura*, or soft atom
111type. Auras are a lightweight, advisory representation of the
112units, semantics, and/or syntax of an atom. An aura is an atomic
113string; two auras are compatible if one is a prefix of the other.
115For instance, `@t` means UTF-8 text (LSB low), `@ta` means ASCII
116text, and `@tas` means an ASCII symbol. `@u` means an unsigned
117integer, `@ud` an unsigned decimal, `@ux` an unsigned
118hexadecimal. You can use a `@ud` atom as a `@u` or vice versa,
119but not as a `@tas`.
121Auras can also end with an optional, capitalized suffix, which
122defines the atom's bitwidth as a log starting from `A`. For
123example, `@udD` is an unsigned decimal byte; `@uxG` is an
124unsigned 64-bit hexadecimal.
126You can make up your own auras and are encouraged to do so, but
127here are some conventions bound to constant syntax:
129```
130@c UTF-32 codepoint
131@d date
132 @da absolute date
133 @dr relative date (ie, timespan)
134@f yes or no (inverse boolean)
135@n nil
136@p phonemic base (plot)
137@r IEEE floating-point
138 @rd double precision (64 bits)
139 @rh half precision (16 bits)
140 @rq quad precision (128 bits)
141 @rs single precision (32 bits)
142@s signed integer, sign bit low
143 @sb signed binary
144 @sd signed decimal
145 @sv signed base32
146 @sw signed base64
147 @sx signed hexadecimal
148@t UTF-8 text (cord)
149 @ta ASCII text (span)
150 @tas ASCII symbol (term)
151@u unsigned integer
152 @ub unsigned binary
153 @ud unsigned decimal
154 @uv unsigned base32
155 @uw unsigned base64
156 @ux unsigned hexadecimal
157```
159Auras are truly soft; you can turn any aura into any other,
160statically, by casting through the empty aura `@`. Hoon is not
161dependently typed and can't statically enforce data constraints
162(for example, it can't enforce that a `@tas` is really a symbol).
164### `{$core p/span q/(map term span)}
166A `$core` is a code-data cell. The data (or *payload*) is the
167tail; the code (or *battery*) is the head. `p`, a span, is the
168span of the payload. `q`, a name-twig table, is the source code
169for the battery.
171Each twig in the battery source is compiled to a formula, with
172the core itself as the subject. The battery is a tree of these
173formulas, or *arms*. An arm is a computed attribute against its
174core.
176All code-data structures in normal languages (functions, objects,
177modules, etc) become cores in Hoon. A Hoon battery looks a bit
178like a method table, but not every arm is a "method" in the OO
179sense. An arm is a computed attribute. A method is an arm whose
180product is a Hoon function (or *gate*).
182A gate (function, lambda, etc) is a core with one arm, whose name
183is the empty symbol `$`, and a payload whose shape is `{sample
184context}`. The *context* is the subject in which the gate was
185defined; the *sample* is the argument.
187To call this function on an argument `x`, replace the sample (at
188tree address `6` in the core) with `x`, then compute the arm.
189(Of course, we don't mutate the noun, we make a mutant copy.)