@@ -10,25 +10,19 @@ title: Concepts
1010Usually, a new language is an improvement on one you already
1111know. If it isn't, it probably at least shares concepts with a
1212large family of relatives. These concepts come with words, like
13−*type* or *function*, that map cleanly onto its semantics.
13+*variable* or *function*, that map cleanly onto its semantics.
1414
15−In Hoon we throw away almost all these words and invent new
15+In Hoon we throw away many of these words and invent new
1616ones, which mean almost the same things. But why?
1717
1818## Motivation
1919
2020Hoon has no close relatives. The normal jargon of programming
21−maps poorly onto its semantics. For example, although Hoon is a
22−typed language, the term "type" is not formally defined in Hoon.
23−"Type" is a great word, but Hoon has three separate concepts
24−which could comfortably claim it. We say "type" all the time; we
25−mean [`span`](#span), or `mold`, or `mark`, or possibly all three.
26−
27−Other common programming concepts used only informally in Hoon
28−are "function," "object," "event," "expression," "variable,"
29−"label," "closure", "environment," "scope," and probably a few
30−more. We do use these words informally, but we're always making
31−an analogy whose precision depends on context.
21+maps poorly onto its semantics. Some of the common concepts used
22+only informally in Hoon include "function," "object," "event,"
23+"variable," "label," "closure", "environment," "scope," and probably
24+a few more. We do use these words informally, but we're always
25+making an analogy whose precision depends on context.
3226
3327Hoon has concepts *like* all these abstractions, but they remain
3428*false cognates*. The closer an inexact cognate, the more
@@ -38,7 +32,7 @@ a few new words is a small price for avoiding this pain point.
3832## Concepts
3933
4034A few major Hoon concepts: `noun` (data), `nock` (interpreter),
41−[`mint`](#mint) (compiler), [`span`](#span) (type), [`twig`](#twig) (expression),
35+[`mint`](#mint) (compiler), [`hoon`](#hoon) (AST node),
4236`gate` (function), `mold` (constructor), `core` (object), `mark`
4337(protocol).
4438
@@ -53,20 +47,21 @@ The simplest noun syntax uses brackets, like `[a b]` for the cell
5347of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c
5448d]]]`. You'll also see braces: `{a b c d}`.
5549
56−A noun list, by convention, points right and is zero-terminated.
57−Hoon uses tuples (improper nouns) more freely than Lisp; only
58−genuinely iterative structures are null-terminated lists.
50+A noun list, by convention, goes from left to right and is
51+null-terminated. That said, Hoon uses tuples (improper nouns) more
52+freely than Lisp; only genuinely iterative structures are
53+null-terminated lists.
5954
6055When an atom is used as a string (a `cord`), the bytes are always
61−UTF-8 in LSB first order. When you see `foo`, `$foo`, `%foo`,
56+UTF-8 in LSB-first order. When you see `foo`, `$foo`, `%foo`,
6257etc, this refers to the integer `0x6f.6f66`, aka `7.303.014`.
63−(Hoon syntax breaks integer atoms in the German style.)
58+(Hoon syntax uses `.` to break integer atoms in the German style.)
6459
6560One common operation on nouns is `slot`, a tree addressing
6661scheme which maps an atom to a subtree. The whole noun is slot
6762`1`; the left child of `n` is `2n`, the right child `2n+1`.
6863
69−Nothing in Nock, Hoon or Urbit can create cycles in a noun or
64+Nothing in Nock, Hoon, or Urbit can create cycles in a noun or
7065detect pointer equivalence. Nouns are generally implemented
7166with reference counting, and have a lazy short Merkle hash to
7267help with equality testing and associative containers.
@@ -82,16 +77,54 @@ it's still fun and useful to [learn more](../../nock).
8277
8378## Compilation concepts
8479
80+### <a name="hoon">`hoon`</a> (AST node)
81+
82+A [`hoon`](../reference) is the result of parsing a Hoon source
83+expression into an AST node. Because every Hoon programs is,
84+in its entirety, a single expression of Hoon, the result of parsing
85+a whole Hoon program into an AST is a single `hoon`.
86+
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`
89+which matches up with the appropriate type of data (often more
90+`hoon`s). For example, the expression `:-(p q)`, once parsed into
91+an AST, becomes the tagged union:
92+
93+```
94+[%clhp p=hoon q=hoon]
95+```
96+
97+The %clhp is for "colhep".
98+
99+Keep in mind that `p` and `q` would be parsed too. So if `p` is `2`
100+and `q` is 17, the parsed result is:
101+
102+```
103+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
104+```
105+
106+To parse Hoon source into a hoon AST, use `ream` on a `cord`, e.g.:
107+
108+```
109+(ream ':-(2 17)')
110+```
111+
112+Try it in the `:dojo` to get:
113+
114+```
115+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
116+```
117+
85118### <a name="mint">`mint`</a> (compiler)
86119
87−[`mint`](#mint) is the Hoon compiler. It maps a cell `{span twig}` to a
88−cell `{span nock}`, where a [`span`](#span) is a type, a [`twig`](#twig)
89−is a compiled expression (AST), and a `nock` is a Nock formula. `mint` accepts
90−a subject type and a source expression; it produces a product type
120+[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]` to a
121+cell `[type nock]`, where a [`type`](#type) is a type, a [`hoon`](#hoon)
122+is a parsed expression (AST), and a `nock` is a Nock formula. `mint` accepts
123+a subject type and a parsed source expression; it produces a product type
91124and an executable formula.
92125
93126Calculating the output type from the input type and the source
94−code is called "type inference." If you've used another typed
127+code is called "type inference". If you've used another typed
95128functional language, like Haskell, Hoon's type inference does the
96129same job but with less intelligence.
97130
@@ -105,52 +138,21 @@ which makes your program more readable anyway. Also, the dumber
105138the compiler, the easier it is for a dumb human to understand
106139what the compiler is thinking.
107140
108−### <a name="twig">`twig`</a> (expression)
109−
110−A [`twig`](../reference) is a Hoon AST node, the result of parsing a
111−source expression. A Hoon source file encodes one twig.
112−
113−As the noun that the parser produces, a twig is a tagged union of
114−the form `{stem bulb}`, where `stem` (the tag) is a `cord` which
115−controls the type of `bulb` (the data).
116−
117−As text, each twig has both regular and irregular syntax forms.
118−Regular syntax can be either *tall* or *flat*: multiline or
119−single-line. Irregular syntax is always flat. Tall twigs can
120−contain flat twigs, but not vice versa.
121−
122−Regular forms always start with a *sigil*, which is either a
123−*keyword* or a *rune* at the programmer's choice. A keyword is
124−the stem cord.
141+To compile the hoon from the last subsection into Nock, try the
142+following in `:dojo`:
125143
126−For most stems, tall regular form has no delimiter or terminator,
127−eliminating the `)))))` problem common in functional languages.
128−Hoon also uses an unusual "backstep" indentation pattern to
129−control left-margin drift.
130−
131−Hoon is mildly whitespace-sensitive. It knows the difference
132−between no whitespace, one-space, and more-space. But all cases
133−of more-space mean the same thing. Flat syntax uses one-space,
134−tall syntax more-space.
135−
136−As an example, the regular flat keyword syntax `:call(a b)` means
137−the same thing as the flat rune syntax `%-(a b)`, the tall
138−keyword syntax
139−
140−```
141−:call a
142−b
143144```
144−or the tall rune syntax (here on one line, with double spaces):
145−```
146−%- a b
145+(mint:ut %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])
147146```
148147
149−### <a name="span">`span`</a> (type, as range)
148+The `%noun` is type information, and the tagged union after that
149+is the hoon.
150+
151+### <a name="type">`type`</a> (type, as range)
150152
151−A `span` is a Hoon type. It defines a set (finite or
152−infinite) of nouns and ascribes some semantics to it. There is
153−no syntax for spans; they are always defined by inference (ie, by
153+A `type` defines a set (finite or infinite) of nouns and ascribes
154+some semantics to it. There is no direct syntax for defining
155+types; they are always defined by inference (ie, by
154156[`mint`](#mint)), usually using a constructor (`mold`).
155157
156158### `gate` (function)
@@ -179,9 +181,9 @@ A `mold` is a constructor function (`gate`). Its sample is any
179181noun; its product is a structured noun. A mold is idempotent;
180182`(mold (mold x))` always equals `(mold x)`.
181183
182−Since there's no such thing as a [`span`](#span) declaration, we use molds
183−to define useful spans by example; we also use them to validate
184−untrusted network input.
184+Because there's no such thing as a [`type`](#type) declaration,
185+we use molds to define useful types by example; we also use them
186+to validate untrusted network input.
185187
186188### `face` (named variable)
187189
@@ -189,21 +191,22 @@ In a conventional language, we have a scope, environment or
189191symbol table. Declaring a variable, like `var foo: atom`, adds
190192the name `foo` to the table with type `atom`.
191193
192−The Hoon equivalent is `:var foo atom`. But Hoon has a
194+The Hoon analogue is `=|(foo atom)`. But Hoon has a
193195homoiconic heap; there is no inscrutable scope or environment.
194196There is just the subject, which is one noun. To "declare a
195−variable" is to make a cell `[variable old-subject]`, and use it
196−as the subject of the [`twig`](#twig) below.
197+variable" is to make a cell `[variable old-subject]`, and use that
198+as the subject of the next expression.
197199
198−So the labe[`twig`](#twig)l `foo` isn't a key in a symbol table; it's in the
199−type ([`span`](#span)) of the new value. It's not a variable named `foo`,
200−whose value is of type `atom`; it's a subtree of type `foo:atom`.
200+The label `foo` isn't a key in a symbol table; it's stored as a kind
201+of metadata, in the type ([`type`](#type)) of the new value. It's not
202+a variable named `foo`, whose value is of type `atom`; it's a subtree
203+of type `foo:atom`.
201204
202205### <a name="limb">`limb`</a> (attribute or variable reference)
203206
204207A [`limb`](../twig/limb/limb), like `foo`, is Hoon's equivalent of a variable
205−reference. A limb is a [`twig`](#twig); given a subject [`span`](#span),
206−[`mint`](#mint) resolves it to a Nock formula and a product [`span`](#span).
208+reference. A limb is a [`hoon`](#hoon); given a subject [`type`](#type),
209+[`mint`](#mint) resolves it to a Nock formula and a product [`type`](#type).
207210
208211To resolve limb `foo`, [`mint`](#mint) searches the subject depth-first,
209212head-first for either a `face` named `foo`, or a `core` with the
@@ -213,6 +216,9 @@ formula with that core as the subject.
213216
214217A limb can also be a slot (direct tree address), like `+15`.
215218
219+`boo:[foo=12 baz=23 boo=34]` evaluates to `34`.
220+`+6:[foo=12 baz=23 boo=34]` evaluates to `baz=23`.
221+
216222### `wing` ([`limb`](#limb) path)
217223
218224A [wing](../twig/limb/wing) is a list of limbs. Like attribute references in a