@@ -4,64 +4,89 @@ weight = 7
44template = "doc.html"
55aliases = ["docs/reference/hoon-expressions/rune/bar/"]
66+++
7+
78Core expressions produce cores. A core is a cell of `[battery payload]`.
8−The `battery` is code, a battery of Nock formulas. The `payload` is the data
9+The `battery` is code, a battery of Nock formulas. The `payload` is the data
910needed to run those formulas correctly.
1011
11−Five core runes (`|=`, `|.`, `|-`, `|*`, and `|$`) produce a
12−core with a single arm, named `$`. As with all arms, we can recompute `$``
13−with changes, which is useful for recursion among other things.
12+Five core runes (`|=`, `|.`, `|-`, `|*`, and `|$`) produce a core with a single
13+arm, named `$`. As with all arms, we can recompute `$` with changes, which is
14+useful for recursion among other things.
1415
15−## Runes
16+## `|$` "barbuc"
1617
17−### |$ "barbuc"
18+Declares a mold builder wet gate with one or more molds as its sample.
1819
19−Declares a mold builder wet gate with one or more molds as its
20−sample.
20+#### Syntax
2121
22−##### Syntax
22+Two arguments, fixed.
2323
24−Regular:
25−```hoon
26−|$ a=(lest term) b=spec
27−```
24+<table>
25+<tr><th>Form</th><th>Syntax</th></tr>
26+<tr>
27+<td>Tall</td>
28+<td>
29+<pre>
30+|$ sample
31+body
32+</pre>
33+</td>
34+</tr>
35+<tr>
36+<td>Wide</td>
37+<td>
38+<pre>
39+|$(sample body)
40+</pre>
41+</td>
42+</tr>
43+<tr>
44+<td>Irregular</td>
45+<td>None.</td>
46+</tr>
47+</table>
48+
49+#### AST
2850
29−AST:
3051```hoon
31−[%brbs sample=(lest term) body=spec]
52+[%brbc sample=(lest term) body=spec]
3253```
3354
34−##### Semantics
35−
36−`|$` is used to declare a wet gate mold builder that is polymorphic in its input molds. `a` is a `lest` of `term` used as
37−identifiers for the input molds. `b` is a structure built from elements of `a`.
38−The output of `|$` is a mold builder obtained by
39−substituting the input molds parameterized by `a` into `b`.
40−
41−##### Expands to
55+#### Expands to
4256
4357```hoon
4458|$ [a b]
4559body
4660```
61+
4762becomes
63+
4864```hoon
4965|* [a=$~(* $-(* *)) b=$~(* $-(* *))]
5066^:
5167body
5268```
5369
54−##### Discussion
70+#### Semantics
71+
72+`|$` is used to declare a wet gate mold builder that is polymorphic in its input
73+molds. `a` is a `lest` of `term` used as identifiers for the input molds. `b` is
74+a structure built from elements of `a`. The output of `|$` is a mold builder
75+obtained by substituting the input molds parameterized by `a` into `b`.
76+
77+#### Discussion
5578
5679A mold builder is a wet gate from one or more molds to a mold. A mold is a
5780function from nouns to nouns with types that may be partial, is always
5881idempotent, and usually the identity function on the noun itself.
5982
60−`|$` is a restricted form of `|*`. The use of `|$` over `|*` is one of style, as either could
61−be used to make wet gates that are mold builders. The buc in `|$` is a hint that
62−`|$` is closely related to buc runes, and thus `|$` should be used to make mold builders, while `|*` should be used for any other sort of
63−wet gate. Thus, the second argument of `|$` is frequently a buc
64−rune. For further discussion of wet gates, see the entry for [`|*`](#bartar).
83+`|$` is a restricted form of `|*`. The use of `|$` over `|*` is one of style, as
84+either could be used to make wet gates that are mold builders. The buc in `|$`
85+is a hint that `|$` is closely related to buc runes, and thus `|$` should be
86+used to make mold builders, while `|*` should be used for any other sort of wet
87+gate. Unlike `|*`, the body of `|$` is parsed in pattern mode to a `$spec`.
88+Thus, the second argument of `|$` is frequently a buc rune. For further
89+discussion of wet gates, see the entry for [`|*`](#-bartar).
6590
6691Like other single-arm cores, the arm for `|$` is named `$` and this can be used to
6792define recursive structures. Note however that Hoon is evaluated eagerly, and so
@@ -69,53 +94,58 @@ infinite structures are not permitted.
6994
7095Proper style for `|$` is to enclose the first argument with brackets, even if it
7196is only a single term. The interpeter will accept a single term without brackets
72−just fine, but this style is for consistency with the fact that the first argument is a `lest`.
97+just fine, but this style is for consistency with the fact that the first
98+argument is a `lest`.
7399
74−##### Examples
100+#### Examples
75101
76102```
77−~zod:dojo> =foo |$([a b] [b a])
103+> =foo |$([a b] [b a])
78104
79−~zod:dojo> =bar (foo [@ @tas])
105+> =bar (foo [@ @tas])
80106
81−~zod:dojo> (bar %cat 3)
107+> (bar %cat 3)
82108[%cat 3]
83109```
84110
85−### `|_` "barcab"
111+---
112+
113+## `|_` "barcab"
86114
87115Produce a **door** (a core with a sample).
88116
89−##### Syntax
117+#### Syntax
90118
91−Regular:
119+One fixed argument, then a variable number of `+`-family expressions.
92120
93−```hoon
121+<table>
122+<tr><th>Form</th><th>Syntax</th></tr>
123+<tr>
124+<td>Tall</td>
125+<td>
126+<pre>
94127|_ a=spec
95128++ b=term c=hoon
96129++ d=term e=hoon
97130 ...
98131++ f=term g=hoon
99132--
100−```
133+</pre>
134+</td>
135+</tr>
136+<tr><td>Wide</td><td>None.</td></tr>
137+<tr><td>Irregular</td><td>None.</td></tr>
138+</table>
101139
102140Note: The `++` rune may be replaced with any other rune in the `+` family.
103141
104−AST:
142+#### AST
105143
106−```
144+```hoon
107145[%brcb p=spec q=alas r=(map term tome)]
108146```
109147
110−##### Semantics
111−
112−The product of a `|_` expression is a **door**, a core with one or more arms whose payload includes a sample. That is, a door is a cell of `[battery [sample context]]`, where the `battery` contains one or more arms.
113−
114−`a` defines the door sample type and usually includes a name assignment (e.g., `n=@`). `a` is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name (`b`, `d`, and `f` above), which is followed by the expression (`c`, `e`, and `g` above) that defines the arm product.
115−
116−The context of the door is the subject of the `|_` expression.
117−
118−##### Expands to
148+#### Expands to
119149
120150```hoon
121151=| a=spec
@@ -127,29 +157,49 @@ The context of the door is the subject of the `|_` expression.
127157--
128158```
129159
130−##### Discussion
160+#### Semantics
161+
162+The product of a `|_` expression is a **door**, a core with one or more arms
163+whose payload includes a sample. That is, a door is a cell of `[battery [sample context]]`, where the `battery` contains one or more arms.
131164
132−A door is the general case of a gate (function). A gate is a
133−door with only one arm, which has the name `$`.
165+`a` defines the door sample type and usually includes a name assignment (e.g.,
166+`n=@`). `a` is followed by a series of arm definitions, each of which begins
167+with a rune in the `+` family (most of `++`). There must be at least one arm,
168+but there may be arbitrarily many. Each arm must include a name (`b`, `d`, and
169+`f` above), which is followed by the expression (`c`, `e`, and `g` above) that
170+defines the arm product.
134171
135−Calling a door is like calling a gate except the caller also needs
136−to specify the arm to be computed. So, for example, if you have some door `door` which contains some arm `arm`, and you want to pass some argument (i.e., input value `arg`), you would call it with `~(arm door arg)`.
172+The context of the door is the subject of the `|_` expression.
173+
174+#### Discussion
175+
176+A door is the general case of a gate (function). A gate is a door with only one
177+arm, which has the name `$`.
178+
179+Calling a door is like calling a gate except the caller also needs to specify
180+the arm to be computed. So, for example, if you have some door `door` which
181+contains some arm `arm`, and you want to pass some argument (i.e., input value
182+`arg`), you would call it with `~(arm door arg)`.
137183
138−Because gates are also doors, you can call them the same way. To call the gate `foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This
139−is an irregular form for `%~($ foo baz)`, [%~](/docs/hoon/reference/rune/cen#censig).
184+Because gates are also doors, you can call them the same way. To call the gate
185+`foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This is
186+an irregular form for `%~($ foo baz)`,
187+[%~](/docs/hoon/reference/rune/cen#censig).
140188
141−##### Examples
189+#### Examples
142190
143191A trivial door:
144192
145193```
146−/~zod:dojo> =mol |_ a=@ud
147− ++ succ +(a)
148− ++ prev (dec a)
149− --
150−/~zod:dojo> ~(succ mol 1)
194+> =mol |_ a=@ud
195+ ++ succ +(a)
196+ ++ prev (dec a)
197+ --
198+
199+> ~(succ mol 1)
1512002
152−/~zod:dojo> ~(succ mol ~(succ mol ~(prev mol 5)))
201+
202+> ~(succ mol ~(succ mol ~(prev mol 5)))
1532036
154204```
155205
@@ -172,174 +222,246 @@ The `ne` door prints a digit in base 10, 16, 32 or 64:
172222'c'
173223```
174224
175−### `|%` "barcen"
225+---
176226
177−Produce a core, `[battery payload]`.
227+## `|:` "barcol"
178228
179−##### Syntax
229+Produce a gate with a custom sample.
180230
181−Regular:
231+#### Syntax
232+
233+Two arguments, fixed.
234+
235+<table>
236+<tr><th>Form</th><th>Syntax</th></tr>
237+<tr>
238+<td>Tall</td>
239+<td>
240+<pre>
241+|: a
242+b
243+</pre>
244+</td>
245+</tr>
246+<tr>
247+<td>Wide</td>
248+<td>
249+<pre>
250+|:(a b)
251+</pre>
252+</td>
253+</tr>
254+<tr>
255+<td>Irregular</td>
256+<td>None.</td>
257+</tr>
258+</table>
259+
260+#### AST
182261
183262```hoon
184−|%
185−++ a=term b=hoon
186−++ c=term d=hoon
187− ...
188−++ e=term f=hoon
189−--
263+[%brcl p=hoon q=hoon]
190264```
191265
192−Note: The `++` rune may be replaced with any other rune in the `+` family.
266+#### Semantics
193267
194−AST:
268+`a` is a Hoon expression whose product type defines which values the gate accepts, and it usually includes a name (e.g., `n=1`). The product of `a` also serves as the default value of the sample. `b` is a Hoon expression that determines the product value of the gate.
195269
196−```
197−[%brcn p=(unit term) q=(map term tome)]
270+#### Expands to
271+
272+```hoon
273+=+ a
274+|. b
198275```
199276
200−##### Semantics
277+#### Discussion
201278
202−The product of a `|%` expression is a dry core with one or more arms in the battery.
279+Pick your own default value for the sample. Note that `a` is an ordinary
280+expression, not a type; `|:` doesn't bunt a sample as [`|=`](#bartis) does.
203281
204−The `|%` rune is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name (`a`, `c`, and `e` above), which is followed by the expression (`b`, `d`, and `f` above) that defines the arm product.
282+This is useful if you want a gate to have a sample of a particular type, but you don't want the default value of the gate to be the default value of that type.
205283
206−The core payload is the subject of the `|%` expression.
284+#### Examples
207285
208−##### Discussion
286+```
287+> =add-ten |:(n=`@`2 (add n 10))
209288
210−A core is a cell of `[battery payload]`, where the `battery` is code and the `payload` is data. The `battery` is one or more arms. An arm is a computation that takes the core itself as its subject.
289+> (add-ten 10)
290+20
211291
212−The `|%` rune is used to construct a core from a series of arm definitions. Each arm definition in the expression begins with an arm rune (`++`, `+$`, or `+*`). These arms make up the `battery`. The subject of the `|%` expression is used to make the core's `payload`.
292+> (add-ten)
293+12
294+```
213295
214−A core is like an "object" in a conventional language, but its
215−attributes (_arms_) are functions on the core, not the core and
216−an argument. A "method" on a core is an arm that produces a gate.
296+---
217297
218−##### Examples
298+## `|%` "barcen"
219299
220−A trivial core:
300+Produce a core, `[battery payload]`.
221301
222−```
223−~zod:dojo> =foo =+ x=58
224− |%
225− ++ n (add 42 x)
226− ++ g |= b=@
227− (add b n)
228− --
229−~zod:dojo> n.foo
230−100
231−~zod:dojo> (g.foo 1)
232−101
233−```
302+#### Syntax
234303
235−### `|:` "barcol"
304+Argument: a variable number of `+`-family expressions.
236305
237−Produce a gate with a custom sample.
306+<table>
307+<tr><th>Form</th><th>Syntax</th></tr>
308+<tr>
309+<td>Tall</td>
310+<td>
311+<pre>
312+|%
313+++ a=term b=hoon
314+++ c=term d=hoon
315+ ...
316+++ e=term f=hoon
317+--
318+</pre>
319+</td>
320+</tr>
321+<tr><td>Wide</td><td>None.</td></tr>
322+<tr><td>Irregular</td><td>None.</td></tr>
323+</table>
238324
239−##### Syntax
325+Note: The `++` rune may be replaced with any other rune in the `+` family.
240326
241−Regular:
327+#### AST
242328
243329```hoon
244−|: a=hoon b=hoon
330+[%brcn p=(unit term) q=(map term tome)]
245331```
246332
247−AST:
333+#### Semantics
248334
249−```
250−[%brcl p=hoon q=hoon]
251−```
335+The product of a `|%` expression is a dry core with one or more arms in the
336+battery.
252337
253−##### Semantics
338+The `|%` rune is followed by a series of arm definitions, each of which begins
339+with a rune in the `+` family (most of `++`). There must be at least one arm,
340+but there may be arbitrarily many. Each arm must include a name (`a`, `c`, and
341+`e` above), which is followed by the expression (`b`, `d`, and `f` above) that
342+defines the arm product.
254343
255−`a` is a Hoon expression whose product type defines which values the gate accepts, and it usually includes a name (e.g., `n=1`). The product of `a` also serves as the default value of the sample. `b` is a Hoon expression that determines the product value of the gate.
344+The core payload is the subject of the `|%` expression.
256345
257−##### Expands to
346+#### Discussion
258347
259−```hoon
260−=> ^~ a
261− |. b
262−```
348+A core is a cell of `[battery payload]`, where the `battery` is code and the
349+`payload` is data. The `battery` is one or more arms. An arm is a computation
350+that takes the core itself as its subject.
263351
264−##### Discussion
352+The `|%` rune is used to construct a core from a series of arm definitions. Each
353+arm definition in the expression begins with an arm rune (`++`, `+$`, or `+*`).
354+These arms make up the `battery`. The subject of the `|%` expression is used to
355+make the core's `payload`.
265356
266−Pick your own default value for the sample. Note that `a` is an ordinary expression, not a type; `|:` doesn't bunt a sample as
267−[`|=`](#bartis) does.
357+A core is like an "object" in a conventional language, but its attributes
358+(_arms_) are functions on the core, not the core and an argument. A "method" on
359+a core is an arm that produces a gate.
268360
269−This is useful if you want a gate to have a sample of a particular type, but you don't want the default value of the gate to be the default value of that type.
361+#### Examples
270362
271−##### Examples
363+A trivial core:
272364
273365```
274−> =add-ten |:(n=`@`2 (add n 10))
366+> =foo =+ x=58
367+ |%
368+ ++ n (add 42 x)
369+ ++ g |= b=@
370+ (add b n)
371+ --
275372
276−> (add-ten 10)
277−20
373+> n.foo
374+100
278375
279−> (add-ten)
280−12
376+> (g.foo 1)
377+101
281378```
282379
283−### `|.` "bardot"
380+---
284381
285−Produce a trap (a core with one arm `$`).
382+## `|.` "bardot"
286383
287−##### Syntax
384+Produce a trap (a core with one arm `$`).
288385
289−Regular:
386+#### Syntax
387+
388+One argument, fixed.
389+
390+<table>
391+<tr><th>Form</th><th>Syntax</th></tr>
392+<tr>
393+<td>Tall</td>
394+<td>
395+<pre>
396+|. a
397+</pre>
398+</td>
399+</tr>
400+<tr>
401+<td>Wide</td>
402+<td>
403+<pre>
404+|.(a)
405+</pre>
406+</td>
407+</tr>
408+<tr>
409+<td>Irregular</td>
410+<td>None.</td>
411+</tr>
412+</table>
413+
414+#### AST
290415
291416```hoon
292−|. a=hoon
293−```
294−
295−AST:
296−
297−```
298417[%brdt p=hoon]
299418```
300419
301−##### Semantics
302−
303−A `|.` expression produces a core with a single arm, `$`. The core isn't explicitly given a sample. `a` is a Hoon expression that defines the computation of the `$` arm.
304−
305−The payload of the core is the subject of the `|.` expression.
306−
307−##### Expands to
420+#### Expands to
308421
309422```hoon
310423|% ++ $ a=hoon
311424--
312425```
313426
314−##### Discussion
427+#### Semantics
428+
429+A `|.` expression produces a core with a single arm, `$`. The core isn't
430+explicitly given a sample. `a` is a Hoon expression that defines the computation
431+of the `$` arm.
432+
433+The payload of the core is the subject of the `|.` expression.
434+
435+#### Discussion
315436
316437A trap is generally used to defer a computation.
317438
318−##### Examples
439+#### Examples
319440
320441A trivial trap:
321442
322443```
323−~zod:dojo> =foo |.(42)
444+> =foo |.(42)
324445
325−~zod:dojo> $:foo
446+> $:foo
32644742
327448
328−~zod:dojo> (foo)
449+> (foo)
32945042
330451```
331452
332453A more interesting trap:
333454
334455```
335−~zod:dojo> =foo =/ reps 10
336− =/ step 0
337− =/ outp 0
338− |.
339− ?: =(step reps)
340− outp
341− $(outp (add outp 2), step +(step))
342−~zod:dojo> (foo)
456+> =foo =/ reps 10
457+ =/ step 0
458+ =/ outp 0
459+ |.
460+ ?: =(step reps)
461+ outp
462+ $(outp (add outp 2), step +(step))
463+
464+> (foo)
34346520
344466```
345467
@@ -348,92 +470,43 @@ trap, since it's a core with an `$` arm.
348470
349471> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
350472
351−### `|-` "barhep"
352−
353−Produce a trap (a core with one arm `$`) and evaluate it.
354−
355−##### Syntax
356−
357−Regular:
358−
359−```hoon
360−|- a=hoon
361−```
362−
363−AST:
364−
365−```
366−[%brhp p=hoon]
367−```
368−
369−##### Semantics
370−
371−A `|-` expression produces a core with one arm named `$` and immediately evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
473+---
372474
373−##### Expands to
374−
375−```hoon
376−=<($ |.(a=hoon))
377−```
378−
379−##### Discussion
380−
381−The `|-` rune can be thought of as a 'recursion point' or a 'loop starting point'. Since `|-` makes a `|.` (["bardot"](#bardot), a core with one arm named `$`, we can recurse back into it with `$()`.
382−
383−> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
384−
385−##### Examples
386−
387−A trivial computation doesn't recurse:
388−
389−```
390−~zod:dojo> |-(42)
391−42
392−```
393−
394−The classic loop is a decrement:
395−
396−```
397−~zod:dojo> =foo =/ a 42
398− =/ b 0
399− |-
400− ?: =(a +(b))
401− b
402− $(b +(b))
403−~zod:dojo> foo
404−41
405−```
406−
407−### `|^` "barket"
475+## `|^` "barket"
408476
409477Produce a core whose battery includes a `$` arm and compute the latter.
410478
411−##### Syntax
479+#### Syntax
412480
413−Regular:
481+One fixed argument, then a variable number of `+`-family expressions.
414482
415−```hoon
483+<table>
484+<tr><th>Form</th><th>Syntax</th></tr>
485+<tr>
486+<td>Tall</td>
487+<td>
488+<pre>
416489|^ a=hoon
417490++ b=term c=hoon
418491++ d=term e=hoon
419492 ...
420493++ f=term g=hoon
421494--
422−```
495+</pre>
496+</td>
497+</tr>
498+<tr>
499+<td>Wide</td><td>None.</td></tr>
500+<tr><td>Irregular</td><td>None.</td></tr>
501+</table>
423502
424−Note: The `++` rune may be replaced with any other rune in the `+` family.
425−
426−AST:
503+#### AST
427504
428−```
505+```hoon
429506[%brkt p=hoon q=(map term tome)]
430507```
431508
432−##### Semantics
433−
434−A `|^` expression produces a multi-arm core whose battery includes a `$` arm, which is evaluated immediately. `a` is a Hoon expression that defines the product of the `$` arm. `a` is followed by a series of arm definitions for the rest of the core battery arms. There must be at least one arm other than the `$` arm.
435−
436−##### Expands to
509+#### Expands to
437510
438511```hoon
439512=> |%
@@ -446,86 +519,218 @@ A `|^` expression produces a multi-arm core whose battery includes a `$` arm, wh
446519$
447520```
448521
449−##### Discussion
522+#### Semantics
523+
524+A `|^` expression produces a multi-arm core whose battery includes a `$` arm,
525+which is evaluated immediately. `a` is a Hoon expression that defines the
526+product of the `$` arm. `a` is followed by a series of arm definitions for the
527+rest of the core battery arms. There must be at least one arm other than the `$`
528+arm.
450529
451−The `|^` rune is useful when you define a multi-arm core in your code and a particular arm in it is to be evaluated immediately.
530+#### Discussion
452531
453−##### Examples
532+The `|^` rune is useful when you define a multi-arm core in your code and a
533+particular arm in it is to be evaluated immediately.
534+
535+#### Examples
454536
455537A trivial example:
456538
457539```
458−~zod:dojo> |^
459− (add n g)
460− ++ n 42
461− ++ g 58
462− --
540+> |^
541+ (add n g)
542+ ++ n 42
543+ ++ g 58
544+ --
463545100
464546```
465547
466−### `|~` "barsig"
548+---
467549
468−Produce an iron gate.
550+## `|-` "barhep"
469551
470−##### Syntax
552+Produce a trap (a core with one arm `$`) and evaluate it.
471553
472−Regular:
554+#### Syntax
555+
556+One argument, fixed.
557+
558+<table>
559+<tr><th>Form</th><th>Syntax</th></tr>
560+<tr>
561+<td>Tall</td>
562+<td>
563+<pre>
564+|- a
565+</pre>
566+</td>
567+</tr>
568+<tr>
569+<td>Wide</td>
570+<td>
571+<pre>
572+|-(a)
573+</pre>
574+</td>
575+</tr>
576+<tr>
577+<td>Irregular</td>
578+<td>None.</td>
579+</tr>
580+</table>
581+
582+#### AST
473583
474584```hoon
475−|~ a=spec b=hoon
585+[%brhp p=hoon]
476586```
477587
478−AST:
588+#### Expands to
479589
590+```hoon
591+=<($ |.(a=hoon))
480592```
481−[%brsg p=spec q=hoon]
593+
594+#### Semantics
595+
596+A `|-` expression produces a core with one arm named `$` and immediately
597+evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
598+
599+#### Discussion
600+
601+The `|-` rune can be thought of as a 'recursion point' or a 'loop starting
602+point'. Since `|-` makes a `|.` (["bardot"](#bardot), a core with one arm named
603+`$`, we can recurse back into it with `$()`.
604+
605+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
606+
607+#### Examples
608+
609+A trivial computation doesn't recurse:
610+
611+```
612+> |-(42)
613+42
614+```
615+
616+The classic loop is a decrement:
617+
618+```
619+> =foo =/ a 42
620+ =/ b 0
621+ |-
622+ ?: =(a +(b))
623+ b
624+ $(b +(b))
625+
626+> foo
627+41
482628```
483629
484−##### Semantics
630+---
631+
632+## `|~` "barsig"
633+
634+Produce an iron gate.
635+
636+#### Syntax
637+
638+Two arguments, fixed.
639+
640+<table>
641+<tr><th>Form</th><th>Syntax</th></tr>
642+<tr>
643+<td>Tall</td>
644+<td>
645+<pre>
646+|~ a
647+b
648+</pre>
649+</td>
650+</tr>
651+<tr>
652+<td>Wide</td>
653+<td>
654+<pre>
655+|~(a b)
656+</pre>
657+</td>
658+</tr>
659+<tr>
660+<td>Irregular</td>
661+<td>None.</td>
662+</tr>
663+</table>
664+
665+#### AST
485666
486−A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines the output value of the gate.
667+```hoon
668+[%brsg p=spec q=hoon]
669+```
487670
488−##### Expands to
671+#### Expands to
489672
490673```hoon
491674^| |=(a b)
492675```
493676
494−##### Discussion
677+#### Semantics
678+
679+A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines
680+the output value of the gate.
681+
682+#### Discussion
495683
496684See [this discussion of core variance models](/docs/hoon/reference/advanced)
497685
498−##### Examples
686+#### Examples
499687
500688```
501−~zod:dojo> => ~ ^+(|~(a=@ *@) |=(a=* *@))
689+> => ~ ^+(|~(a=@ *@) |=(a=* *@))
502690<1|usl {a/@ $~}>
503691```
504692
505−### `|*` "bartar"
693+---
506694
507−Produce a wet gate (one-armed core with sample).
695+## `|*` "bartar"
508696
509−##### Syntax
697+Produce a wet gate (one-armed core with sample).
510698
511−Regular:
699+#### Syntax
700+
701+Two arguments, fixed.
702+
703+<table>
704+<tr><th>Form</th><th>Syntax</th></tr>
705+<tr>
706+<td>Tall</td>
707+<td>
708+<pre>
709+|* a b
710+</pre>
711+</td>
712+</tr>
713+<tr>
714+<td>Wide</td>
715+<td>
716+<pre>
717+|*(a b)
718+</pre>
719+</td>
720+</tr>
721+<tr>
722+<td>Irregular</td>
723+<td>None.</td>
724+</tr>
725+</table>
726+
727+#### AST
512728
513729```hoon
514−|* a=spec b=hoon
515−```
516−
517−AST:
518−
519−```
520730[%brtr p=spec q=hoon]
521731```
522732
523−##### Semantics
524−
525−A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b`
526−is a Hoon expression that determines the output value of the gate.
527−
528−##### Expands to
733+#### Expands to
529734
530735```hoon
531736=| a
@@ -535,14 +740,19 @@ is a Hoon expression that determines the output value of the gate.
535740--
536741```
537742
538−##### Discussion
743+#### Semantics
744+
745+A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b` is
746+a Hoon expression that determines the output value of the gate.
747+
748+#### Discussion
539749
540750In a normal (dry) gate, your argument is converted into the
541−sample type. In a generic (wet) gate, your argument type
751+sample type. In a generic (wet) gate, your argument type
542752passes through the function, rather as if it were a macro (there
543753is still only one copy of the code, however).
544754
545−Genericity is a powerful and dangerous tool. Use wet gates only if
755+Genericity is a powerful and dangerous tool. Use wet gates only if
546756you know what you're doing.
547757
548758Just as with a [gate](#bartis), we can recurse back into a wet gate
@@ -553,58 +763,83 @@ with `$()`.
553763`|*` can be used to make wet gates that produce structures, but this usage is
554764discouraged in favor of `|$`.
555765
556−##### Examples
766+#### Examples
557767
558768Wet and dry gates in a nutshell:
559769
560770```
561−~zod:dojo> =foo |=([a=* b=*] [b a])
771+> =foo |=([a=* b=*] [b a])
562772
563−~zod:dojo> =bar |*([a=* b=*] [b a])
773+> =bar |*([a=* b=*] [b a])
564774
565−~zod:dojo> (foo %cat %dog)
775+> (foo %cat %dog)
566776[6.778.724 7.627.107]
567777
568−~zod:dojo> (bar %cat %dog)
778+> (bar %cat %dog)
569779[%dog %cat]
570780```
571781
572782The dry gate does not preserve the type of `a` and `b`; the wet
573783gate does.
574784
575−### `|=` "bartis"
785+---
576786
577−Produce a gate (a one-armed core with a sample).
787+## `|=` "bartis"
578788
579−##### Syntax
789+Produce a gate (a one-armed core with a sample).
580790
581−Regular:
791+#### Syntax
792+
793+Two arguments, fixed.
794+
795+<table>
796+<tr><th>Form</th><th>Syntax</th></tr>
797+<tr>
798+<td>Tall</td>
799+<td>
800+<pre>
801+|= a
802+b
803+</pre>
804+</td>
805+</tr>
806+<tr>
807+<td>Wide</td>
808+<td>
809+<pre>
810+|=(a b)
811+</pre>
812+</td>
813+</tr>
814+<tr>
815+<td>Irregular</td>
816+<td>None.</td>
817+</tr>
818+</table>
819+
820+#### AST
582821
583822```hoon
584−|= a=spec b=hoon
585−```
586−
587−AST:
588−
589−```
590823[%brts p=spec q=hoon]
591824```
592825
593−##### Definition
594−
595−The product of a `|=` expression is a dry **gate**, i.e., a Hoon function.
596−
597−`p` defines the gate sample type -- i.e., the input value type -- and usually includes a sample name assignment (e.g., `a=@`). `q` is an expression that determines the output value of the gate.
598−
599−##### Expands to
826+#### Expands to
600827
601828```hoon
602−=| a=spec
829+=+ ^~(*a=spec)
603830|% ++ $ b=hoon
604831--
605832```
606833
607−##### Discussion
834+#### Definition
835+
836+The product of a `|=` expression is a dry **gate**, i.e., a Hoon function.
837+
838+`p` defines the gate sample type -- i.e., the input value type -- and usually
839+includes a sample name assignment (e.g., `a=@`). `q` is an expression that
840+determines the output value of the gate.
841+
842+#### Discussion
608843
609844Dry gates are used for the vast majority of ordinary functions in Hoon.
610845
@@ -612,97 +847,138 @@ A gate is a core with one arm named `$`, so we can recurse back into it with `$(
612847
613848> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
614849
615−##### Examples
850+#### Examples
616851
617852A trivial gate:
618853
619854```
620−~zod:dojo> =foo |=(a=@ +(a))
855+> =foo |=(a=@ +(a))
621856
622−~zod:dojo> (foo 20)
857+> (foo 20)
62385821
624859```
625860
626861A slightly less trivial gate:
627862
628863```
629−~zod:dojo> =foo |= [a=@ b=@]
630− (add a b)
631−~zod:dojo> (foo 30 400)
864+> =foo |= [a=@ b=@]
865+ (add a b)
866+
867+> (foo 30 400)
632868430
633869```
634870
635−### `|@` "barpat"
871+---
872+
873+## `|@` "barpat"
636874
637875Produce a 'wet' core `[battery payload]`.
638876
639−##### Syntax
877+#### Syntax
640878
641−Regular:
879+Arguments: a variable number of `+`-family expressions.
642880
643−```hoon
881+<table>
882+<tr><th>Form</th><th>Syntax</th></tr>
883+<tr>
884+<td>Tall</td>
885+<td>
886+<pre>
644887|@
645888++ a=term b=hoon
646889++ c=term d=hoon
647890 ...
648891++ e=term f=hoon
649892--
650−```
893+</pre>
894+</td>
895+</tr>
896+<tr><td>Wide</td><td>None.</td></tr>
897+<tr><td>Irregular</td><td>None.</td></tr>
898+</table>
651899
652900Note: The `++` rune may be replaced with any other rune in the `+` family.
653901
654−AST:
902+#### AST
655903
656−```
904+```hoon
657905[%brpt p=(unit term) q=(map term tome)]
658906```
659907
660−##### Semantics
908+#### Semantics
661909
662−A `|@` expression produces a 'wet' core whose payload is the expression's subject. The various arms in the battery are each named (`a`, `c`, and `e` above) and defined explicitly with a Hoon expression (with `b`, `d`, and `f` above).
910+A `|@` expression produces a 'wet' core whose payload is the expression's
911+subject. The various arms in the battery are each named (`a`, `c`, and `e`
912+above) and defined explicitly with a Hoon expression (with `b`, `d`, and `f`
913+above).
663914
664−##### Discussion
915+#### Discussion
665916
666−The `|@` rune is just like the `|%` rune except that instead of producing a 'dry' core, it produces a 'wet' one. This allows for type polymorphism of its arms, using 'genericity'. See [Advanced types](/docs/hoon/reference/advanced).
917+The `|@` rune is just like the `|%` rune except that instead of producing a
918+'dry' core, it produces a 'wet' one. This allows for type polymorphism of its
919+arms, using 'genericity'. See [Advanced types](/docs/hoon/reference/advanced).
667920
668−### `|?` "barwut"
921+---
669922
670−Produce a lead trap.
923+## `|?` "barwut"
671924
672−##### Syntax
925+Produce a lead trap.
673926
674−Regular:
927+#### Syntax
928+
929+One argument, fixed.
930+
931+<table>
932+<tr><th>Form</th><th>Syntax</th></tr>
933+<tr>
934+<td>Tall</td>
935+<td>
936+<pre>
937+|? a
938+</pre>
939+</td>
940+</tr>
941+<tr>
942+<td>Wide</td>
943+<td>
944+<pre>
945+|?(a)
946+</pre>
947+</td>
948+</tr>
949+<tr>
950+<td>Irregular</td>
951+<td>None.</td>
952+</tr>
953+</table>
954+
955+#### AST
675956
676957```hoon
677−|? a=hoon
678−```
679−
680−AST:
681−
682−```
683958[%brwt p=hoon]
684959```
685960
686−##### Semantics
687−
688−A `|?` expression produces a lead trap (i.e., a lead core with one arm named `$`). `a` is a Hoon expression that defines what the `$` arm does.
689−
690−##### Expands to
961+#### Expands to
691962
692963```hoon
693964^? |. a
694965```
695966
696−##### Discussion
967+#### Semantics
968+
969+A `|?` expression produces a lead trap (i.e., a lead core with one arm named
970+`$`). `a` is a Hoon expression that defines what the `$` arm does.
971+
972+#### Discussion
697973
698974See this [discussion of the core variance model](/docs/hoon/reference/advanced).
699975
700−##### Examples
976+#### Examples
701977
702978```
703−~zod:dojo> => ~ ^+ |?(%a) |.(%a)
979+> => ~ ^+ |?(%a) |.(%a)
704980<1?pqz $~>
705981
706−~zod:dojo> => ~ ^+ |?(%a) |.(%b)
982+> => ~ ^+ |?(%a) |.(%b)
707983nest-fail
708984```