@@ -55,43 +55,41 @@ or `48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of
55- `noun`: an `atom` or a `cell`
55- `noun`: an `atom` or a `cell`
56- `atom`: any natural number
56- `atom`: any natural number
57- `cell`: any ordered pair of `noun`s
57- `cell`: any ordered pair of `noun`s
58−- `subject`: a `noun` - the argument against which a `formula` is evaluated
58+- `subject`: a `noun` - the data against which a `formula` is evaluated
59−- `formula`: a `noun` - any of the Hoon formula numbers (0-10), followed by *(TODO: ?)*
59+- `formula`: a `cell` - any of the Nock formula numbers (0-10) or a pair of formulas that resolves to a cell.
60- `product`: a `noun` - the result of evaluating a `formula` against a `subject`
60- `product`: a `noun` - the result of evaluating a `formula` against a `subject`
62−*See [Nock definition](../../nock/definition/)*
62+*See [Nock definition](/nock/definition/).*
66−> Hoon is a strict, higher-order typed functional language which compiles itself to Nock.
66+> Hoon is a strict, higher-order typed functional language that compiles itself to Nock.
68###### `span`: an inferred type
68###### `span`: an inferred type
70A `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`).
70A `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`).
72−*See [basic types](../../hoon/basic/#-type-span-and-mold)*
72+*See [basic types](/hoon/basic/#-type-span-and-mold).*
74###### `mold`: a type constructor / validator
74###### `mold`: a type constructor / validator
76A mold is an idempotent `gate` (function), accepting any `noun` and normalizing it to a range.
76A mold is an idempotent `gate` (function), accepting any `noun` and normalizing it to a range.
78+- `bunt`: the default value of a `mold`
78−- `icon`: the `span` of a `mold`
79+- `icon`: the `span` of a `bunt`
79−- `bunt`: *(TODO: ??)*
81−*See [`mold` `twig`s](../../hoon/twig/buc-mold/)*
81+*See [`mold` `twig`s](/hoon/twig/buc-mold/).*
83###### `gate`: a function, lambda or closure
83###### `gate`: a function, lambda or closure
85−*TODO: simplify description*
87−A `gate` is a specialized `core` with only one `arm` (whose name is the empty string (the symbol `$`). 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`.
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`.
89The `payload` of a `gate` has a shape of `{sample context}`.
87The `payload` of a `gate` has a shape of `{sample context}`.
91−- `sample`: the argument *(TODO: or plural?)* of a `gate`
89+- `sample`: the argument
92−- `context`: the subject in *(TODO: against?)* which a `gate` was defined
90+- `context`: the subject in which a `gate` was defined
94−+*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`)*
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`).*
96###### `core`: a code-data `cell`
94###### `core`: a code-data `cell`
@@ -104,92 +102,68 @@ The code (`battery`) is the head, the data (`payload`) is the tail. All code-dat
105- `wet`: polymorphic by means of *genericity*
103- `wet`: polymorphic by means of *genericity*
109−> When we call a `wet` `arm`, we're essentially using the `twig` as a macro. We are not generating new code for every call site; we are creating a new type analysis path, which works as if we expanded the callee with the caller's context.
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.
111- `dry`: polymorphic by means of *variance*
107- `dry`: polymorphic by means of *variance*
113For a `dry` `arm`, we ask, is the new `payload` compatible with the old `payload` (against which the `core` was compiled)?
109For a `dry` `arm`, we ask, is the new `payload` compatible with the old `payload` (against which the `core` was compiled)?
115−Every `dry` `core` has a `metal` *(TODO: check)* which defines its *variance* model (ie, the properties of the `span` of a compatible `core`).
111+Every `core` has a `metal` which defines its *variance* model (ie, the properties of the `span` of a compatible `core`).
117−*TODO: is the core dry, the arm dry, or both?*
119- `gold`: *invariant*
113- `gold`: *invariant*
120- `lead`: *bivariant*
114- `lead`: *bivariant*
121- `zync`: *covariant*
115- `zync`: *covariant*
122- `iron`: *contravariant*
116- `iron`: *contravariant*
124−*See [advanced types](../../hoon/advanced)*
118+*See [advanced types](/hoon/advanced)*.
126###### `arm`: a named, functionally-computed attribute of a `core`
120###### `arm`: a named, functionally-computed attribute of a `core`
128The `twig` of each `arm` is compiled to a Nock formula, with the enclosing `core` itself as the subject.
122The `twig` of each `arm` is compiled to a Nock formula, with the enclosing `core` itself as the subject.
130−*See [basic types](../../hoon/basic)*
124+*See [basic types](/hoon/basic)*.
132−###### `foot`: a `wet` or `dry` `twig`
126+###### `foot`: a `wet` or `dry` `arm`
134−*TODO: any `twig`, or always an `arm` within a `battery`?*
136###### `atom`
128###### `atom`
138−A Hoon `atom` is a Nock `atom`, with two additional pieces of metadata (TODO: ?): an `aura`, and a `unit`.
130+A Hoon `atom` is a Nock `atom`, with two additional pieces of metadata: an `aura`, and an optional constant.
140−- `unit`: a nullable pointer (TODO: ?), or a Maybe
142−`atom`s are said to be `warm` or `cold` based on their `unit`
132+`atom`s are `warm` or `cold` based on whether the constant exists.
144−- `warm`: if the `unit` is `~` (null), any `atom` is in the `span`
134+- `warm`: if the constant is `~` (null), any `atom` is in the `span`
145−- `cold`: if the `unit` is `[~ x]`, where `x` is any `atom`, its only legal value is the constant `x`. *(TODO: what does this actually mean? What is the consequence of illegality?)*
135+- `cold`: if the constant is `[~ atom]`, its only legal value is `atom`.
147*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
137*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
149###### `aura`: a soft `atom` type
139###### `aura`: a soft `atom` type
151−*alternately `odor`*
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).
153−*TODO: write a short summary*
155−*TODO: are `aura`s always `mold`s? just the built-in `aura`s?*
157−> Auras are a lightweight, advisory representation of the units, semantics, and/or syntax of an `atom`. An `aura` is an atomic string; two auras are compatible if one is a prefix of the other.
159−> For instance, @t means UTF-8 text (LSB low), @ta means ASCII text, and @tas means an ASCII symbol. @u means an unsigned integer, @ud an unsigned decimal, @ux an unsigned hexadecimal. You can use a @ud atom as a @u or vice versa, but not as a @tas.
161−> Auras are truly soft; you can turn any `aura` into any other, statically, by casting through the empty `aura` `@`. Hoon is not dependently typed and can't statically enforce data constraints (for example, it can't enforce that a `@tas` is really a symbol).
164−- `term` (`@tas`): a symbol - an atomic ASCII string which obeys symbol rules: lowercase and digit only, infix hyphen ("worm-case"), first character must be lowercase *(TODO: alphabetic?)*.
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.
166- `cord` (`@t`): UTF-8 text, least-significant-byte first
145- `cord` (`@t`): UTF-8 text, least-significant-byte first
168−- `char` (`@tD`): a character, a single unicode byte (for multi-byte characters and codepoints, see `@c`)
147+- `char` (`@td`): a character, a single unicode byte (for multi-byte characters and codepoints, see `@c`)
170−- `tape` (`(list char)`): a `tape` is not an `aura`, but a `mold` for a collection where every item has an `aura` of `char` *(TODO: is this for easy indexing vs `@t`?)*
149+- `tape` (`(list char)`): a `tape` is not an `aura`, but a `mold` for a list where every item has an `aura` of `char`.
172−*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
151+*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
174###### `loobean`: a Hoon boolean
153###### `loobean`: a Hoon boolean
176`0` (`%.y`) is *true*, `1` (`%.n`) is *false*.
155`0` (`%.y`) is *true*, `1` (`%.n`) is *false*.
178−>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.
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.
180###### `twig`: a Hoon expression
159###### `twig`: a Hoon expression
182−A `twig` is the name for any Hoon expression, and for the AST node representing the expression as compiled to a Nock formula *(TODO: seems to be used interchangeably in the docs)*. It is a `book` with the form `{stem bulb}`.
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}`.
184- `book`: a tagged-union
163- `book`: a tagged-union
185- `page`: an item in a `book`
164- `page`: an item in a `book`
186−- `stem`: an atomic symbol (`@tas`) - uniquely identifies a `twig` *(TODO: ?)*
165+- `stem`: an atomic symbol (`@tas`) - the name of a `twig`
187−- `bulb`: The `bulb` for each `stem` has its own type, usually a tuple, sometimes a list or a map.
166+- `bulb`: The `mold` of the `twig`'s arguments.
189−A `twig` is either a `moss` ("mossy") or a `seed` ("woody"):
191−- `moss`: a `twig` whose `product` is used as a `mold`
192−- `seed`: a `twig` whose `product` could be anything
194The 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*.
168The 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*.
@@ -199,9 +173,9 @@ Hoon does not have reserved words, but `sigil`s (prefixed with `:`), which are e
200- `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.
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.
202−*regular forms* can alternate between *tall* and *wide* (or *flat*) syntax, *irregular formas* can use only the *wide*/*flat* syntax.
176+*regular forms* can alternate between *tall* and *wide* (or *flat*) syntax, *irregular forms* can use only the *wide*/*flat* syntax.
204−*See [`twig` concept](../../hoon/concepts/#-twig-expression), [expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*
178+*See [`twig` concept](../../hoon/concepts/#-twig-expression), [expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.
206###### `limb`: attribute or variable reference
180###### `limb`: attribute or variable reference
@@ -216,27 +190,10 @@ To resolve a `limb` named "foo", the `subject` is searched depth-first, head-fir
217Hoon has no scope or symbol-table; there is only the `subject`. To "declare" a "variable" is to construct a new `subject`: `[variable old-subject]`.
191Hoon has no scope or symbol-table; there is only the `subject`. To "declare" a "variable" is to construct a new `subject`: `[variable old-subject]`.
219−A `face` is a `span` *(TODO: ?)* with a label (`@tas`) wrapped around it.
193+A `face` wraps a name (`@tas`) around a `span`.
221−- `taco`: a `symbol` (for a *type-inferred* `face`), or a `symbol` *with* a `mold` (for a *type-checked* `face`)
225−- `tune`: advanced `face`s:
226− - `alias`: a `face` that is a lazy reference to another `face`
227− - `bridge`: a `face` that references a `twig`, against which the `face` label is resolved
229−*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*
195+*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
231###### `nest`: a type-casting operation
197###### `nest`: a type-casting operation
233−*TODO:*
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/).
237−> Arvo is a nonpreemptive OS kernel, a single-threaded event interpreter.