@@ -2,25 +2,35 @@
2navhome: /docs
2navhome: /docs
5−title: Glossary of Urbit Terms
5+title: Urbit glossary
8−# Glossary of Urbit Terms
8+# Urbit glossary
10−Here is a simple overview of the most common Urbit terms. Once you understand this, you know almost everything you need to start using Urbit.
10+Urbit is renowned for its exotic terminology. Here's a simple
11+overview from the strange words in.
12−## The Universe in a Table
13+As Dijkstra put it: "The purpose of abstraction is not to be
14+vague, but to create a new semantic level in which one can be
19+An Urbit `ship` is a cryptographic identity, a human-memorable
20+name, and a packet routing address. Ships are classed by the
21+number of bits in their address:
14 Size Name Parent Object Example
23 Size Name Parent Object Example
15 ----- ------ ------ ------ -------
24 ----- ------ ------ ------ -------
16− 2^8 galaxy ~ datacenter ~zod
25+ 2^8 galaxy ~ supernode ~zod
17− 2^16 star galaxy sysadmin ~doznec
26+ 2^16 star galaxy supernode ~doznec
18 2^32 planet star user ~tasfyn-partyv
27 2^32 planet star user ~tasfyn-partyv
19 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
28 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
20 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
29 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
21− any urbit * * ~somnym-anynym
31+Any ship can be called an `urbit`.
23−> The below summary is also available [here](http://urbit.org/posts/address-space/).
33+> A summary [here](http://urbit.org/posts/address-space/).
25An Urbit identity is a string like `~firbyr-napbes`. It
35An Urbit identity is a string like `~firbyr-napbes`. It
26means nothing, but it's easy to remember and say out loud.
36means nothing, but it's easy to remember and say out loud.
@@ -50,13 +60,13 @@ or `48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of
53−> Nock is a Turing-complete, non-lambda combinator function.
63+> Nock is a Turing-complete, non-lambda combinator interpreter.
55- `noun`: an `atom` or a `cell`
65- `noun`: an `atom` or a `cell`
56- `atom`: any natural number
66- `atom`: any natural number
57- `cell`: any ordered pair of `noun`s
67- `cell`: any ordered pair of `noun`s
58- `subject`: a `noun` - the data against which a `formula` is evaluated
68- `subject`: a `noun` - the data against which a `formula` is evaluated
59−- `formula`: a `cell` - any of the Nock formula numbers (0-10) or a pair of formulas that resolves to a cell.
69+- `formula`: a `noun` - a function at the Nock level
60- `product`: a `noun` - the result of evaluating a `formula` against a `subject`
70- `product`: a `noun` - the result of evaluating a `formula` against a `subject`
62*See [Nock definition](/nock/definition/).*
72*See [Nock definition](/nock/definition/).*
@@ -67,69 +77,88 @@ or `48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of
68###### `span`: an inferred type
78###### `span`: an inferred type
80+A `span` defines a set (finite or infinite) of `noun`s and
70−A `span` defines a set (finite or infinite) of `noun`s and ascribes some semantics to it. There is no Hoon syntax for a `span`; it is always produced as the inferred range of an expression (`twig`).
81+ascribes some semantics to it. There is no Hoon syntax for a
82+`span`; it is always produced as the inferred range of an
72*See [basic types](/hoon/basic/#-type-span-and-mold).*
85*See [basic types](/hoon/basic/#-type-span-and-mold).*
74−###### `mold`: a type constructor / validator
87+###### `core`: a code-data `cell`
76−A mold is an idempotent `gate` (function), accepting any `noun` and normalizing it to a range.
78−- `bunt`: the default value of a `mold`
79−- `icon`: the `span` of a `bunt`
81−*See [`mold` `twig`s](/hoon/twig/buc-mold/).*
83−###### `gate`: a function, lambda or closure
85−A `gate` is a `core` with one `arm`. To call a `gate` on an argument, replace the `sample` (at tree address `6` in the `core`) with the argument, and then compute the `arm`.
89+The code (`battery`) is the head, the data (`payload`) is the
90+tail. All code-data structures in normal languages (functions,
91+objects, modules, etc) become `core`s in Hoon.
87−The `payload` of a `gate` has a shape of `{sample context}`.
93+- `battery`: the code of a `core`, a tree of `arm`s
94+- `payload`: the data in a `core`
89−- `sample`: the argument
96+*See [basic types](/hoon/basic)*.
90−- `context`: the subject in which a `gate` was defined
92−*See [basic types](/hoon/basic/#-core-p-span-q-map-term-span), [`%-` or `:call`](/hoon/twig/cen-call/hep-call/) (the `twig` for calling a `gate`).*
98+###### `arm`: a named, functionally-computed attribute of a `core`
94−###### `core`: a code-data `cell`
100+The `twig` of each `arm` is compiled to a Nock formula, with the
101+enclosing `core` itself as the subject.
96−The code (`battery`) is the head, the data (`payload`) is the tail. All code-data structures in normal languages (functions, objects, modules, etc) become `core`s in Hoon.
103+There are two kinds of `arm`s: `dry` and `wet`. Most arms are
98−- `battery`: the code of a `core`, a tree of `arm`s
106+- `dry`: normal, `++`, polymorphic by means of *variance*
99−- `payload`: the data in a `core`
101−`core`s are *polymorphic* structures; every function call (`gate`) in Hoon replaces the `payload` of a `core` with a different `noun`, and then invokes an `arm` from the `battery`.
108+For a `dry` `arm`, we ask, is the new `payload` compatible with
109+the old `payload` (against which the `core` was compiled)?
103−- `wet`: polymorphic by means of *genericity*
111+- `wet`: unusual, `--`, polymorphic by means of *genericity*
113+A `wet` `arm` uses the `twig` as a macro. We create a new type
105−A `wet` `arm` uses the `twig` as a macro. We create a new type analysis path, which works as if we expanded the callee with the caller's context.
114+analysis path, which works as if we expanded the callee with the
107−- `dry`: polymorphic by means of *variance*
117+*See [advanced types](/hoon/advanced)*.
109−For a `dry` `arm`, we ask, is the new `payload` compatible with the old `payload` (against which the `core` was compiled)?
119+###### `metal`: a variance model
111−Every `core` has a `metal` which defines its *variance* model (ie, the properties of the `span` of a compatible `core`).
121+Every `core` has a `metal` which defines its *variance* model
122+(ie, the properties of the `span` of a compatible `core`).
123+The default is `gold` (invariant).
113- `gold`: *invariant*
125- `gold`: *invariant*
114- `lead`: *bivariant*
126- `lead`: *bivariant*
115−- `zync`: *covariant*
127+- `zinc`: *covariant*
116- `iron`: *contravariant*
128- `iron`: *contravariant*
118*See [advanced types](/hoon/advanced)*.
130*See [advanced types](/hoon/advanced)*.
120−###### `arm`: a named, functionally-computed attribute of a `core`
132+###### `gate`: a function/lambda/closure
122−The `twig` of each `arm` is compiled to a Nock formula, with the enclosing `core` itself as the subject.
134+A `gate` is a `core` with one `arm`. To call a `gate` on an
135+argument, replace the `sample` (at tree address `6` in the
136+`core`) with the argument, and then compute the `arm`.
124−*See [basic types](/hoon/basic)*.
138+The `payload` of a `gate` has a shape of `{sample context}`.
140+- `sample`: the argument tuple
141+- `context`: the subject in which the `gate` was defined
143+*See [basic types](/hoon/basic/#-core-p-span-q-map-term-span), [`%-` or `:call`](/hoon/twig/cen-call/hep-call/) (the `twig` for calling a `gate`).*
145+###### `mold`: a type constructor / validator
126−###### `foot`: a `wet` or `dry` `arm`
147+A mold is an idempotent `gate` (function), accepting any `noun`,
148+and producing a range with a useful `span`.
150+- `bunt`: the value a `mold` produces when normalizing its default sample
151+- `icon`: the `span` of the `mold`'s range
153+*See [`mold` `twig`s](/hoon/twig/buc-mold/).*
128###### `atom`
155###### `atom`
157+A Hoon `atom` span describes a Nock `atom`, with two additional
130−A Hoon `atom` is a Nock `atom`, with two additional pieces of metadata: an `aura`, and an optional constant.
158+pieces of metadata: an `aura`, and an optional constant.
132−`atom`s are `warm` or `cold` based on whether the constant exists.
160+An `atom` span are `warm` or `cold` based on whether the constant
134- `warm`: if the constant is `~` (null), any `atom` is in the `span`
163- `warm`: if the constant is `~` (null), any `atom` is in the `span`
135- `cold`: if the constant is `[~ atom]`, its only legal value is `atom`.
164- `cold`: if the constant is `[~ atom]`, its only legal value is `atom`.
@@ -138,62 +167,101 @@ A Hoon `atom` is a Nock `atom`, with two additional pieces of metadata: an `aura
139###### `aura`: a soft `atom` type
168###### `aura`: a soft `atom` type
141−`aura` is a name for an atom type. It represents the structure of an `atom` in a string beginning with `@`. Any `aura` may change into any other by casting it through `@`, which by itself is an empty `aura`: [nominal equivalence](https://en.wikipedia.org/wiki/Nominal_type_system), rather than [structural equivalence](https://en.wikipedia.org/wiki/Structural_type_system).
170+`aura` is a name for an atom type. It represents the structure of
171+an `atom` in a string beginning with `@`. An aura may represent
172+units, print format, or other semantics. Its constraints on the
173+value of an atom aren't enforced in any way.
143−- `term` (`@tas`): a symbol - an atomic ASCII string which obeys symbol rules: lowercase and digit only, infix hyphen ("kebab-case"), first character must be lowercase alphabetic.
175+Two `aura`s are compatible if one is a prefix of the other. You
176+can change any `aura` into any other `aura` by casting through
177+the empty `aura`, `@`. The standard library has molds which
178+alias many common auras.
145−- `cord` (`@t`): UTF-8 text, least-significant-byte first
180+Some common auras and their aliases:
182+- `term` (`@tas`): a symbol - an atomic ASCII string which obeys symbol rules: lowercase and digit only, infix hyphen ("kebab-case"), first character must be lowercase alphabetic.
183+- `cord` (`@t`): UTF-8 text, least-significant-byte first
147- `char` (`@td`): a character, a single unicode byte (for multi-byte characters and codepoints, see `@c`)
184- `char` (`@td`): a character, a single unicode byte (for multi-byte characters and codepoints, see `@c`)
149−- `tape` (`(list char)`): a `tape` is not an `aura`, but a `mold` for a list where every item has an `aura` of `char`.
151*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
186*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
153−###### `loobean`: a Hoon boolean
188+###### `twig`: a Hoon expression
155−`0` (`%.y`) is *true*, `1` (`%.n`) is *false*.
190+A `twig` is a Hoon expression. Specifically, `twig` is the mold
191+for the noun that a Hoon source expression compiles to. A twig
157−> Why? It's fresh, it's different, it's new. And it's annoying. And it keeps you on your toes. And it's also just intuitively right.
194+A twig has one of two forms: `{twig twig}`, which produces the
195+ordered pair of the two twigs, or a cell `{stem bulb}`, where
196+`stem` is an atomic symbol.
159−###### `twig`: a Hoon expression
198+- `stem`: an atomic symbol (`@tas`) - the name of a `twig`.
199+- `bulb`: The `mold` of the `twig`'s contents.
161−A `twig` is the name for any Hoon expression, and for the AST node representing the expression as compiled to a Nock formula. It is a `book` with the form `{stem bulb}`.
201+Most `twig`s have a *regular form*, beginning with a `sigil`
202+which is either a `keyword` or a `rune`. Some `twig`s also have
203+a syntactic *irregular form*; a few have *only* an *irregular
163−- `book`: a tagged-union
206+- `sigil`: a `keyword` or `rune` used to begin a `twig`
164−- `page`: an item in a `book`
207+- `keyword`: the value of a stem, prefixed with `:`.
165−- `stem`: an atomic symbol (`@tas`) - the name of a `twig`
208+- `rune`: a pair of ASCII symbols used to begin a `twig`.
166−- `bulb`: The `mold` of the `twig`'s arguments.
168−The vast majority of `twig`s have a *regular form*, beginning with either a keyword `sigil` or a digraph `rune`. Some `twig`s also have a syntactic *irregular form*, a handful have *only* an *irregular form*.
210+For example, the stem `%if` becomes the keyword
211+[`:if`](../../hoon/twig/wut-test/col-if/), with the rune `?:`.
212+The first symbol in a rune represents a family of related
213+`twig`s. For example, the [`?` family](../../hoon/twig/wut-test/)
214+are all conditionals.
170−- `sigil`: a keyword used to begin a `twig`
216+The keyword or rune forms are up to the programmer's choice.
217+Most existing code uses runes, but the keyword form makes the
218+learning path easier.
172−Hoon does not have reserved words, but `sigil`s (prefixed with `:`), which are effectively aliases for `rune`s. For example, [`:if` is `?:`](../../hoon/twig/wut-test/col-if/).
220+A regular twig has two syntactic forms, *tall* and *flat*:
174−- `rune`: a pair of ASCII symbols used to begin a `twig` - the first symbol represents a family of related `twig`s. For example, the [`?` family](../../hoon/twig/wut-test/) are all conditionals.
222+- `tall`: multiple lines, no parentheses, two or more spaces between tokens
223+- `flat`: one line, parentheses, one space between tokens
176−*regular forms* can alternate between *tall* and *wide* (or *flat*) syntax, *irregular forms* can use only the *wide*/*flat* syntax.
225+`tall` twigs can contain `flat` ones, but not vice versa. All
226+irregular forms are `flat`.
178*See [`twig` concept](../../hoon/concepts/#-twig-expression), [expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
228*See [`twig` concept](../../hoon/concepts/#-twig-expression), [expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
180###### `limb`: attribute or variable reference
230###### `limb`: attribute or variable reference
232+To resolve a `limb` named "foo", the `subject` is searched
182−To resolve a `limb` named "foo", the `subject` is searched depth-first, head-first for either a `face` named "foo" or a `core` with an `arm` of "foo". If a `face` is found, the result is a `leg`, if a `core` is found, the result is the `product` of the `arm`.
233+depth-first, head-first for either a `face` named "foo" or a
234+`core` with an `arm` of "foo". If a `face` is found, the result
235+is a `leg`, if a `core` is found, the result is the `product` of
184−- `leg`: a subexpression, or subtree of the `subject`. usually another `twig`, sometimes a symbol (`@tas`) or `wing`
238+- `leg`: a subexpression, or subtree of the `subject`.
185−- `wing`: a list of `limb`s
239+- `wing`: a list of `limb`s, searched from right to left (`a.b` means `b` within `a`).
187*See [Limbs and wings](../../hoon/twig/limb)*
241*See [Limbs and wings](../../hoon/twig/limb)*
189−###### `face`: a named variable
243+###### `face`: a labeled subtree
191−Hoon has no scope or symbol-table; there is only the `subject`. To "declare" a "variable" is to construct a new `subject`: `[variable old-subject]`.
245+Hoon has no scope or symbol-table; there is only the `subject`.
246+To "declare" a "variable" is to construct a new `subject`:
247+`[name=value old-subject]`.
193−A `face` wraps a name (`@tas`) around a `span`.
249+A `face` is a `span` that wraps a name (`@tas`) around another `span`.
195*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
251*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
197−###### `nest`: a type-casting operation
253+###### `nest`: type compatibility test
255+`nest` is an internal function on two spans, which produces yes
256+if the set of nouns in the second span is provably a subset of
259+*See [advanced types](../../hoon/advanced/)*.
261+###### `loobean`: a Hoon boolean
263+`0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
199−`nest` checks if the type of the second child is a subset of the type of the first chile. That's a short summary. To go in-depth, see [advanced types](../../hoon/advanced/).
265+> Why? It's fresh, it's different, it's new. And it's annoying.
266+> And it keeps you on your toes. And it's also just intuitively