@@ -80,39 +80,35 @@ it's still fun and useful to [learn more](../../nock).
80### <a name="hoon">`hoon`</a> (AST node)
80### <a name="hoon">`hoon`</a> (AST node)
82A [`hoon`](../reference) is the result of parsing a Hoon source
82A [`hoon`](../reference) is the result of parsing a Hoon source
83+expression into an AST node. These AST nodes are nouns, like all
83−expression into an AST node. Because every Hoon program is,
84+other Hoon data. Because every Hoon program is, in its entirety, a
84−in its entirety, a single expression of Hoon, the result of parsing
85+single expression of Hoon, the result of parsing the whole thing
85−a whole Hoon program into an AST is a single `hoon`.
86+into an AST is a single `hoon`.
87−As the noun that the parser produces, a hoon is a tagged union of
88−the form `[tag data]`, where the tag is a constant such as `%brts`,
88+A hoon is a tagged union of the form `[%tag data]`, where the tag
89+is a constant such as `%brts` (from the source `|=`, i.e. "bartis"),
89−which is matched up with the appropriate type of data (often more
90+and is matched up with the appropriate type of data (often more
90−`hoon`s). For example, the expression `:-(p q)`, once parsed into
91+`hoon`s, from source subexpressions). For example, the expression
91−an AST, becomes the tagged union:
92+`:-(2 17)`, once parsed into an AST, becomes the following:
97−The `%clhp` is for "colhep". Keep in mind that `p` and `q` would be
98−parsed too. So if `p` is 2 and `q` is 17, the parsed result is:
101[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
95[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
98+The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and
104−The 2 and 17 have each been parsed as `%sand`-tagged `hoon`s, which
99+17 have each been parsed as `%sand`-tagged hoons, which represent
100+atoms (in this case each with an aura of `%ud`, i.e. unsigned
105−represent constant atoms. To parse Hoon source into a hoon AST, use
101+decimal). To parse Hoon source into a hoon AST, use `ream` on a `cord`
106−`ream` on a `cord`, e.g.:
102+containing Hoon source, e.g.:
109−(ream ':-(2 17)')
105+(ream ':+(12 7 %a)')
112−Try it in the `:dojo` to get:
108+Try the above in the `:dojo` to get:
115−[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
111+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
118### <a name="mint">`mint`</a> (compiler)
114### <a name="mint">`mint`</a> (compiler)
@@ -120,14 +116,19 @@ Try it in the `:dojo` to get:
120[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]`
116[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]`
121to a cell `[type nock]`, where a [`type`](#type) is type
117to a cell `[type nock]`, where a [`type`](#type) is type
122information, a [`hoon`](#hoon) is a parsed expression (AST), and a
118information, a [`hoon`](#hoon) is a parsed expression (AST), and a
123−`nock` is a Nock formula. `mint` accepts a subject type and a parsed
119+`nock` is a Nock formula. `mint` accepts a type and a parsed
124source expression; it produces a product type and an executable
120source expression; it produces a product type and an executable
123+As part of the type-checking process, mint checks that the output
124+type "nests" within the input type, i.e. that the output type is a
125+subset of the input type. If not, mint halts with a `nest-fail`
127−Calculating the output type from the input type and the source
128+Calculating the output type from the input `hoon` is called "type
128−code is called "type inference". If you've used another typed
129+inference". If you've used another typed functional language, like
129−functional language, like Haskell, Hoon's type inference does the
130+Haskell, Hoon's type inference does the same job but with less
130−same job but with less intelligence.
131+intelligence.
132Haskell infers backward and forward; Hoon only infers forward.
133Haskell infers backward and forward; Hoon only infers forward.
133Hoon can't figure out the type of a noun from how you use it,
134Hoon can't figure out the type of a noun from how you use it,
@@ -139,15 +140,15 @@ which makes your program more readable anyway. Also, the dumber
139the compiler, the easier it is for a dumb human to understand
140the compiler, the easier it is for a dumb human to understand
140what the compiler is thinking.
141what the compiler is thinking.
142−To compile the hoon from the last subsection into Nock, try the
143+To compile an example `hoon` from the last subsection into Nock,
143−following in `:dojo`:
144+try the following in `:dojo`:
146(mint:ut %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])
147(mint:ut %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])
149−The `%noun` is for the data type of the subject, and the tagged
150+The `%noun` is the input `type` for `mint`, and the tree after that
150−union after that is the hoon.
151+is the input `hoon`.
152### <a name="type">`type`</a> (type, as range)
153### <a name="type">`type`</a> (type, as range)
@@ -158,7 +159,7 @@ types; they are always defined by inference (i.e., by
159All types are assembled out of base types defined in `++type`.
160All types are assembled out of base types defined in `++type`.
160(Look up `++ type` in hoon.hoon for examples.) When the compiler
161(Look up `++ type` in hoon.hoon for examples.) When the compiler
161−does type-inference on a prorgam, it assembles complex types out
162+does type-inference on a program, it assembles complex types out
162of the simpler built-in types.
163of the simpler built-in types.
164### `gate` (function)
165### `gate` (function)
@@ -181,7 +182,7 @@ A gate is a special case of a core: a core with one arm, whose
181name is the empty string. The shape of a core is `[battery
182name is the empty string. The shape of a core is `[battery
182payload]`, where *battery* is a tree of Nock formulas
183payload]`, where *battery* is a tree of Nock formulas
184−### `mold` (type, as constructor)
185+### `mold` (constructor)
186A `mold` is a constructor function (`gate`). Its sample is any
187A `mold` is a constructor function (`gate`). Its sample is any
187noun; its product is a structured noun. A mold is idempotent;
188noun; its product is a structured noun. A mold is idempotent;
@@ -194,14 +195,15 @@ to validate untrusted network input.
194### `face` (named variable)
195### `face` (named variable)
196In a conventional language, we have a scope, environment or
197In a conventional language, we have a scope, environment or
197−symbol table. Declaring a variable, like `var foo: atom`, adds
198+symbol table. Declaring a variable, like e.g. `int foo = 3`,
198−the name `foo` to the table with type `atom`.
199+adds the name `foo` to the table with type `int`.
200−The Hoon analogue is `=|(foo atom)`. But Hoon has a
201+The Hoon analogue is `=/(foo atom 3 ...)`, where `foo` is a `face`
202+and `atom` is the type. But Hoon has a homoiconic heap; there is no
201−homoiconic heap; there is no inscrutable scope or environment.
203+inscrutable scope or environment. There is just the subject, which
202−There is just the subject, which is one noun. To "declare a
204+is one noun. To "declare a variable" is to make a cell
203−variable" is to make a cell `[variable old-subject]`, and use that
205+`[variable old-subject]`, and use thatas the subject of the next
204−as the subject of the next expression.
206+expression.
206The label `foo` isn't a key in a symbol table; it's stored as a kind
208The label `foo` isn't a key in a symbol table; it's stored as a kind
207of metadata, in the type ([`type`](#type)) of the new value. It's not
209of metadata, in the type ([`type`](#type)) of the new value. It's not