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