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