@@ -4,33 +4,50 @@ weight = 8
44template = "doc.html"
55+++
66
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.
89
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.
10+Arm runes are used to define arms in a core, and thus can only be used from
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.
1014
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 `+*`.
1218
13−## Runes
14−
15−### `+|` "lusbar"
19+## `+|` "lusbar"
1620
1721Chapter label.
1822
19−##### Syntax
23+#### Syntax
24+
25+One argument, fixed.
2026
21−Regular: **1-fixed**.
27+Tall form:
2228
2329```hoon
2430+| %label
2531```
2632
27−##### Discussion
33+Wide form:
34+
35+None.
36+
37+Irregular form:
2838
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.
39+None.
40+
41+#### Discussion
42+
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
45+'organization'. Chapter labels aren't part of the underlying noun of the core;
46+they're stored as type system metadata only.
3047
3148See `tome` in the Hoon standard library.
3249
33−##### Examples
50+#### Examples
3451
3552Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
3653
@@ -46,7 +63,7 @@ Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
4663]
4764```
4865
49−Notice that `p.q` has the label `%numbers`. Contrast with:
66+Notice that `p.q` has the label `%numbers`. Contrast with:
5067
5168```
5269> (ream '|% ++ two 2 ++ three 3 --')
@@ -60,27 +77,42 @@ Notice that `p.q` has the label `%numbers`. Contrast with:
6077]
6178```
6279
63−### `+$` "lusbuc"
80+---
81+
82+## `+$` "lusbuc"
6483
6584Produce a structure arm (type definition).
6685
67−##### Syntax
86+#### Syntax
6887
69−Regular: **2-fixed**.
88+Two arguments, fixed.
89+
90+Tall form:
7091
7192```hoon
7293+$ p=term q=spec
7394```
7495
96+Wide form:
97+
98+None.
99+
100+Irregular form:
101+
102+None.
103+
75104`p` is an arm name, and `q` is any structure expression.
76105
77−##### Discussion
106+#### Discussion
78107
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.
80109
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`).
82114
83−##### Examples
115+#### Examples
84116
85117```
86118> =c |%
@@ -98,27 +130,41 @@ nest-fail
98130[%.y 22]
99131```
100132
101−### `++` "luslus"
133+---
134+
135+## `++` "luslus"
102136
103137Produce a normal arm.
104138
105−##### Syntax
139+#### Syntax
106140
107−Regular: **2-fixed**.
141+Two arguments, fixed.
142+
143+Tall form:
108144
109145```hoon
110146++ p=term q=hoon
111147```
112148
149+Wide form:
150+
151+None.
152+
153+Irregular form:
154+
155+None.
156+
113157`p` is the arm name, and `q` is any Hoon expression.
114158
115−##### Discussion
159+#### Discussion
116160
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.
118164
119165Any Hoon expression, `q`, may be used to define the arm computation.
120166
121−##### Examples
167+#### Examples
122168
123169```
124170> =c |%
@@ -133,13 +179,17 @@ Any Hoon expression, `q`, may be used to define the arm computation.
13317912
134180```
135181
136−### `+*` "lustar"
182+---
183+
184+## `+*` "lustar"
137185
138186Defines deferred expressions within doors.
139187
140−##### Syntax
188+#### Syntax
141189
142−Regular: **variadic**.
190+Arguments: A variable number of pairs.
191+
192+Tall form:
143193
144194```hoon
145195+* a=term b=hoon
@@ -155,7 +205,7 @@ arguments of `+*` does not end with a terminator.
155205`+*` arms must always come at the beginning of the battery, before any other
156206type of lus arm.
157207
158−##### Discussion
208+#### Discussion
159209
160210The primary use of `+*` is to create deferred expressions within doors (see
161211Examples below). This is a name for an expressions that will be evaluated in
@@ -178,7 +228,9 @@ compiled from this Hoon expression
178228++ y (sub z n)
179229--
180230```
231+
181232as being identical the Nock compiled from this one:
233+
182234```hoon
183235=| z=@ud
184236|%
@@ -191,13 +243,15 @@ as being identical the Nock compiled from this one:
191243--
192244```
193245
194−##### Examples
246+#### Examples
195247
196248To assign an alias to a door, we often write the following.
249+
197250```hoon
198251|_ foo
199252+* this .
200253```
254+
201255This is the idomatic way to assign the alias `this` to the door.
202256
203257Sometimes 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.
211265 samp +<
212266 cont +>
213267```
268+
214269This assigns the door the alias `this`, the sample of the door `samp`, and the
215270context of the door `cont`.
216271
@@ -218,7 +273,7 @@ You may also call functions with `+*` by making use of e.g. the `%~` rune.
218273
219274```hoon
220275=<
221− |_ a=@
276+ |_ a=@
222277 +* do ~(. +> a)
223278 ++ stuff foo:do
224279::etc