@@ -4,33 +4,50 @@ weight = 8
4template = "doc.html"
4template = "doc.html"
7−A core is a cell of `[battery payload]`. The battery is made of one or more arms, each of which is a computation on its parent core.
7+A core is a cell of `[battery payload]`. The battery is made of one or more
8+arms, each of which is a computation on its parent core.
10+Arm runes are used to define arms in a core, and thus can only be used from
9−Arm runes are used to define arms in a core, and thus can only be used from within an expression that produces a multi-arm core. That means arm runes cannot be used to mark the beginning of a first-class expression -- there is no such thing in Hoon as an arm without a core.
11+within an expression that produces a multi-arm core. That means arm runes cannot
12+be used to mark the beginning of a first-class expression -- there is no such
13+thing in Hoon as an arm without a core.
11−There are various arm runes you can use to produce different kinds of arms. Normal arms use `++`; arms defining a structure (or 'mold') use `+$`; and constructor arms use `+*`.
15+There are various arm runes you can use to produce different kinds of arms.
16+Normal arms use `++`; arms defining a structure (or 'mold') use `+$`; and
17+constructor arms use `+*`.
15−### `+|` "lusbar"
19+## `+|` "lusbar"
17Chapter label.
21Chapter label.
19−##### Syntax
23+#### Syntax
21−Regular: **1-fixed**.
27+Tall form:
27−##### Discussion
33+Wide form:
43+The `+|` doesn't produce an arm. It instead provides a label for the arms that
44+follow it. The arms of a core can be divided into **chapters** for
29−The `+|` doesn't produce an arm. It instead provides a label for the arms that follow it. The arms of a core can be divided into **chapters** for 'organization'. Chapter labels aren't part of the underlying noun of the core; they're stored as type system metadata only.
45+'organization'. Chapter labels aren't part of the underlying noun of the core;
46+they're stored as type system metadata only.
31See `tome` in the Hoon standard library.
48See `tome` in the Hoon standard library.
33−##### Examples
50+#### Examples
35Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
52Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
@@ -46,7 +63,7 @@ Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
49−Notice that `p.q` has the label `%numbers`. Contrast with:
66+Notice that `p.q` has the label `%numbers`. Contrast with:
52> (ream '|% ++ two 2 ++ three 3 --')
69> (ream '|% ++ two 2 ++ three 3 --')
@@ -60,27 +77,42 @@ Notice that `p.q` has the label `%numbers`. Contrast with:
63−### `+$` "lusbuc"
82+## `+$` "lusbuc"
65Produce a structure arm (type definition).
84Produce a structure arm (type definition).
67−##### Syntax
86+#### Syntax
69−Regular: **2-fixed**.
88+Two arguments, fixed.
72+$ p=term q=spec
93+$ p=term q=spec
75`p` is an arm name, and `q` is any structure expression.
104`p` is an arm name, and `q` is any structure expression.
77−##### Discussion
106+#### Discussion
79−Arms produced by `+$` are essentially type definitions. They should be used when one wants to define custom types using core arms.
108+Arms produced by `+$` are essentially type definitions. They should be used when one wants to define custom types using core arms.
81−The Hoon subexpression, `q`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants). Names of structures are also permitted (e.g., `tape`).
110+The Hoon subexpression, `q`, must be a structure expression. That is, it must be
111+either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex
112+expression made with the `$` family of runes (including irregular variants).
113+Names of structures are also permitted (e.g., `tape`).
83−##### Examples
115+#### Examples
@@ -98,27 +130,41 @@ nest-fail
101−### `++` "luslus"
135+## `++` "luslus"
103Produce a normal arm.
137Produce a normal arm.
105−##### Syntax
139+#### Syntax
107−Regular: **2-fixed**.
141+Two arguments, fixed.
110++ p=term q=hoon
146++ p=term q=hoon
113`p` is the arm name, and `q` is any Hoon expression.
157`p` is the arm name, and `q` is any Hoon expression.
115−##### Discussion
159+#### Discussion
117−All arms must have a name (e.g., `add`). An arm is computed by name resolution. (This resolution is implicit in the case of `$` arms. See `|=`, `|-`, and `|^`.) The `++` rune is used for explicitly giving a name to an arm.
161+All arms must have a name (e.g., `add`). An arm is computed by name resolution.
162+(This resolution is implicit in the case of `$` arms. See `|=`, `|-`, and `|^`.)
163+The `++` rune is used for explicitly giving a name to an arm.
119Any Hoon expression, `q`, may be used to define the arm computation.
165Any Hoon expression, `q`, may be used to define the arm computation.
121−##### Examples
167+#### Examples
@@ -133,13 +179,17 @@ Any Hoon expression, `q`, may be used to define the arm computation.
136−### `+*` "lustar"
184+## `+*` "lustar"
138Defines deferred expressions within doors.
186Defines deferred expressions within doors.
140−##### Syntax
188+#### Syntax
142−Regular: **variadic**.
190+Arguments: A variable number of pairs.
145+* a=term b=hoon
195+* a=term b=hoon
@@ -155,7 +205,7 @@ arguments of `+*` does not end with a terminator.
155`+*` arms must always come at the beginning of the battery, before any other
205`+*` arms must always come at the beginning of the battery, before any other
156type of lus arm.
206type of lus arm.
158−##### Discussion
208+#### Discussion
160The primary use of `+*` is to create deferred expressions within doors (see
210The primary use of `+*` is to create deferred expressions within doors (see
161Examples below). This is a name for an expressions that will be evaluated in
211Examples below). This is a name for an expressions that will be evaluated in
@@ -178,7 +228,9 @@ compiled from this Hoon expression
178++ y (sub z n)
228++ y (sub z n)
181as being identical the Nock compiled from this one:
232as being identical the Nock compiled from this one:
@@ -191,13 +243,15 @@ as being identical the Nock compiled from this one:
194−##### Examples
246+#### Examples
196To assign an alias to a door, we often write the following.
248To assign an alias to a door, we often write the following.
201This is the idomatic way to assign the alias `this` to the door.
255This is the idomatic way to assign the alias `this` to the door.
203Sometimes cores, such as Gall app cores, have a fixed number of arms, but you'd
257Sometimes cores, such as Gall app cores, have a fixed number of arms, but you'd
@@ -211,6 +265,7 @@ Gall app core. This usage of `+*` is controversial and should be minimized.
214This assigns the door the alias `this`, the sample of the door `samp`, and the
269This assigns the door the alias `this`, the sample of the door `samp`, and the
215context of the door `cont`.
270context of the door `cont`.
@@ -218,7 +273,7 @@ You may also call functions with `+*` by making use of e.g. the `%~` rune.
222 +* do ~(. +> a)
277 +* do ~(. +> a)
223 ++ stuff foo:do
278 ++ stuff foo:do