@@ -1,11 +1,10 @@
11---
2−navhome: '/docs'
3−next: True
2+navhome: /docs/
43sort: 3
5−title: Urbit glossary
4+title: Glossary
65---
76
8−# Urbit Glossary
7+# Glossary
98
109Urbit is renowned for its exotic terminology. Here's a simple overview
1110from the strange words in.
@@ -29,12 +28,13 @@ classed by the number of bits in their address:
2928
3029Any ship can be called an "urbit."
3130
32−> A summary [here](http://urbit.org/posts/address-space/).
33−
31+> You can find a longer-form summary here:
32+> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).
33+
3434An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
3535but it's easy to remember and say out loud. `~firbyr-napbes` is actually
36−just a 32-bit number, like an IP address, that we turn into a
37−human-memorable string.
36+just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
37+that we turn into a human-memorable string.
3838
3939Technically, an urbit is a secure digital identity that you own and
4040control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
@@ -57,7 +57,7 @@ whose number is its bottom half. So the planet `~firbyr-napbes`,
5757`48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of `~mun`
5858and all galaxies is `~zod`, `0`.
5959
60−##### <h5 id="pier">Pier</h5>
60+#### pier
6161
6262A ship's *pier* is its Unix directory. For planets the name of the pier is usually the planet name.
6363
@@ -65,60 +65,62 @@ A ship's *pier* is its Unix directory. For planets the name of the pier is usua
6565
6666> Nock is a Turing-complete, non-lambda combinator interpreter.
6767
68−- *atom*: any natural number
69−- *cell*: any ordered pair of nouns
70−- *formula*: a noun - a function at the Nock level
71−- *noun*: an *atom* or a *cell*
72−- *product*: a noun - the result of evaluating a formula against a
73− subject
74−- *subject*: a noun - the data against which a `formula` is
68+- <h6 id="-nock-noun">noun:</h6> an _atom_ or a _cell_
69+- <h6 id="-nock-atom">atom:</h6> any natural number
70+- <h6 id="-nock-cell">cell:</h6> any ordered pair of nouns
71+- <h6 id="-nock-subject">subject:</h6> a noun - the data against which a _formula_ is
7572 evaluated
73+- <h6 id="-nock-formula">formula:</h6> a noun - a function at the Nock level
74+- <h6 id="-nock-product">product:</h6> a noun - the result of evaluating a formula against a
75+ subject
7676
7777*See [Nock definition](../../nock/definition/).*
7878
79−### Hoon
79+## Hoon
8080
8181> Hoon is a strict, higher-order typed functional language that compiles
8282> itself to Nock.
8383
84−###### <h6 id="arm">arm:</h6> a named, functionally-computed attribute of a core
84+#### arm
85+
86+An _arm_ is a named, functionally-computed attribute of a [core](#-core).
8587
86−The *twig* of each arm is compiled to a Nock formula, with the
88+The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the
8789enclosing `core` itself as the subject.
8890
8991There are two kinds of arms: *dry* and *wet*. Most arms are dry.
9092
91−- *dry*: normal, `++`, polymorphic by means of *variance*
93+- <h6 id="-arm-dry">dry:</h6> normal, `++`, polymorphic by means of *variance*
9294
9395For a dry arm, we ask, is the new payload compatible with the old
9496payload (against which the core was compiled)?
9597
96−- *wet*: unusual, `+-`, polymorphic by means of *genericity*
98+- <h6 id="-arm-wet">wet:</h6> unusual, `+-`, polymorphic by means of *genericity*
9799
98−A wet arm uses the twig as a macro. We create a new type analysis
100+A wet arm uses the hoon as a macro. We create a new type analysis
99101path, which works as if we expanded the callee with the caller's
100102context.
101103
102−*See [advanced types](/hoon/advanced)*.
104+*See [advanced types](../../hoon/advanced/)*.
103105
104−###### atom
106+#### atom
105107
106−A Hoon *atom* span describes a Nock atom, with two additional pieces
108+A Hoon _atom_ type describes a Nock atom, with two additional pieces
107109of metadata: an *aura*, and an optional constant.
108110
109−An atom span is *warm* or *cold* based on whether the constant exists.
111+An atom type is *warm* or *cold* based on whether the constant exists.
110112
111−- *warm*: if the constant is `~` (null), any atom is in the span
112−- *cold*: if the constant is `[~ atom]`, its only legal value is
113+- <h6 id="-atom-warm">warm:</h6> if the constant is `~` (null), any atom is in the type
114+- <h6 id="-atom-cold">cold:</h6> if the constant is `[~ atom]`, its only legal value is
113115 `atom`.
114116
115117*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
116118
117−###### aura: a soft atom type
119+#### aura
118120
119−*aura* is a name for an atom type. It represents the structure of an
120−atom in a string beginning with `@`. An aura may represent units,
121−print format, or other semantics. Its constraints on the value of an
121+An *aura* is a soft atom type. It represents the structure of an
122+atom in a string beginning with `@`. An aura may represent print
123+format or other semantics. Its constraints on the value of an
122124atom aren't enforced in any way.
123125
124126Two auras are compatible if one is a prefix of the other. You can
@@ -128,76 +130,133 @@ auras.
128130
129131Some common auras and their aliases:
130132
131−- *term* (`@tas`): a symbol - an atomic ASCII string which obeys
133+- <h6 id="-aura-term">term:</h6> (`@tas`): a symbol - an atomic ASCII string which obeys
132134 symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),
133135 first character must be lowercase alphabetic.
134−- *cord* (`@t`): UTF-8 text, least-significant-byte first
135−- *char* (`@tD`): a character, a single unicode byte (for multi-byte
136+- <h6 id="-aura-cord">cord:</h6> (`@t`): UTF-8 text, least-significant-byte first
137+- <h6 id="-aura-char">char:</h6> (`@tD`): a character, a single unicode byte (for multi-byte
136138 characters and codepoints, see `@c`)
137139
140+You can find the list of all auras [here](../../hoon/twig/atom/sand/).
141+
138142*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
139143
140−###### <h6 id="core">core:</h6> a code-data cell
144+#### core
141145
142−The code (*battery*) is the head, the data (*payload*) is the tail. All
143−code-data structures in normal languages (functions, objects, modules,
144−etc) become *core*s in Hoon.
146+A _core_ is a [cell](#-nock-cell) of `[code data]`, where we call the
147+code head the _battery_ and the data tail the _payload_. All code-data
148+structures in normal languages (functions, objects, modules, etc.)
149+become _core_s in Hoon.
145150
146−- <h6 id="battery">*battery*:</h6> the code of a core, a tree of *arms*
147−- <h6 id="payload">*payload*:</h6> the data in a core
151+- <h6 id="-core-battery">battery:</h6> the code of a core, a tree of *arms*
152+- <h6 id="-core-payload">payload:</h6> the data in a core
148153
149154*See [basic types](../../hoon/basic)*.
150155
151−###### face: a labeled subtree
156+#### face
157+
158+A Hoon _face_ is a labeled subtree.
152159
153160Hoon has no scope or symbol-table; there is only the subject. To
154161"declare" a "variable" is to construct a new subject:
155162`[name=value old-subject]`.
156163
157−A *face* is a span that wraps a name (`@tas`) around another span.
164+A face is a type that wraps a named symbol (of [aura](#-aura)
165+`@tas`) around another type.
158166
159167*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
160168
161−###### <h6 id="gate">gate:</h6> a function/lambda/closure
169+#### gate
162170
163−A *gate* is a core with one arm. To call a gate on an argument,
164−replace the sample (at [tree
165−address](../../hoon/twig/limb/limb/) `+6` in the core) with the
166−argument, and then compute the arm.
171+A _gate_ is a [core](#-core) with one [arm](#-arm) -- Hoon's closest
172+analog to a function/lambda/closure. To call a gate on an argument,
173+replace the sample (at [tree address](../../hoon/twig/limb/limb/) `+6`
174+in the core) with the argument, and then compute the arm.
167175
168−The payload of a gate has a shape of `{sample context}`.
176+The payload of a gate has a shape of `[sample context]`.
169177
170−- *sample*: the argument tuple
171−- *context*: the subject in which the gate was defined
178+- <h6 id="-gate-sample">sample:</h6> the argument tuple
179+- <h6 id="-gate-context">context:</h6> the subject in which the gate was defined
172180
173181*See [basic types](../../hoon/basic/#-core-p-span-q-map-term-span),
174−[`%-` or `:call`](../../hoon/twig/cen-call/hep-call/) (the `twig` for
175−calling a `gate`).*
182+[`%-` ("cenhep")](../../hoon/twig/cen-call/hep-call/) (the
183+[rune](#-rune) for calling a `gate`).*
184+
185+#### <h4 id="-a-hoon">hoon</h4>
186+
187+A [`hoon`](../../hoon/reference/) is the result of parsing a Hoon source
188+expression into an AST node. These AST nodes are nouns, like all
189+other Hoon data. Because every Hoon program is, in its entirety, a
190+single expression of Hoon, the result of parsing the whole thing
191+into an AST is a single `hoon`.
192+
193+A hoon is a tagged union of the form `[%tag data]`, where the tag
194+is a constant such as `%brts` (from the source [rune](#-rune) `|=`,
195+i.e. "bartis"), and is matched up with the appropriate type of data
196+(often more `hoon`s, from source subexpressions). For example, the
197+expression `:-(2 17)`, once parsed into an AST, becomes the following:
198+
199+```
200+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
201+```
202+
203+The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and
204+17 have each been parsed as `%sand`-tagged hoons, which represent
205+atoms (in this case each with an aura of `%ud`, i.e. unsigned
206+decimal).
176207
177−###### limb: attribute or variable reference
208+To parse Hoon source into a hoon AST, use `ream` on a `cord`
209+containing Hoon source. Try the following in [Dojo](../../using/shell):
210+
211+```
212+(ream ':+(12 7 %a)')
213+```
214+
215+The result should be:
216+
217+```
218+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
219+```
220+
221+#### limb
222+
223+A _limb_ is an attribute or variable reference.
178224
179225To resolve a *limb* named "foo", the subject is searched depth-first,
180226head-first for either a face named "foo" or a core with an arm of
181227"foo". If a face is found, the result is a leg, if a core is
182228found, the result is the product of the arm.
183229
184−- *leg*: a subexpression, or subtree of the subject.
185−- *wing*: a list of limbs, searched from right to left (`a.b` means
230+- <h6 id="-limb-leg">leg:</h6> a subexpression, or subtree of the subject.
231+- <h6 id="-limb-wing">wing:</h6> a list of limbs, searched from right to left (`a.b` means
186232 `b` within `a`).
187233
188−*See [Limbs and wings](../../hoon/twig/limb)*
234+*See [Limbs and wings](../../hoon/twig/limb/)*
189235
190−###### loobean: a Hoon boolean
236+#### loobean
191237
192−`0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
238+A _loobean_ is a Hoon boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
193239
194240> Why? It's fresh, it's different, it's new. And it's annoying. And it
195241> keeps you on your toes. And it's also just intuitively right.
196242
197−###### metal: a variance model
243+#### mark
244+
245+A _mark_ is Urbit's version of a MIME type, if a MIME type was an
246+executable specification. The mark is just a label that's used as a path
247+to a local source file in the Arvo filesystem. This source file defines
248+a core that can mold untrusted data, diff and patch, convert to other
249+marks, etc.
198250
199−Every core has a *metal* which defines its variance model (ie, the
200−properties of the span of a compatible core). The default is `gold`
251+If this sounds like magic, it isn't quite magic. There's no way
252+for different urbits to make sure they mean the same thing by the
253+same mark. However, when incompatibility happens, marks ensure
254+that we at least handle the situation in a predictable way.
255+
256+#### metal
257+
258+Every core has a _metal_ which defines its variance model (ie, the
259+properties of the type of a compatible core). The default is `gold`
201260(invariant).
202261
203262- `gold`: *invariant*
@@ -207,69 +266,98 @@ properties of the span of a compatible core). The default is `gold`
207266
208267*See [advanced types](/hoon/advanced)*.
209268
210−###### <h6 id="mold">mold:</h6> a type constructor / validator
269+#### mold
270+
271+A _mold_ is an idempotent [gate](#-gate) (function), accepting any noun,
272+and producing a range with a type, a set of nouns.
211273
212−A *mold* is an idempotent gate (function), accepting any noun, and
213−producing a range with a useful span.
274+Molds act as type constructor/validators in Hoon. An example: Arvo
275+[marks](#-marks) use Hoon's type system under the hood via molds to
276+validate untrusted network data.
214277
215−- *bunt*: the value a mold produces when normalizing its default
278+Here's some common mold terminology:
279+
280+- <h6 id="-mold-bunt">bunt:</h6> the value a mold produces when normalizing its default
216281 sample
217−- *icon*: the span of the mold's range
282+- <h6 id="-mold-icon">icon:</h6> the type of the mold's range
218283
219−*See [mold twigs](/hoon/twig/buc-mold/).*
284+*See [mold hoons](../../hoon/twig/buc-mold/).*
220285
221−###### nest: type compatibility test
286+#### nest
222287
223−*nest* is an internal function on two spans, which produces yes if the
224−set of nouns in the second span is provably a subset of the first.
288+`nest` is an internal Hoon function on two types which performs a type
289+compatibility test. `nest` produces yes if the
290+set of nouns in the second type is provably a subset of the first.
291+If `nest` produces no, the Hoon programmer will receive a `nest-fail`
292+error. This is one of the most commons errors in Hoon programming.
225293
226294*See [advanced types](../../hoon/advanced/)*.
295+*See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.
227296
228−###### slot: a tree addressing scheme
297+#### rune
229298
230−Every cell has a head and a tail, each of which may be either an atom or
231−a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
232−the whole cell (technically this would work against an atom as well).
233−The head of `+n` is `+2n`, the tail is `+(2n+1)`.
299+A Hoon _rune_ is a pair of ASCII symbols used to begin a
300+[Hoon expression](#-a-hoon).
234301
235−###### <h6 id="span">span:</h6> an inferred type
302+For example, the rune [`?:`](../../hoon/twig/wut-test/col-if/) is
303+Hoon's most common conditional, a branch on a boolean test. The first
304+symbol in a rune represents a family of related runes. For example, the
305+[`?` family](../../hoon/twig/wut-test/) are all conditionals.
236306
237−A *span* defines a set (finite or infinite) of nouns and ascribes some
238−semantics to it. There is no Hoon syntax for a span; it is always
239−produced as the inferred range of an expression (*twig*).
307+The result of parsing a Hoon source expression—the rune, followed
308+by its respective children—into an AST node is simply called
309+a [`hoon`](#-a-hoon).
240310
241−*See [basic types](../../hoon/basic/#-type-span-and-mold).*
311+Runes have two syntactic forms, _tall_ and _flat_:
242312
243−###### <h6 id="twig">twig:</h6> a Hoon expression
313+- <h6 id="-rune-tall">tall:</h6> multiple lines, no parentheses, two or more spaces between
314+ tokens
244315
245−A *twig* is a Hoon expression. Specifically, twig is the mold for the
246−noun that a Hoon source expression compiles to. A twig is always a cell.
316+ Example:
247317
248−A twig has one of two forms: `{twig twig}`, which produces the ordered
249−pair of the two twigs, or a cell `{stem bulb}`, where `stem` is an
250−atomic symbol.
318+ ```
319+ ~zod:dojo> %+ add 2 2
320+ 4
321+ ```
322+- <h6 id="-rune-flat">flat:</h6> one line, parentheses, one space between tokens
251323
252−- <h6 id="stem">*stem*:</h6> an atomic symbol (`@tas`) - the name of a twig.
253−- <h6 id="bulb">*bulb*:</h6> The mold of the twig's contents.
324+ Example:
254325
255−Most twigs have a *regular form*, beginning with a *rune*. Some twigs
256−also have a syntactic *irregular form*; a few have *only* an *irregular form*.
326+ ```
327+ ~zod:dojo> %+(add 2 2) :: regular flat form
328+ 4
257329
258−- <h6 id="rune">*rune*:</h6> a pair of ASCII symbols used to begin a twig.
330+ ~zod:dojo> (add 2 2) :: irregular flat form
331+ 4
332+ ```
259333
260−For example, the rune [`?:`](../../hoon/twig/wut-test/col-if/) is
261−Hoon's most common conditional, a branch on a boolean test. The first symbol
262−in a rune represents a family of related `twig`s. For example, the
263−[`?` family](../../hoon/twig/wut-test/) are all conditionals.
334+Tall hoons can contain flat hoons, but not vice versa. All irregular
335+forms are flat.
264336
265−A regular twig has two syntactic forms, *tall* and *flat*:
337+*See [hoon concept](../../hoon/concepts/#-hoon),
338+[expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
266339
267−- *tall*: multiple lines, no parentheses, two or more spaces between
268− tokens
269−- *flat*: one line, parentheses, one space between tokens
270340
271−Tall twigs can contain flat ones, but not vice versa. All irregular
272−forms are flat.
341+#### slot
342+
343+`slot` is the name for Hoon's tree addressing scheme.
344+
345+Every cell has a head and a tail, each of which may be either an atom or
346+a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
347+the whole cell (technically this would work against an atom as well).
348+The head of `+n` is `+2n`, the tail is `+(2n+1)`.
349+
350+#### type
351+
352+A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes
353+some semantics to it. There is no direct syntax for defining
354+types; they are always defined by inference (i.e., by
355+[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).
356+
357+All types are assembled out of base types defined in `++type`.
358+(Look up `++ type` in hoon.hoon for examples.) When the compiler
359+does type-inference on a program, it assembles complex types out
360+of the simpler built-in types.
361+
362+*See [basic types](../../hoon/basic/#-type-span-and-mold).*
273363
274−*See [twig concept](../../hoon/concepts/#-twig-expression),
275−[expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.