git.iko.soy/urbit.org
on master help sign in
reformats glossary with pandoc (a la contributing.md)
a93481bJoseph Bryan
docs/about/glossary.md+130−127
compare with master
unifiedsplit
@@ -1,24 +1,23 @@
1---
1---
2−navhome: /docs
2+navhome: '/docs'
3−next: true
3+next: True
4sort: 3
4sort: 3
5title: Urbit glossary
5title: Urbit glossary
6---
6---
7
7
8# Urbit glossary
8# Urbit glossary
9
9
10−Urbit is renowned for its exotic terminology. Here's a simple
10+Urbit is renowned for its exotic terminology. Here's a simple overview
11−overview from the strange words in.
11+from the strange words in.
12
12
13−As Dijkstra put it: "The purpose of abstraction is not to be
13+As Dijkstra put it: "The purpose of abstraction is not to be vague, but
14−vague, but to create a new semantic level in which one can be
14+to create a new semantic level in which one can be absolutely precise."
15−absolutely precise."
16
15
17## Ships
16## Ships
18
17
19−An Urbit `ship` is a cryptographic identity, a human-memorable
18+An Urbit `ship` is a cryptographic identity, a human-memorable name, and
20−name, and a packet routing address. Ships are classed by the
19+a packet routing address. Ships are classed by the number of bits in
21−number of bits in their address:
20+their address:
22
21
23 Size Name Parent Object Example
22 Size Name Parent Object Example
24 ----- ------ ------ ------ -------
23 ----- ------ ------ ------ -------
@@ -32,66 +31,68 @@ Any ship can be called an `urbit`.
32
31
33> A summary [here](http://urbit.org/posts/address-space/).
32> A summary [here](http://urbit.org/posts/address-space/).
34
33
35−An Urbit identity is a string like `~firbyr-napbes`. It
34+An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
36−means nothing, but it's easy to remember and say out loud.
35+but it's easy to remember and say out loud. `~firbyr-napbes` is actually
37−`~firbyr-napbes` is actually just a 32-bit number, like an IP address,
36+just a 32-bit number, like an IP address, that we turn into a
38−that we turn into a human-memorable string.
37+human-memorable string.
39
38
40Technically, an urbit is a secure digital identity that you own and
39Technically, an urbit is a secure digital identity that you own and
41−control with a cryptographic key, like a Bitcoin wallet. As in
40+control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
42−Bitcoin, the supply of urbits is mathematically limited. This keeps
41+the supply of urbits is mathematically limited. This keeps the network
43−the network friendly, by making spam and abuse expensive.
42+friendly, by making spam and abuse expensive.
44
43
45An urbit name is just a number; smaller numbers make shorter names.
44An urbit name is just a number; smaller numbers make shorter names.
46−Shorter names are easier to remember, so they're more valuable. So
45+Shorter names are easier to remember, so they're more valuable. So
47−urbits are classified by the number of bits in their name. (A ship
46+urbits are classified by the number of bits in their name. (A ship name
48−name is just a scrambled base-256 representation of the number.)
47+is just a scrambled base-256 representation of the number.)
49
48
50A 32-bit urbit (like `~firbyr-napbes`) is called a "planet." A 16-bit
49A 32-bit urbit (like `~firbyr-napbes`) is called a "planet." A 16-bit
51urbit (like `~pollev)` is a "star." An 8-bit ship (like `~mun`) is a
50urbit (like `~pollev)` is a "star." An 8-bit ship (like `~mun`) is a
52−"galaxy." A planet is an identity for an independent, adult human.
51+"galaxy." A planet is an identity for an independent, adult human. Stars
53−Stars and galaxies are network infrastructure.
52+and galaxies are network infrastructure.
54
53
55Each planet or star is launched by its "parent," the star or galaxy
54Each planet or star is launched by its "parent," the star or galaxy
56−whose number is its bottom half. So the planet `~firbyr-napbes`,
55+whose number is its bottom half. So the planet `~firbyr-napbes`,
57−`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef`
56+`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
58−or `48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of
57+`48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of `~mun`
59−`~mun` and all galaxies is `~zod`, `0`.
58+and all galaxies is `~zod`, `0`.
60
59
61### Nock
60### Nock
62
61
63> Nock is a Turing-complete, non-lambda combinator interpreter.
62> Nock is a Turing-complete, non-lambda combinator interpreter.
64
63
65−- `noun`: an `atom` or a `cell`
64+- `noun`: an `atom` or a `cell`
66−- `atom`: any natural number
65+- `atom`: any natural number
67−- `cell`: any ordered pair of `noun`s
66+- `cell`: any ordered pair of `noun`s
68−- `subject`: a `noun` - the data against which a `formula` is evaluated
67+- `subject`: a `noun` - the data against which a `formula` is
68+ evaluated
69−- `formula`: a `noun` - a function at the Nock level
69+- `formula`: a `noun` - a function at the Nock level
70−- `product`: a `noun` - the result of evaluating a `formula` against a `subject`
70+- `product`: a `noun` - the result of evaluating a `formula` against a
71+ `subject`
71
72
72*See [Nock definition](../../nock/definition/).*
73*See [Nock definition](../../nock/definition/).*
73
74
74### Hoon
75### Hoon
75
76
76−> Hoon is a strict, higher-order typed functional language that compiles itself to Nock.
77+> Hoon is a strict, higher-order typed functional language that compiles
78+> itself to Nock.
77
79
78###### `span`: an inferred type
80###### `span`: an inferred type
79
81
80−A `span` defines a set (finite or infinite) of `noun`s and
82+A `span` defines a set (finite or infinite) of `noun`s and ascribes some
81−ascribes some semantics to it. There is no Hoon syntax for a
83+semantics to it. There is no Hoon syntax for a `span`; it is always
82−`span`; it is always produced as the inferred range of an
84+produced as the inferred range of an expression (`twig`).
83−expression (`twig`).
84
85
85*See [basic types](../../hoon/basic/#-type-span-and-mold).*
86*See [basic types](../../hoon/basic/#-type-span-and-mold).*
86
87
87###### `core`: a code-data `cell`
88###### `core`: a code-data `cell`
88
89
89−The code (`battery`) is the head, the data (`payload`) is the
90+The code (`battery`) is the head, the data (`payload`) is the tail. All
90−tail. All code-data structures in normal languages (functions,
91+code-data structures in normal languages (functions, objects, modules,
91−objects, modules, etc) become `core`s in Hoon.
92+etc) become `core`s in Hoon.
92
93
93−- `battery`: the code of a `core`, a tree of `arm`s
94+- `battery`: the code of a `core`, a tree of `arm`s
94−- `payload`: the data in a `core`
95+- `payload`: the data in a `core`
95
96
96*See [basic types](../../hoon/basic)*.
97*See [basic types](../../hoon/basic)*.
97
98
@@ -100,150 +101,154 @@ objects, modules, etc) become `core`s in Hoon.
100The `twig` of each `arm` is compiled to a Nock formula, with the
101The `twig` of each `arm` is compiled to a Nock formula, with the
101enclosing `core` itself as the subject.
102enclosing `core` itself as the subject.
102
103
103−There are two kinds of `arm`s: `dry` and `wet`. Most arms are
104+There are two kinds of `arm`s: `dry` and `wet`. Most arms are dry.
104−dry.
105
105
106−- `dry`: normal, `++`, polymorphic by means of *variance*
106+- `dry`: normal, `++`, polymorphic by means of *variance*
107
107
108−For a `dry` `arm`, we ask, is the new `payload` compatible with
108+For a `dry` `arm`, we ask, is the new `payload` compatible with the old
109−the old `payload` (against which the `core` was compiled)?
109+`payload` (against which the `core` was compiled)?
110
110
111−- `wet`: unusual, `+-`, polymorphic by means of *genericity*
111+- `wet`: unusual, `+-`, polymorphic by means of *genericity*
112
112
113−A `wet` `arm` uses the `twig` as a macro. We create a new type
113+A `wet` `arm` uses the `twig` as a macro. We create a new type analysis
114−analysis path, which works as if we expanded the callee with the
114+path, which works as if we expanded the callee with the caller's
115−caller's context.
115+context.
116
116
117*See [advanced types](/hoon/advanced)*.
117*See [advanced types](/hoon/advanced)*.
118
118
119###### `metal`: a variance model
119###### `metal`: a variance model
120
120
121−Every `core` has a `metal` which defines its *variance* model
121+Every `core` has a `metal` which defines its *variance* model (ie, the
122−(ie, the properties of the `span` of a compatible `core`).
122+properties of the `span` of a compatible `core`). The default is `gold`
123−The default is `gold` (invariant).
123+(invariant).
124
124
125−- `gold`: *invariant*
125+- `gold`: *invariant*
126−- `lead`: *bivariant*
126+- `lead`: *bivariant*
127−- `zinc`: *covariant*
127+- `zinc`: *covariant*
128−- `iron`: *contravariant*
128+- `iron`: *contravariant*
129
129
130*See [advanced types](/hoon/advanced)*.
130*See [advanced types](/hoon/advanced)*.
131
131
132###### `gate`: a function/lambda/closure
132###### `gate`: a function/lambda/closure
133
133
134−A `gate` is a `core` with one `arm`. To call a `gate` on an
134+A `gate` is a `core` with one `arm`. To call a `gate` on an argument,
135−argument, replace the `sample` (at tree address `6` in the
135+replace the `sample` (at tree address `6` in the `core`) with the
136−`core`) with the argument, and then compute the `arm`.
136+argument, and then compute the `arm`.
137
137
138The `payload` of a `gate` has a shape of `{sample context}`.
138The `payload` of a `gate` has a shape of `{sample context}`.
139
139
140−- `sample`: the argument tuple
140+- `sample`: the argument tuple
141−- `context`: the subject in which the `gate` was defined
141+- `context`: the subject in which the `gate` was defined
142
142
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`).*
143+*See [basic types](../../hoon/basic/#-core-p-span-q-map-term-span),
144+[`%-` or `:call`](../../hoon/twig/cen-call/hep-call/) (the `twig` for
145+calling a `gate`).*
144
146
145###### `mold`: a type constructor / validator
147###### `mold`: a type constructor / validator
146
148
147−A mold is an idempotent `gate` (function), accepting any `noun`,
149+A mold is an idempotent `gate` (function), accepting any `noun`, and
148−and producing a range with a useful `span`.
150+producing a range with a useful `span`.
149
151
150−- `bunt`: the value a `mold` produces when normalizing its default sample
152+- `bunt`: the value a `mold` produces when normalizing its default
153+ sample
151−- `icon`: the `span` of the `mold`'s range
154+- `icon`: the `span` of the `mold`'s range
152
155
153*See [`mold` `twig`s](/hoon/twig/buc-mold/).*
156*See [`mold` `twig`s](/hoon/twig/buc-mold/).*
154
157
155###### `atom`
158###### `atom`
156
159
157−A Hoon `atom` span describes a Nock `atom`, with two additional
160+A Hoon `atom` span describes a Nock `atom`, with two additional pieces
158−pieces of metadata: an `aura`, and an optional constant.
161+of metadata: an `aura`, and an optional constant.
159
162
160−An `atom` span is `warm` or `cold` based on whether the constant
163+An `atom` span is `warm` or `cold` based on whether the constant exists.
161−exists.
162
164
163−- `warm`: if the constant is `~` (null), any `atom` is in the `span`
165+- `warm`: if the constant is `~` (null), any `atom` is in the `span`
164−- `cold`: if the constant is `[~ atom]`, its only legal value is `atom`.
166+- `cold`: if the constant is `[~ atom]`, its only legal value is
167+ `atom`.
165
168
166*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
169*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
167
170
168###### `aura`: a soft `atom` type
171###### `aura`: a soft `atom` type
169
172
170−`aura` is a name for an atom type. It represents the structure of
173+`aura` is a name for an atom type. It represents the structure of an
171−an `atom` in a string beginning with `@`. An aura may represent
174+`atom` in a string beginning with `@`. An aura may represent units,
172−units, print format, or other semantics. Its constraints on the
175+print format, or other semantics. Its constraints on the value of an
173−value of an atom aren't enforced in any way.
176+atom aren't enforced in any way.
174
177
175−Two `aura`s are compatible if one is a prefix of the other. You
178+Two `aura`s are compatible if one is a prefix of the other. You can
176−can change any `aura` into any other `aura` by casting through
179+change any `aura` into any other `aura` by casting through the empty
177−the empty `aura`, `@`. The standard library has molds which
180+`aura`, `@`. The standard library has molds which alias many common
178−alias many common auras.
181+auras.
179
182
180Some common auras and their aliases:
183Some common auras and their aliases:
181
184
185+- `term` (`@tas`): a symbol - an atomic ASCII string which obeys
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.
186+ symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),
187+ first character must be lowercase alphabetic.
183−- `cord` (`@t`): UTF-8 text, least-significant-byte first
188+- `cord` (`@t`): UTF-8 text, least-significant-byte first
184−- `char` (`@tD`): a character, a single unicode byte (for multi-byte characters and codepoints, see `@c`)
189+- `char` (`@tD`): a character, a single unicode byte (for multi-byte
190+ characters and codepoints, see `@c`)
185
191
186*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
192*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
187
193
188###### `twig`: a Hoon expression
194###### `twig`: a Hoon expression
189
195
190−A `twig` is a Hoon expression. Specifically, `twig` is the mold
196+A `twig` is a Hoon expression. Specifically, `twig` is the mold for the
191−for the noun that a Hoon source expression compiles to. A twig
197+noun that a Hoon source expression compiles to. A twig is always a cell.
192−is always a cell.
193
198
194−A twig has one of two forms: `{twig twig}`, which produces the
199+A twig has one of two forms: `{twig twig}`, which produces the ordered
195−ordered pair of the two twigs, or a cell `{stem bulb}`, where
200+pair of the two twigs, or a cell `{stem bulb}`, where `stem` is an
196−`stem` is an atomic symbol.
201+atomic symbol.
197
202
198−- `stem`: an atomic symbol (`@tas`) - the name of a `twig`.
203+- `stem`: an atomic symbol (`@tas`) - the name of a `twig`.
199−- `bulb`: The `mold` of the `twig`'s contents.
204+- `bulb`: The `mold` of the `twig`'s contents.
200
205
201−Most `twig`s have a *regular form*, beginning with a `sigil`
206+Most `twig`s have a *regular form*, beginning with a `sigil` which is
202−which is either a `keyword` or a `rune`. Some `twig`s also have
207+either a `keyword` or a `rune`. Some `twig`s also have a syntactic
203−a syntactic *irregular form*; a few have *only* an *irregular
208+*irregular form*; a few have *only* an *irregular form*.
204−form*.
205
209
206−- `sigil`: a `keyword` or `rune` used to begin a `twig`
210+- `sigil`: a `keyword` or `rune` used to begin a `twig`
207−- `keyword`: the value of a stem, prefixed with `:`.
211+- `keyword`: the value of a stem, prefixed with `:`.
208−- `rune`: a pair of ASCII symbols used to begin a `twig`.
212+- `rune`: a pair of ASCII symbols used to begin a `twig`.
209
213
210For example, the stem `%if` becomes the keyword
214For example, the stem `%if` becomes the keyword
211−[`:if`](../../hoon/twig/wut-test/col-if/), with the rune `?:`.
215+[`:if`](../../hoon/twig/wut-test/col-if/), with the rune `?:`. The first
212−The first symbol in a rune represents a family of related
216+symbol in a rune represents a family of related `twig`s. For example,
213−`twig`s. For example, the [`?` family](../../hoon/twig/wut-test/)
214−are all conditionals.
217+the [`?` family](../../hoon/twig/wut-test/) are all conditionals.
215
218
216−The keyword or rune forms are up to the programmer's choice.
219+The keyword or rune forms are up to the programmer's choice. Most
217−Most existing code uses runes, but the keyword form makes the
220+existing code uses runes, but the keyword form makes the learning path
218−learning path easier.
221+easier.
219
222
220A regular twig has two syntactic forms, *tall* and *flat*:
223A regular twig has two syntactic forms, *tall* and *flat*:
221
224
222−- `tall`: multiple lines, no parentheses, two or more spaces between tokens
225+- `tall`: multiple lines, no parentheses, two or more spaces between
226+ tokens
223−- `flat`: one line, parentheses, one space between tokens
227+- `flat`: one line, parentheses, one space between tokens
224
228
225−`tall` twigs can contain `flat` ones, but not vice versa. All
229+`tall` twigs can contain `flat` ones, but not vice versa. All irregular
226−irregular forms are `flat`.
230+forms are `flat`.
227
231
228−*See [`twig` concept](../../hoon/concepts/#-twig-expression), [expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
232+*See [`twig` concept](../../hoon/concepts/#-twig-expression),
233+[expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
229
234
230###### `limb`: attribute or variable reference
235###### `limb`: attribute or variable reference
231
236
232−To resolve a `limb` named "foo", the `subject` is searched
237+To resolve a `limb` named "foo", the `subject` is searched depth-first,
233−depth-first, head-first for either a `face` named "foo" or a
238+head-first for either a `face` named "foo" or a `core` with an `arm` of
234−`core` with an `arm` of "foo". If a `face` is found, the result
239+"foo". If a `face` is found, the result is a `leg`, if a `core` is
235−is a `leg`, if a `core` is found, the result is the `product` of
240+found, the result is the `product` of the `arm`.
236−the `arm`.
237
241
238−- `leg`: a subexpression, or subtree of the `subject`.
242+- `leg`: a subexpression, or subtree of the `subject`.
239−- `wing`: a list of `limb`s, searched from right to left (`a.b` means `b` within `a`).
243+- `wing`: a list of `limb`s, searched from right to left (`a.b` means
244+ `b` within `a`).
240
245
241*See [Limbs and wings](../../hoon/twig/limb)*
246*See [Limbs and wings](../../hoon/twig/limb)*
242
247
243###### `face`: a labeled subtree
248###### `face`: a labeled subtree
244
249
245−Hoon has no scope or symbol-table; there is only the `subject`.
250+Hoon has no scope or symbol-table; there is only the `subject`. To
246−To "declare" a "variable" is to construct a new `subject`:
251+"declare" a "variable" is to construct a new `subject`:
247`[name=value old-subject]`.
252`[name=value old-subject]`.
248
253
249A `face` is a `span` that wraps a name (`@tas`) around another `span`.
254A `face` is a `span` that wraps a name (`@tas`) around another `span`.
@@ -252,9 +257,8 @@ A `face` is a `span` that wraps a name (`@tas`) around another `span`.
252
257
253###### `nest`: type compatibility test
258###### `nest`: type compatibility test
254
259
255−`nest` is an internal function on two spans, which produces yes
260+`nest` is an internal function on two spans, which produces yes if the
256−if the set of nouns in the second span is provably a subset of
261+set of nouns in the second span is provably a subset of the first.
257−the first.
258
262
259*See [advanced types](../../hoon/advanced/)*.
263*See [advanced types](../../hoon/advanced/)*.
260
264
@@ -262,6 +266,5 @@ the first.
262
266
263`0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
267`0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
264
268
265−> Why? It's fresh, it's different, it's new. And it's annoying.
269+> Why? It's fresh, it's different, it's new. And it's annoying. And it
266−> And it keeps you on your toes. And it's also just intuitively
270+> keeps you on your toes. And it's also just intuitively right.
267−> right.