@@ -8,191 +8,446 @@ title: Glossary
10Urbit is renowned for its exotic terminology. Here's a simple overview
10Urbit is renowned for its exotic terminology. Here's a simple overview
11−from the strange words in.
11+from the strange words within.
13As Dijkstra put it: "The purpose of abstraction is not to be vague, but
13As Dijkstra put it: "The purpose of abstraction is not to be vague, but
14to create a new semantic level in which one can be absolutely precise."
14to create a new semantic level in which one can be absolutely precise."
16−## Ships
16+### application
18−An Urbit *ship* is a cryptographic title on a *will* signed by private
18+Also known as an “app,” an *application* is a Hoon program that can hold state.
19−key, a human-memorable name, and a packet routing address. Ships are
20−classed by the number of bits in their address:
22− Size Name Parent Object Example
20+### arm
23− ----- ------ ------ ------ -------
24− 2^8 galaxy ~ supernode ~zod
25− 2^16 star galaxy supernode ~dozbud
26− 2^32 planet star user ~tasfyn-partyv
27− 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
28− 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
30−Any ship can be called an "urbit."
22+An *arm* is a named, functionally-computed attribute of a [core](#-core).
32−> You can find a longer-form summary here:
24+The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the
33−> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).
25+enclosing [core](#-core) itself as the subject.
35−An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
27+There are two kinds of arms: *dry* and *wet*. Most arms are
36−but it's easy to remember and say out loud. `~firbyr-napbes` is actually
28+dry.
37−just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
38−that we turn into a human-memorable string. The full name of this string
39−can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
40−when running a ship with a longer name, such as a *moon* or a *comet*.
42−Technically, an urbit is a secure digital identity that you own and
30+- ##### dry:
43−control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
44−the supply of urbits is mathematically limited. This keeps the network
45−friendly, by making spam and abuse expensive.
47−An urbit name is just a number; smaller numbers make shorter names.
32+ normal, `++`, polymorphic by means of *variance*
48−Shorter names are easier to remember, so they're more valuable. So
49−urbits are classified by the number of bits in their name. (A ship name
50−is just a scrambled base-256 representation of the number.)
52−A 32-bit urbit (like `~firbyr-napbes`) is called a *planet.* A 16-bit
34+ For a dry arm, we ask: is the new payload compatible with the old
53−urbit (like `~pollev)` is a *star.* An 8-bit ship (like `~mun`) is a
35+ payload (against which the core was compiled)?
54−*galaxy.* A planet is an identity for an independent, adult human. Stars
55−and galaxies are network infrastructure.
57−Each planet or star is launched by its *parent,* the star or galaxy
37+- ##### wet:
58−whose number is its bottom half. So the planet `~firbyr-napbes`,
59−`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
60−`48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of `~mun`
61−and all galaxies is `~zod`, `0`.
63−#### pier
39+ unusual, `+-`, polymorphic by means of *genericity*
65−A ship's *pier* is its Unix directory. For planets the name of the pier is usually the planet name.
41+ A wet arm uses the hoon as a macro. We create a new type analysis
42+ path, which works as if we expanded the callee with the caller's
67−### Nock
45+*See [advanced types](../../hoon/advanced/)*.
69−> Nock is a Turing-complete, non-lambda combinator interpreter.
71−- <h6 id="-nock-noun">noun:</h6> an _atom_ or a _cell_
48+### Arvo
72−- <h6 id="-nock-atom">atom:</h6> any natural number
73−- <h6 id="-nock-cell">cell:</h6> any ordered pair of nouns
74−- <h6 id="-nock-subject">subject:</h6> a noun - the data against which a _formula_ is
76−- <h6 id="-nock-formula">formula:</h6> a noun - a function at the Nock level
77−- <h6 id="-nock-product">product:</h6> a noun - the result of evaluating a formula against a
80−*See [Nock definition](../../nock/definition/).*
50+The Urbit operating system and kernel. Arvo's state is a pure function of its
51+event log, and it serves as the Urbit event manager. It contains vanes, which are
52+kernel modules that perform essential system operations. Arvo itself can only
53+deal with one file at a time. For more, it relies on Ford, the build-system
82−## Hoon
56+Arvo being purely functional means that the it is a function that is:
84−> Hoon is a strict, higher-order typed functional language that compiles
58+> (state, event) → (state, effects).
87−#### arm
60+Arvo coordinates and reloads vanes. It can be thought of as a traffic-director.
61+Any vane needs to go through Arvo before reaching another vane. Events and
62+their effects happen like so:
89−An _arm_ is a named, functionally-computed attribute of a [core](#-core).
64+> Unix event → vere (the virtual machine that runs Urbit) → Arvo → vane → Arvo
91−The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the
66+Arvo is located in `/home/sys/arvo.hoon` within your urbit.
92−enclosing [core](#-core) itself as the subject.
94−There are two kinds of arms: *dry* and *wet*. Most arms are dry.
68+More in-depth information on Arvo can be found
69+[`here`](https://urbit.org/docs/arvo/internals/).
96−- <h6 id="-arm-dry">dry:</h6> normal, `++`, polymorphic by means of *variance*
71+Below are Arvo modules, which are called "vanes".
98−For a dry arm, we ask, is the new payload compatible with the old
73+- #### Ames
99−payload (against which the core was compiled)?
101−- <h6 id="-arm-wet">wet:</h6> unusual, `+-`, polymorphic by means of *genericity*
75+The networking vane. Ames handles all things UDP. Here live the protocols for
76+discovering and interacting with other urbits. It’s also the name for the Urbit
77+network itself. All communication is signed and encrypted.
103−A wet arm uses the hoon as a macro. We create a new type analysis
79+Ames is located in `/home/sys/vane/ames.hoon` within your urbit.
104−path, which works as if we expanded the callee with the caller's
107−*See [advanced types](../../hoon/advanced/)*.
81+More in-depth information on Ames can be found
82+[`here`](https://urbit.org/docs/arvo/internals/ames/commentary/).
86+The timing vane. Behn allows for applications to schedule events, which are
87+managed in a simple priority queue. For example, Clay, the Urbit filesystem,
88+uses Behn to keep track of time-specific file requests. Eyre, the Urbit web
89+vane, uses Behn for timing-out HTTP sessions.
91+Behn is located in `/home/sys/vane/behn.hoon` within your urbit.
95+The filesystem and typed revision-control vane. Think of Clay as a
96+continuously synced git. It handles file-change events and maps them from Urbit
97+to Unix and vice versa.
99+A common way to use it is to create a pier, a directory that exists in and is
100+visible in Unix. Changes are automatically recorded from Urbit to the Unix
101+directory, and vice versa. Just set it and forget it!
103+Clay is located at `/home/sys/vane/clay.hoon` within your urbit.
105+Basic information on using Clay can be found
106+[`here`](https://urbit.org/docs/using/filesystem/). An in-depth explanation
107+of the architecture can be found
108+[`here`](https://urbit.org/docs/arvo/internals/clay/architecture/).
112+The terminal-driver vane. You run your urbit in your Unix terminal, and
113+Unix sends every event -- such as a keystroke or a change in the dimensions of
114+the terminal window -- to be handled by Dill. Dill acts as an intermediary for
115+anything that uses keyboard events. This is why there’s some input lag in
116+Urbit’s command-line interface. (Optimization will come later!)
118+A keyboard event's journey from Unix to Dojo, the Urbit shell, can be imagined
119+ as diagrammed below:
121+> Keystroke in Unix terminal -> Vere (virtual machine) -> Arvo -> Dill ->
124+Dill is located at `/home/sys/vane/clay.hoon` within your urbit.
126+More in-depth information on Eyre can be found
127+[`here`](https://urbit.org/docs/arvo/internals/dill/).
131+The web-server vane. Anything HTTP-related lives here. Unix sends HTTP messages
132+though to Eyre, and Eyre produces HTTP messages in response.
134+In general, apps and vanes do not call Eyre; rather, Eyre calls apps and vanes.
135+Eyre uses Ford and Gall to functionally publish pages and facilitate
136+communication with apps.
138+Eyre is located at `/home/sys/vane/eyre.hoon` within your urbit.
140+More in-depth information on Eyre can be found
141+[`here`](https://urbit.org/docs/using/web/).
109−#### atom
143+- #### Ford
145+The build-system vane. Ford is capable of sequencing generic asynchronous
146+computations. Its uses include linking source files into programs, assembling
147+live-updating websites, and performing file-type conversions.
149+Ford neither accepts Unix events nor produces Unix effects. It exists
150+entirely for the benefit of Urbit applications and other vanes, in particular
153+Ford is located at `/home/sys/vane/ford.hoon` within your urbit.
155+More in-depth information on Ford can be found
156+[`here`](https://urbit.org/docs/arvo/internals/ford/).
160+The application-management vane. Userspace apps -- daemons, really -- are
161+started, stopped, and sandboxed by Gall. Gall provides developers with a
162+consistent interface for hooking their app up to the operating system. It allows
163+applications and other vanes to send messages to applications and subscribe to
164+data streams. Messages coming into Gall are routed to the intended application,
165+and the response comes back along the same route. If the intended target is on
166+another ship, Gall will route it, behind the scenes, through Ames to the other
169+Gall is located at `/home/sys/vane/gall.hoon` within your urbit.
171+More in-depth information on Ford can be found
172+[`here`](https://urbit.org/docs/arvo/internals/gall/).
176+An atom is any natural number, including zero. The atom is the most basic data
177+type in [Nock](#-nock) and [Hoon](#-hoon). A Hoon atom type describes a Nock
111−A Hoon _atom_ type describes a Nock atom, with two additional pieces
178+atom with two additional pieces of metadata: an [*aura*](#-aura), and an
112−of metadata: an *aura*, and an optional constant.
179+optional constant.
114An atom type is *warm* or *cold* based on whether the constant exists.
181An atom type is *warm* or *cold* based on whether the constant exists.
116−- <h6 id="-atom-warm">warm:</h6> if the constant is `~` (null), any
184+ if the constant is `~` (null), any atom is in the type.
117− atom is in the type
185+- ##### cold:
118−- <h6 id="-atom-cold">cold:</h6> if the constant is `[~ atom]`, its
119− only legal value is `atom`.
186+ if the constant is `[~ atom]`, its only legal value is `atom`.
121*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
188*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
123−#### aura
190+### Aura
192+An aura a soft atom type. They appear as strings beginning with `@`. Auras
193+represent the structure of an atom, print format, or other semantics. Its
194+constraints on the value of an atom aren't enforced in any way.
196+You can cast something to an aura, like a decimal, and get back its hexademical.
203+Auras are an advisory type system. You can go up or down, but not sideways in
204+the hierarchy. `@t` and `@` can each be cast to the other, but @t can’t be cast
205+to `@u`, for example, without first being cast to the empty aura `@`.
125−An *aura* is a soft atom type. It represents the structure of an
209+ > ^- @ 'c' :: 'c' is of the aura @t
126−atom in a string beginning with `@`. An aura may represent print
210+ 99
127−format or other semantics. Its constraints on the value of an
128−atom aren't enforced in any way.
130−Two auras are compatible if one is a prefix of the other. You can
212+ > ^- @u 'c'
131−change any aura into any other aura by casting through the empty
213+ ! exit
132−aura, `@`. The standard library has molds which alias many common
135−Some common auras and their aliases:
215+Here is a non-exhaustive list of auras:
137−- <h6 id="-aura-term">term:</h6> (`@tas`): a symbol - an atomic ASCII string which obeys
217+```
138− symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),
218+Aura Meaning Example Literal Syntax
139− first character must be lowercase alphabetic.
219+-------------------------------------------------------------------------
140−- <h6 id="-aura-cord">cord:</h6> (`@t`): UTF-8 text, least-significant-byte first
220+@d date
141−- <h6 id="-aura-char">char:</h6> (`@tD`): a character, a single unicode byte (for multi-byte
221+ @da absolute date ~2018.5.14..22.31.46..1435
142− characters and codepoints, see `@c`)
222+@n nil ~
223+@p phonemic string (ship name) ~sorreg-namtyv
224+@r IEEE floating-point
225+ @rd double precision (64 bits) .~6.02214085774e23
226+ @rh half precision (16 bits) .~~3.14
227+@s signed integer, sign-bit low
228+ @sb signed binary --0b11.1000
229+ @sd signed decimal --1.000.056
230+ @sx signed hexadecimal -0x5f5.e138
231+@t UTF-8 text (cord) 'howdy'
232+ @ta ASCII text (knot) ~.howdy
233+ @tas ASCII text symbol (term) %howdy
235+ @ub unsigned binary 0b11.1000
236+ @ud unsigned decimal 1.000.056
237+ @ux unsigned hexadecimal 0x5f5.e138
144You can find the list of all auras [here](../../hoon/atom/sand/).
240You can find the list of all auras [here](../../hoon/atom/sand/).
146−*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
242+### blocksize
244+Blocksize is the power-of-two bitwidth of an atom. So, an atom with a blocksize
245+of `3` has a bitwidth of `2^3`, which is 8. A bitwidth of 8, in turn, can
246+represent `2^8` values, or 256.
250+To cast is to put a Hoon expression through the compiler’s type-checker to test
251+whether the expression is guaranteed to evaluate to a product that falls within
252+the desired type. If the expression is not guaranteed to behave in this way,
253+then the compiler will halt with a nest-fail crash. Proper Hoon code will
254+include a cast for the product type of each gate.
256+The cast rune is `^-` (pronounced "ket-hep"). So, to cast to a list of atoms,
257+we write `^- (list @)`. The irregular form of that expression is ``(list @)``.
261+In Nock and Hoon, a *cell* is an ordered pair of [nouns](#-noun).
265+Cells orient to the right; for example, the noun [2 6 14 15] is short for
271+A clam is the use of a structure as a gate. Usually used to verify marks from
274+ > ((list @t) [97 98 ~])
279+In Hoon, `cord` is an aura for representing atoms as strings. UTF-8,
280+least-significant bit first. Represented as the aura `@t`.
282+ > `@t`478.560.413.032
150−A _core_ is a [cell](#-nock-cell) of `[code data]`, where we call the
287+A *core* is a [cell](#-nock-cell) of `[code data]`, where we call the
151−code head the _battery_ and the data tail the _payload_. All code-data
288+code head the *battery* and the data tail the *payload*. All code-data
152structures in normal languages (functions, objects, modules, etc.)
289structures in normal languages (functions, objects, modules, etc.)
153−become _core_s in Hoon.
290+translate to cores in Hoon.
293+ The code-containing head of a core.
155−- <h6 id="-core-battery">battery:</h6> the code of a core, a tree of *arms*
295+- ##### payload
156−- <h6 id="-core-payload">payload:</h6> the data in a core
296+ The data-containing tail of a core.
158*See [basic types](../../hoon/basic)*.
298*See [basic types](../../hoon/basic)*.
160−#### face
300+### Dojo
302+The Dojo is the Urbit shell; the command line where you run programs,
303+expressions, and system commands. It’s a CLI that is encountered right when
304+an urbit is started for the first time. It is somewhat analogous to Bash, the
305+Unix terminal, and more analogous to a Hoon REPL.
307+You’ll notice that many things can’t be written here; this is normal. The Dojo
308+enforces syntactical correctness right at the command line. Strings that can’t
309+be continued into a valid expression are automatically trimmed back to something
310+ that can be. Some syntactically invalid expressions can be completed, but the
311+Dojo will prevent them from being entered as a command. You can play around
312+with this functionality learn what syntax is kosher.
162−A Hoon _face_ is a labeled subtree.
315+### duct
164−Hoon has no scope or symbol-table; there is only the subject. To
317+A duct is an Arvo-level call stack. At the beginning of every duct is a Unix
165−"declare" a "variable" is to construct a new subject:
318+event, such as a keystroke, network packet, timer event, or file change.
166−`[name=value old-subject]`.
168−A face is a type that wraps a named symbol (of [aura](#-aura)
320+A duct is a `list` of `wire`s. A wire is itself a `list` of `knot`s. A `knot`
169−`@tas`) around another type.
321+is, in turn, a knot.
325+A *face* is the Hoon analog to what is a variable name in most other
326+programming languages. Faces are metadata labels for legs, allowing us to
327+address parts. Because there is no metadata in Nock, faces cannot exist in Nock.
332+In the above example, `a` is the face and `2` is the value.
334+Hoon has no scope or symbol-table; there is only the subject. To "declare" a
335+"variable" is to construct a new subject: `[name=value old-subject]`.
171*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
337*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
342+A `flag` is Hoon's version of a boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is
345+> Why? It's fresh, it's different, it's new. And it's annoying. And it
346+> keeps you on your toes. And it's also just intuitively right.
175−A _gate_ is a [core](#-core) with one [arm](#-arm) -- Hoon's closest
350+A *gate* is a [core](#-core) with one [arm](#-arm) -- Hoon's closest
176−analog to a function/lambda/closure. To call a gate on an argument,
351+analog to a function. To call a gate on an argument, replace the sample
177−replace the sample (at [tree address](../../hoon/limb/limb/) `+6`
352+(at [tree address](../../hoon/limb/limb/) `+6`
178in the core) with the argument, and then compute the arm.
353in the core) with the argument, and then compute the arm.
180The payload of a gate has a shape of `[sample context]`.
355The payload of a gate has a shape of `[sample context]`.
182−- <h6 id="-gate-sample">sample:</h6> the argument tuple
358+ The argument tuple.
183−- <h6 id="-gate-context">context:</h6> the subject in which the gate was defined
360+ The subject in which the gate was defined.
185*See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),
362*See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),
186[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the
363[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the
187[rune](#-rune) for calling a `gate`).*
364[rune](#-rune) for calling a `gate`).*
189−#### <h4 id="-a-hoon">hoon</h4>
366+### generator
368+A *generator* is like a limited Hoon script: it’s a shell command that produces
369+a value before disappearing. Generators take an input [noun](#-noun) (a value)
370+and produce an output `noun` by performing calculations on its arguments,
371+prompting for input, or making HTTP requests.
373+You need a `bar` rune like `|=` in your generator, because a generator is
374+essentially a function that you’re calling.
376+Generators, unlike [apps](#-application), hold no state. They are pure,
377+stateless functions, and they cannot send [moves](#-move). Because of this,
378+generators are have a more narrow use than apps. Among the non-trivial uses of
379+a a generator is moving data into apps -- they’re the backbone of Urbit’s
380+information pipeline.
382+Generators are run from the `/gen` directory of your current desk. For example,
383+to run a generator named whatever.hoon, you would type `> +whatever` in the
388+A *glyph* is a single, non-alphanumeric ASCII character. Each glyph has its own
389+monosyllabic name, which allows the efficient communication of Hoon-related
390+information in speech. [`Runes`](#-rune) are composed of two glyphs.
391+Below is a complete list of glyphs with their associated pronunciations.
394+ace [1 space] hep - rob }
404+gap [>1 space, nl] rac ]
410+*Hall* is the Urbit communication back-end. It’s a messaging bus that can work
411+with clients of all sorts. [`:talk`](#-talk), the built-in chat client, is one
412+such app that uses Hall.
414+*More information on Hall can be found [here](../hall).*
418+ A circle is the “audience” of your messages -- who can receive them. It can be
419+ thought of as a chat channel, but this is a little too narrow. More
420+ specifically, it’s a named collection of messages created by and hosted on a
421+ ship’s Hall, usually represented as `~ship-name/circle-name`. On Talk,
422+ Urbit’s built-in chat front-end, the first circle that you will likely
423+ encounter is `/urbit-meta`.
427+*Hood* orchestrates many of the Urbit initialization systems necessary
432+Hoon is a strict, higher-order typed functional language that compiles itself
435+The Hoon source file is located in `/home/sys/hoon.hoon` within your urbit.
437+*More information can be found in the [hoon](../../hoon) section.*
441+ *Mint* is the Hoon compiler function. Mint takes the subject type and the
442+ expression source (a [hoon](#-a-hoon), for example) and produces the product
443+ type and nock formula. So [type hoon] is mapped to [type nock].
445+### <a id="-a-hoon">hoon</a>
191−A [`hoon`](../../hoon/reference/) is the result of parsing a Hoon source
447+A *hoon* (lowercase) is the result of parsing a Hoon source expression into an
192−expression into an AST node. These AST nodes are nouns, like all
448+AST node. These AST nodes are nouns, like all other Hoon data. Because every
193−other Hoon data. Because every Hoon program is, in its entirety, a
194−single expression of Hoon, the result of parsing the whole thing
449+Hoon program is, in its entirety, a single expression of Hoon, the result of
195−into an AST is a single `hoon`.
450+parsing the whole thing into an AST is a single `hoon`.
197A hoon is a tagged union of the form `[%tag data]`, where the tag
452A hoon is a tagged union of the form `[%tag data]`, where the tag
198is a constant such as `%brts` (from the source [rune](#-rune) `|=`,
453is a constant such as `%brts` (from the source [rune](#-rune) `|=`,
@@ -222,31 +477,107 @@ The result should be:
222[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
477[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
480+See [expression reference](../../hoon/reference/) for the
485+Irregular forms are alternative ways of writing Hoon expressions, alternatives
486+to the digraphic runes such as `:~`. Irregular forms are usually more compact
489+*See [irregular forms](../../hoon/irregular).*
493+A *jet* is a piece of C code that have equivalent products to a piece of Hoon or
494+ Nock code. They are used for performance reasons; jets are meant to be faster
495+than the code that they are substituting for.
497+Jets are necessary for mathematics, performance-wise, because Nock handles it
498+so inefficiently. Nock, for example, can’t decrement (reduce a number by one)
499+except by starting building a loop that starts from zero and increments to a
502+*See [API overview](../../vere/api).*
506+A lark is an expression that returns a [limb](#-limb) at the specified
507+address in a cell. Using `-` by itself returns the head of the subject, and
508+using `+` by itself returns the tail:
511+> -:[[4 5] [6 [14 15]]]
514+> +:[[4 5] [6 [14 15]]]
518+You can combine `+` or `-` with either of `>` or `<` to get a more specific limb
519+of the subject. `-<` returns the head of the head; `->` returns the tail of the
520+head; `+<` returns the head of the tail; and `+>` returns the tail of the tail.
521+By alternating the `+`/`-` symbols with `<`/`>` symbols, you can go as deep as
525+> +>-:[[4 5] [6 [14 15]]]
528+> +>+:[[4 5] [6 [14 15]]]
225−#### limb
532+### limb
227−A _limb_ is an attribute or variable reference.
534+A *limb* is an attribute or variable reference. A limb is an [arm](#-arm) or a
229To resolve a *limb* named "foo", the subject is searched depth-first,
537To resolve a *limb* named "foo", the subject is searched depth-first,
230head-first for either a face named "foo" or a core with an arm of
538head-first for either a face named "foo" or a core with an arm of
231"foo". If a face is found, the result is a leg, if a core is
539"foo". If a face is found, the result is a leg, if a core is
232found, the result is the product of the arm.
540found, the result is the product of the arm.
234−- <h6 id="-limb-leg">leg:</h6> a subexpression, or subtree of the subject.
543+ a subexpression, or subtree of the
544+ [subject](#nock-subject).
547+ a search path into the subject, composed of
235−- <h6 id="-limb-wing">wing:</h6> a list of limbs, searched from right to left (`a.b` means
548+ limbs. Search occurs from right to left (`a.b` means `b` within `a`).
238*See [Limbs and wings](../../hoon/limb/)*
550*See [Limbs and wings](../../hoon/limb/)*
240−#### loobean
552+### move
242−A _loobean_ is a Hoon boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
554+A move is the [Arvo](#-arvo) equivalent of a syscall.
558+In [Nock](#-nock) and [Hoon](#-hoon), a *noun* is an atom or a cell.
563+Nock is Nock is a Turing-complete, non-lambda combinator interpreter. It's
564+Urbit's low-level programming language. Nock is functional and typeless.
566+- <h5 id="-nock-noun">noun:</h5> an *atom* or a *cell*.
567+- <h5 id="-nock-atom">atom:</h5> any natural number, including zero.
568+- <h5 id="-nock-cell">cell:</h5> any ordered pair of nouns.
569+- <h5 id="-nock-subject">subject:</h5> a noun - the data against which a
570+ *formula* is evaluated.
571+- <h5 id="-nock-formula">formula:</h5> a noun - a function at the Nock level.
572+- <h5 id="-nock-product">product:</h5> a noun - the result of evaluating a
573+ formula against a subject.
575+*See the [Nock definition](../../nock/definition/).*
244−> Why? It's fresh, it's different, it's new. And it's annoying. And it
245−> keeps you on your toes. And it's also just intuitively right.
249−A _mark_ is Urbit's version of a MIME type, if a MIME type was an
580+A *mark* is Urbit's version of a MIME type, if a MIME type was an
250executable specification. The mark is just a label that's used as a path
581executable specification. The mark is just a label that's used as a path
251to a local source file in the Arvo filesystem. This source file defines
582to a local source file in the Arvo filesystem. This source file defines
252a core that can mold untrusted data, diff and patch, convert to other
583a core that can mold untrusted data, diff and patch, convert to other
@@ -259,7 +590,7 @@ that we at least handle the situation in a predictable way.
260#### metal
591#### metal
262−Every core has a _metal_ which defines its variance model (ie, the
593+Every core has a *metal* which defines its variance model (ie, the
263properties of the type of a compatible core). The default is `gold`
594properties of the type of a compatible core). The default is `gold`
264(invariant).
595(invariant).
@@ -270,33 +601,89 @@ properties of the type of a compatible core). The default is `gold`
271*See [advanced types](../../hoon/advanced)*.
602*See [advanced types](../../hoon/advanced)*.
273−#### mold
604+### ship
606+An Urbit *ship* is: a cryptographic title on a *will* signed by private key; a
607+human-memorable name; and a packet-routing address. Ships are classed by the
608+number of bits in their address:
610+ Size Name Parent Object Example
611+ ----- ------ ------ ------ -------
612+ 2^8 galaxy ~ supernode ~zod
613+ 2^16 star galaxy supernode ~dozbud
614+ 2^32 planet star user ~tasfyn-partyv
615+ 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
616+ 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
618+Any ship can be called an *urbit*. The lowercase "u" distinguishes it from Urbit
619+ the software stack and Urbit the network.
621+> You can find a longer-form summary here:
622+> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).
624+An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
625+but it's easy to remember and say out loud. `~firbyr-napbes` is actually
626+just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
627+that we turn into a human-memorable string. The full name of this string
628+can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
629+when running a ship with a longer name, such as a *moon* or a *comet*.
631+Technically, an urbit is a secure digital identity that you own and
632+control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
633+the supply of urbits is mathematically limited. This keeps the network
634+friendly, by making spam and abuse expensive.
636+An urbit name is just a number; smaller numbers make shorter names.
637+Shorter names are easier to remember, so they're more valuable. So
638+urbits are classified by the number of bits in their name. (A ship name
639+is just a scrambled base-256 representation of the number.)
641+A 32-bit urbit (like `~firbyr-napbes`) is called a *planet.* A 16-bit
642+urbit (like `~pollev)` is a *star.* An 8-bit ship (like `~mun`) is a
643+*galaxy.* A planet is an identity for an independent, adult human. Stars
644+and galaxies are network infrastructure.
646+Each planet or star is launched by its *parent,* the star or galaxy
647+whose number is its bottom half. So the planet `~firbyr-napbes`,
648+`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
649+`48.879`, whose parent is `~mun`, `0xef`, `239`. The galaxy at the address of
655+ A ship's *pier* is its Unix directory. For planets, the name of the pier is
656+ usually the planet name.
275−A _mold_ is an idempotent [gate](#-gate) (function), accepting any noun,
276−and producing a range with a type, a set of nouns.
278−Molds act as type constructor/validators in Hoon. An example: Arvo
659+
662+A *structure* is an idempotent [gate](#-gate) (function) that constructs and
663+validates types in Hoon.
279−[marks](#-marks) use Hoon's type system under the hood via molds to
665+An example: Arvo [marks](#-marks) use Hoon's type system via structures to
280validate untrusted network data.
666validate untrusted network data.
282−Here's some common mold terminology:
668+Here's some common structure terminology:
284−- <h6 id="-mold-bunt">bunt:</h6> the value a mold produces when normalizing its default
670+- #### bunt:
286−- <h6 id="-mold-icon">icon:</h6> the type of the mold's range
288−*See [mold hoons](../../hoon/rune/buc/).*
672+ A bunt is the default value of a [structure](#-structure). It's also a verb;
673+ to *bunt* a structure is to produce the bunt of that structure. For example,
674+ bunting `@` results in `0`, and bunting `@t` results in `''`. Bunting is
675+ performed with `*` followed by the structure in question:
290−#### nest
683+- #### icon: The type of the mold's range.
292−`nest` is an internal Hoon function on two types which performs a type
685+*See [mold hoons](../../hoon/rune/buc/).*
293−compatibility test. `nest` produces yes if the
294−set of nouns in the second type is provably a subset of the first.
295−If `nest` produces no, the Hoon programmer will receive a `nest-fail`
296−error. This is one of the most commons errors in Hoon programming.
298−*See [advanced types](../../hoon/advanced/)*.
299−*See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.
@@ -312,10 +699,10 @@ The result of parsing a Hoon source expression—the rune, followed
312by its respective children—into an AST node is simply called
699by its respective children—into an AST node is simply called
313a [`hoon`](#-a-hoon).
700a [`hoon`](#-a-hoon).
315−Runes have two syntactic forms, _tall_ and _flat_:
702+Runes have two syntactic forms, *tall* and *flat*:
317−- <h6 id="-rune-tall">tall:</h6> multiple lines, no parentheses, two or more spaces between
705+ multiple lines, no parentheses, two or more spaces between tokens
@@ -323,7 +710,8 @@ Runes have two syntactic forms, _tall_ and _flat_:
323 ~zod:dojo> %+ add 2 2
710 ~zod:dojo> %+ add 2 2
326−- <h6 id="-rune-flat">flat:</h6> one line, parentheses, one space between tokens
714+ one line, parentheses, one space between tokens
@@ -341,18 +729,39 @@ forms are flat.
341*See [hoon concept](../../hoon/concepts/#-hoon),
729*See [hoon concept](../../hoon/concepts/#-hoon),
342[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)*.
730[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)*.
344−#### slot
732+### Sail
734+*Sail* is the Hoon markup language for XML.
738+To *scry* means to request data from the Arvo namespace and bring it
741+*See [.^ (dot-ket)](../../hoon/rune/dot/ket/).*
346−`slot` is the name for Hoon's tree addressing scheme.
745+`slot` is the name for Hoon's tree-addressing scheme.
348Every cell has a head and a tail, each of which may be either an atom or
747Every cell has a head and a tail, each of which may be either an atom or
349a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
748a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
350the whole cell (technically this would work against an atom as well).
749the whole cell (technically this would work against an atom as well).
351The head of `+n` is `+2n`, the tail is `+(2n+1)`.
750The head of `+n` is `+2n`, the tail is `+(2n+1)`.
353−#### type
752+`+7` is a special address for gates, because the position is defined
753+(by convention) as the context of a gate and of all cores.
757+*Talk* is Urbit's built-in chat app. It’s one example of an app that can be
758+built on top of Hall, the Urbit back-end messaging system.
760+*See [Messaging](../using/messaging). for more information.*
355−A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes
764+A Hoon *type* defines a set (finite or infinite) of nouns and ascribes
356some semantics to it. There is no direct syntax for defining
765some semantics to it. There is no direct syntax for defining
357types; they are always defined by inference (i.e., by
766types; they are always defined by inference (i.e., by
358[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).
767[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).
@@ -362,4 +771,44 @@ All types are assembled out of base types defined in `++type`.
362does type-inference on a program, it assembles complex types out
771does type-inference on a program, it assembles complex types out
363of the simpler built-in types.
772of the simpler built-in types.
776+ `nest` is an internal Hoon function on two types which performs a type
777+ compatibility test. `nest` produces yes if the
778+ set of nouns in the second type is provably a subset of the first.
779+ If `nest` produces no, the Hoon programmer will receive a `nest-fail`
780+ error. This is one of the most commons errors in Hoon programming.
365−*See [basic types](../../hoon/basic/).*
782+ *See [advanced types](../../hoon/advanced/)*.
783+ *See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.
788+Hoon's equivalent of a nullable pointer or a Haskell Maybe. If `q` is `~`,
789+null, the type is *warm*; any atom is in the type. If `q` is `[~ x]`, where
790+`x` is any atom, the type is *cold*; its only legal value is the constant `x`.
794+A *vane* is an [Arvo](#-arvo) module. Each Vane is a single file because Arvo
795+cannot, on its own, deal with programs that are split between multiple files.
796+Some vanes can do this, however.
798+### Vere (pronounced “vair”)
800+The runtime system, written in C, that implements [Nock](#-nock). All
801+It’s written in C. Vere-level errors are prepended with as `bail:`.
803+Vere is a virtual machine: it pretends to be hardware, and is the single point
804+of contact between your Urbit and the rest of your system. But more than that,
805+Vere handles the Urbit event log and handles jets. It’s also contains the i/o
806+drivers for Urbit’s vanes, responsible for generating events from Unix and
807+applying effects to Unix.
811+*Zuse* is a defined interface for vanes. It contains the part of the Hoon
812+standard library that is specific to Arvo functionality.
814+Arvo is located in `/home/sys/zuse.hoon` within your urbit.