@@ -10,25 +10,19 @@ title: Concepts
10Usually, a new language is an improvement on one you already
10Usually, a new language is an improvement on one you already
11know. If it isn't, it probably at least shares concepts with a
11know. If it isn't, it probably at least shares concepts with a
12large family of relatives. These concepts come with words, like
12large 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.
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
16ones, which mean almost the same things. But why?
16ones, which mean almost the same things. But why?
18## Motivation
18## Motivation
20Hoon has no close relatives. The normal jargon of programming
20Hoon has no close relatives. The normal jargon of programming
21−maps poorly onto its semantics. For example, although Hoon is a
21+maps poorly onto its semantics. Some of the common concepts used
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.
27−Other common programming concepts used only informally in Hoon
28−are "function," "object," "event," "expression," "variable,"
22+only informally in Hoon include "function," "object," "event,"
29−"label," "closure", "environment," "scope," and probably a few
23+"variable," "label," "closure", "environment," "scope," and probably
30−more. We do use these words informally, but we're always making
24+a few more. We do use these words informally, but we're always
31−an analogy whose precision depends on context.
25+making an analogy whose precision depends on context.
33Hoon has concepts *like* all these abstractions, but they remain
27Hoon has concepts *like* all these abstractions, but they remain
34*false cognates*. The closer an inexact cognate, the more
28*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.
38## Concepts
32## Concepts
40A few major Hoon concepts: `noun` (data), `nock` (interpreter),
34A 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),
42`gate` (function), `mold` (constructor), `core` (object), `mark`
36`gate` (function), `mold` (constructor), `core` (object), `mark`
43(protocol).
37(protocol).
@@ -53,20 +47,21 @@ The simplest noun syntax uses brackets, like `[a b]` for the cell
53of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c
47of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c
54d]]]`. You'll also see braces: `{a b c d}`.
48d]]]`. You'll also see braces: `{a b c d}`.
56−A noun list, by convention, points right and is zero-terminated.
50+A noun list, by convention, goes from left to right and is
57−Hoon uses tuples (improper nouns) more freely than Lisp; only
51+null-terminated. That said, Hoon uses tuples (improper nouns) more
58−genuinely iterative structures are null-terminated lists.
52+freely than Lisp; only genuinely iterative structures are
53+null-terminated lists.
60When an atom is used as a string (a `cord`), the bytes are always
55When 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`,
62etc, this refers to the integer `0x6f.6f66`, aka `7.303.014`.
57etc, 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.)
65One common operation on nouns is `slot`, a tree addressing
60One common operation on nouns is `slot`, a tree addressing
66scheme which maps an atom to a subtree. The whole noun is slot
61scheme which maps an atom to a subtree. The whole noun is slot
67`1`; the left child of `n` is `2n`, the right child `2n+1`.
62`1`; the left child of `n` is `2n`, the right child `2n+1`.
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
70detect pointer equivalence. Nouns are generally implemented
65detect pointer equivalence. Nouns are generally implemented
71with reference counting, and have a lazy short Merkle hash to
66with reference counting, and have a lazy short Merkle hash to
72help with equality testing and associative containers.
67help with equality testing and associative containers.
@@ -82,16 +77,54 @@ it's still fun and useful to [learn more](../../nock).
83## Compilation concepts
78## Compilation concepts
80+### <a name="hoon">`hoon`</a> (AST node)
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`.
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:
97+The %clhp is for "colhep".
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:
103+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
106+To parse Hoon source into a hoon AST, use `ream` on a `cord`, e.g.:
112+Try it in the `:dojo` to get:
115+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
85### <a name="mint">`mint`</a> (compiler)
118### <a name="mint">`mint`</a> (compiler)
87−[`mint`](#mint) is the Hoon compiler. It maps a cell `{span twig}` to a
120+[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]` to a
88−cell `{span nock}`, where a [`span`](#span) is a type, a [`twig`](#twig)
121+cell `[type nock]`, where a [`type`](#type) is a type, a [`hoon`](#hoon)
89−is a compiled expression (AST), and a `nock` is a Nock formula. `mint` accepts
122+is a parsed expression (AST), and a `nock` is a Nock formula. `mint` accepts
90−a subject type and a source expression; it produces a product type
123+a subject type and a parsed source expression; it produces a product type
91and an executable formula.
124and an executable formula.
93Calculating the output type from the input type and the source
126Calculating 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
95functional language, like Haskell, Hoon's type inference does the
128functional language, like Haskell, Hoon's type inference does the
96same job but with less intelligence.
129same job but with less intelligence.
@@ -105,52 +138,21 @@ which makes your program more readable anyway. Also, the dumber
105the compiler, the easier it is for a dumb human to understand
138the compiler, the easier it is for a dumb human to understand
106what the compiler is thinking.
139what the compiler is thinking.
108−### <a name="twig">`twig`</a> (expression)
141+To compile the hoon from the last subsection into Nock, try the
109−
142+following in `:dojo`:
110−A [`twig`](../reference) is a Hoon AST node, the result of parsing a
111−source expression. A Hoon source file encodes one twig.
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).
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.
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
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.
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.
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
144−or the tall rune syntax (here on one line, with double spaces):
145+(mint:ut %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])
148+The `%noun` is type information, and the tagged union after that
149−### <a name="span">`span`</a> (type, as range)
151+### <a name="type">`type`</a> (type, as range)
151−A `span` is a Hoon type. It defines a set (finite or
153+A `type` defines a set (finite or infinite) of nouns and ascribes
152−infinite) of nouns and ascribes some semantics to it. There is
154+some semantics to it. There is no direct syntax for defining
153−no syntax for spans; they are always defined by inference (ie, by
155+types; they are always defined by inference (ie, by
154[`mint`](#mint)), usually using a constructor (`mold`).
156[`mint`](#mint)), usually using a constructor (`mold`).
156### `gate` (function)
158### `gate` (function)
@@ -179,9 +181,9 @@ A `mold` is a constructor function (`gate`). Its sample is any
179noun; its product is a structured noun. A mold is idempotent;
181noun; its product is a structured noun. A mold is idempotent;
180`(mold (mold x))` always equals `(mold x)`.
182`(mold (mold x))` always equals `(mold x)`.
182−Since there's no such thing as a [`span`](#span) declaration, we use molds
184+Because there's no such thing as a [`type`](#type) declaration,
183−to define useful spans by example; we also use them to validate
185+we use molds to define useful types by example; we also use them
184−untrusted network input.
186+to validate untrusted network input.
186### `face` (named variable)
188### `face` (named variable)
@@ -189,21 +191,22 @@ In a conventional language, we have a scope, environment or
189symbol table. Declaring a variable, like `var foo: atom`, adds
191symbol table. Declaring a variable, like `var foo: atom`, adds
190the name `foo` to the table with type `atom`.
192the name `foo` to the table with type `atom`.
192−The Hoon equivalent is `:var foo atom`. But Hoon has a
194+The Hoon analogue is `=|(foo atom)`. But Hoon has a
193homoiconic heap; there is no inscrutable scope or environment.
195homoiconic heap; there is no inscrutable scope or environment.
194There is just the subject, which is one noun. To "declare a
196There is just the subject, which is one noun. To "declare a
195−variable" is to make a cell `[variable old-subject]`, and use it
197+variable" is to make a cell `[variable old-subject]`, and use that
196−as the subject of the [`twig`](#twig) below.
198+as the subject of the next expression.
198−So the labe[`twig`](#twig)l `foo` isn't a key in a symbol table; it's in the
200+The label `foo` isn't a key in a symbol table; it's stored as a kind
199−type ([`span`](#span)) of the new value. It's not a variable named `foo`,
201+of metadata, in the type ([`type`](#type)) of the new value. It's not
200−whose value is of type `atom`; it's a subtree of type `foo:atom`.
202+a variable named `foo`, whose value is of type `atom`; it's a subtree
202### <a name="limb">`limb`</a> (attribute or variable reference)
205### <a name="limb">`limb`</a> (attribute or variable reference)
204A [`limb`](../twig/limb/limb), like `foo`, is Hoon's equivalent of a variable
207A [`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),
208+reference. A limb is a [`hoon`](#hoon); given a subject [`type`](#type),
206−[`mint`](#mint) resolves it to a Nock formula and a product [`span`](#span).
209+[`mint`](#mint) resolves it to a Nock formula and a product [`type`](#type).
208To resolve limb `foo`, [`mint`](#mint) searches the subject depth-first,
211To resolve limb `foo`, [`mint`](#mint) searches the subject depth-first,
209head-first for either a `face` named `foo`, or a `core` with the
212head-first for either a `face` named `foo`, or a `core` with the
@@ -213,6 +216,9 @@ formula with that core as the subject.
214A limb can also be a slot (direct tree address), like `+15`.
217A limb can also be a slot (direct tree address), like `+15`.
219+`boo:[foo=12 baz=23 boo=34]` evaluates to `34`.
220+`+6:[foo=12 baz=23 boo=34]` evaluates to `baz=23`.
216### `wing` ([`limb`](#limb) path)
222### `wing` ([`limb`](#limb) path)
218A [wing](../twig/limb/wing) is a list of limbs. Like attribute references in a
224A [wing](../twig/limb/wing) is a list of limbs. Like attribute references in a