@@ -4,64 +4,80 @@ 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.
15+
16+## `|$` "barbuc"
1417
15−## Runes
18+Declares a mold builder wet gate with one or more molds as its sample.
1619
17−### |$ "barbuc"
20+#### Syntax
1821
19−Declares a mold builder wet gate with one or more molds as its
20−sample.
22+Two arguments, fixed.
2123
22−##### Syntax
24+Tall form:
2325
24−Regular:
2526```hoon
26−|$ a=(lest term) b=spec
27+|$ sample
28+body
2729```
2830
29−AST:
31+Wide form:
32+
3033```hoon
31−[%brbs sample=(lest term) body=spec]
34+|$(sample body)
3235```
3336
34−##### Semantics
37+Irregular form:
3538
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`.
39+None.
40+
41+#### AST
42+
43+```hoon
44+[%brbc sample=(lest term) body=spec]
45+```
4046
41−##### Expands to
47+#### Expands to
4248
4349```hoon
4450|$ [a b]
4551body
4652```
53+
4754becomes
55+
4856```hoon
4957|* [a=$~(* $-(* *)) b=$~(* $-(* *))]
5058^:
5159body
5260```
5361
54−##### Discussion
62+#### Semantics
63+
64+`|$` is used to declare a wet gate mold builder that is polymorphic in its input
65+molds. `a` is a `lest` of `term` used as identifiers for the input molds. `b` is
66+a structure built from elements of `a`. The output of `|$` is a mold builder
67+obtained by substituting the input molds parameterized by `a` into `b`.
68+
69+#### Discussion
5570
5671A mold builder is a wet gate from one or more molds to a mold. A mold is a
5772function from nouns to nouns with types that may be partial, is always
5873idempotent, and usually the identity function on the noun itself.
5974
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).
75+`|$` is a restricted form of `|*`. The use of `|$` over `|*` is one of style, as
76+either could be used to make wet gates that are mold builders. The buc in `|$`
77+is a hint that `|$` is closely related to buc runes, and thus `|$` should be
78+used to make mold builders, while `|*` should be used for any other sort of wet
79+gate. Thus, the second argument of `|$` is frequently a buc rune. For further
80+discussion of wet gates, see the entry for [`|*`](#-bartar).
6581
6682Like other single-arm cores, the arm for `|$` is named `$` and this can be used to
6783define recursive structures. Note however that Hoon is evaluated eagerly, and so
@@ -69,26 +85,31 @@ infinite structures are not permitted.
6985
7086Proper style for `|$` is to enclose the first argument with brackets, even if it
7187is 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`.
88+just fine, but this style is for consistency with the fact that the first
89+argument is a `lest`.
7390
74−##### Examples
91+#### Examples
7592
7693```
77−~zod:dojo> =foo |$([a b] [b a])
94+> =foo |$([a b] [b a])
7895
79−~zod:dojo> =bar (foo [@ @tas])
96+> =bar (foo [@ @tas])
8097
81−~zod:dojo> (bar %cat 3)
98+> (bar %cat 3)
8299[%cat 3]
83100```
84101
85−### `|_` "barcab"
102+---
103+
104+## `|_` "barcab"
86105
87106Produce a **door** (a core with a sample).
88107
89−##### Syntax
108+#### Syntax
109+
110+One fixed argument, then a variable number of `+`-family expressions.
90111
91−Regular:
112+Tall form:
92113
93114```hoon
94115|_ a=spec
@@ -101,21 +122,21 @@ Regular:
101122
102123Note: The `++` rune may be replaced with any other rune in the `+` family.
103124
104−AST:
125+Wide form:
105126
106−```
107−[%brcb p=spec q=alas r=(map term tome)]
108−```
127+None.
109128
110−##### Semantics
129+Irregular form:
111130
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.
131+None.
113132
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.
133+#### AST
115134
116−The context of the door is the subject of the `|_` expression.
135+```hoon
136+[%brcb p=spec q=alas r=(map term tome)]
137+```
117138
118−##### Expands to
139+#### Expands to
119140
120141```hoon
121142=| a=spec
@@ -127,29 +148,49 @@ The context of the door is the subject of the `|_` expression.
127148--
128149```
129150
130−##### Discussion
151+#### Semantics
152+
153+The product of a `|_` expression is a **door**, a core with one or more arms
154+whose payload includes a sample. That is, a door is a cell of `[battery [sample context]]`, where the `battery` contains one or more arms.
155+
156+`a` defines the door sample type and usually includes a name assignment (e.g.,
157+`n=@`). `a` is followed by a series of arm definitions, each of which begins
158+with a rune in the `+` family (most of `++`). There must be at least one arm,
159+but there may be arbitrarily many. Each arm must include a name (`b`, `d`, and
160+`f` above), which is followed by the expression (`c`, `e`, and `g` above) that
161+defines the arm product.
162+
163+The context of the door is the subject of the `|_` expression.
164+
165+#### Discussion
131166
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 `$`.
167+A door is the general case of a gate (function). A gate is a door with only one
168+arm, which has the name `$`.
134169
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)`.
170+Calling a door is like calling a gate except the caller also needs to specify
171+the arm to be computed. So, for example, if you have some door `door` which
172+contains some arm `arm`, and you want to pass some argument (i.e., input value
173+`arg`), you would call it with `~(arm door arg)`.
137174
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).
175+Because gates are also doors, you can call them the same way. To call the gate
176+`foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This is
177+an irregular form for `%~($ foo baz)`,
178+[%~](/docs/hoon/reference/rune/cen#censig).
140179
141−##### Examples
180+#### Examples
142181
143182A trivial door:
144183
145184```
146−/~zod:dojo> =mol |_ a=@ud
147− ++ succ +(a)
148− ++ prev (dec a)
149− --
150−/~zod:dojo> ~(succ mol 1)
185+> =mol |_ a=@ud
186+ ++ succ +(a)
187+ ++ prev (dec a)
188+ --
189+
190+> ~(succ mol 1)
1511912
152−/~zod:dojo> ~(succ mol ~(succ mol ~(prev mol 5)))
192+
193+> ~(succ mol ~(succ mol ~(prev mol 5)))
1531946
154195```
155196
@@ -172,103 +213,58 @@ The `ne` door prints a digit in base 10, 16, 32 or 64:
172213'c'
173214```
174215
175−### `|%` "barcen"
216+---
176217
177−Produce a core, `[battery payload]`.
218+## `|:` "barcol"
178219
179−##### Syntax
220+Produce a gate with a custom sample.
180221
181−Regular:
222+#### Syntax
182223
183−```hoon
184−|%
185−++ a=term b=hoon
186−++ c=term d=hoon
187− ...
188−++ e=term f=hoon
189−--
190−```
191−
192−Note: The `++` rune may be replaced with any other rune in the `+` family.
224+Two arguments, fixed.
193225
194−AST:
226+Tall form:
195227
228+```hoon
229+|: a
230+b
196231```
197−[%brcn p=(unit term) q=(map term tome)]
198−```
199−
200−##### Semantics
201−
202−The product of a `|%` expression is a dry core with one or more arms in the battery.
203−
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.
205−
206−The core payload is the subject of the `|%` expression.
207232
208−##### Discussion
233+Wide form:
209234
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.
211−
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`.
213−
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.
217−
218−##### Examples
219−
220−A trivial core:
221−
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
235+```hoon
236+|:(a b)
233237```
234238
235−### `|:` "barcol"
236−
237−Produce a gate with a custom sample.
239+Irregular form:
238240
239−##### Syntax
241+None
240242
241−Regular:
243+#### AST
242244
243245```hoon
244−|: a=hoon b=hoon
245−```
246−
247−AST:
248−
249−```
250246[%brcl p=hoon q=hoon]
251247```
252248
253−##### Semantics
249+#### Semantics
254250
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.
251+`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.
256252
257−##### Expands to
253+#### Expands to
258254
259255```hoon
260256=> ^~ a
261257 |. b
262258```
263259
264−##### Discussion
260+#### Discussion
265261
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.
262+Pick your own default value for the sample. Note that `a` is an ordinary
263+expression, not a type; `|:` doesn't bunt a sample as [`|=`](#bartis) does.
268264
269265This 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.
270266
271−##### Examples
267+#### Examples
272268
273269```
274270> =add-ten |:(n=`@`2 (add n 10))
@@ -280,137 +276,186 @@ This is useful if you want a gate to have a sample of a particular type, but you
28027612
281277```
282278
283−### `|.` "bardot"
279+---
284280
285−Produce a trap (a core with one arm `$`).
281+## `|%` "barcen"
282+
283+Produce a core, `[battery payload]`.
286284
287−##### Syntax
285+#### Syntax
288286
289−Regular:
287+Argument: a variable number of `+`-family expressions.
288+
289+Tall form:
290290
291291```hoon
292−|. a=hoon
292+|%
293+++ a=term b=hoon
294+++ c=term d=hoon
295+ ...
296+++ e=term f=hoon
297+--
293298```
294299
295−AST:
300+Note: The `++` rune may be replaced with any other rune in the `+` family.
296301
297−```
298−[%brdt p=hoon]
299−```
302+Wide form:
300303
301−##### Semantics
304+None.
302305
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.
306+Irregular form:
304307
305−The payload of the core is the subject of the `|.` expression.
308+None.
306309
307−##### Expands to
310+#### AST
308311
309312```hoon
310−|% ++ $ a=hoon
311−--
313+[%brcn p=(unit term) q=(map term tome)]
312314```
313315
314−##### Discussion
316+#### Semantics
315317
316−A trap is generally used to defer a computation.
318+The product of a `|%` expression is a dry core with one or more arms in the
319+battery.
317320
318−##### Examples
321+The `|%` rune is followed by a series of arm definitions, each of which begins
322+with a rune in the `+` family (most of `++`). There must be at least one arm,
323+but there may be arbitrarily many. Each arm must include a name (`a`, `c`, and
324+`e` above), which is followed by the expression (`b`, `d`, and `f` above) that
325+defines the arm product.
319326
320−A trivial trap:
327+The core payload is the subject of the `|%` expression.
321328
322−```
323−~zod:dojo> =foo |.(42)
329+#### Discussion
324330
325−~zod:dojo> $:foo
326−42
331+A core is a cell of `[battery payload]`, where the `battery` is code and the
332+`payload` is data. The `battery` is one or more arms. An arm is a computation
333+that takes the core itself as its subject.
327334
328−~zod:dojo> (foo)
329−42
330−```
335+The `|%` rune is used to construct a core from a series of arm definitions. Each
336+arm definition in the expression begins with an arm rune (`++`, `+$`, or `+*`).
337+These arms make up the `battery`. The subject of the `|%` expression is used to
338+make the core's `payload`.
331339
332−A more interesting trap:
340+A core is like an "object" in a conventional language, but its attributes
341+(_arms_) are functions on the core, not the core and an argument. A "method" on
342+a core is an arm that produces a gate.
343+
344+#### Examples
345+
346+A trivial core:
333347
334348```
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)
343−20
349+> =foo =+ x=58
350+ |%
351+ ++ n (add 42 x)
352+ ++ g |= b=@
353+ (add b n)
354+ --
355+
356+> n.foo
357+100
358+
359+> (g.foo 1)
360+101
344361```
345362
346−Note that we can use `$()` to recurse back into the
347−trap, since it's a core with an `$` arm.
363+---
348364
349−> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
365+## `|.` "bardot"
350366
351−### `|-` "barhep"
367+Produce a trap (a core with one arm `$`).
352368
353−Produce a trap (a core with one arm `$`) and evaluate it.
369+#### Syntax
354370
355−##### Syntax
371+One argument, fixed.
356372
357−Regular:
373+Tall form:
358374
359375```hoon
360−|- a=hoon
376+|. a
361377```
362378
363−AST:
379+Wide form:
364380
365−```
366−[%brhp p=hoon]
381+```hoon
382+|.(a)
367383```
368384
369−##### Semantics
385+Irregular form:
370386
371−A `|-` expression produces a core with one arm named `$` and immediately evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
387+None.
372388
373−##### Expands to
389+#### AST
374390
375391```hoon
376−=<($ |.(a=hoon))
392+[%brdt p=hoon]
377393```
378394
379−##### Discussion
395+#### Expands to
380396
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 `$()`.
397+```hoon
398+|% ++ $ a=hoon
399+--
400+```
382401
383−> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
402+#### Semantics
384403
385−##### Examples
404+A `|.` expression produces a core with a single arm, `$`. The core isn't
405+explicitly given a sample. `a` is a Hoon expression that defines the computation
406+of the `$` arm.
386407
387−A trivial computation doesn't recurse:
408+The payload of the core is the subject of the `|.` expression.
409+
410+#### Discussion
411+
412+A trap is generally used to defer a computation.
413+
414+#### Examples
415+
416+A trivial trap:
388417
389418```
390−~zod:dojo> |-(42)
419+> =foo |.(42)
420+
421+> $:foo
422+42
423+
424+> (foo)
39142542
392426```
393427
394−The classic loop is a decrement:
428+A more interesting trap:
395429
396430```
397−~zod:dojo> =foo =/ a 42
398− =/ b 0
399− |-
400− ?: =(a +(b))
401− b
402− $(b +(b))
403−~zod:dojo> foo
404−41
431+> =foo =/ reps 10
432+ =/ step 0
433+ =/ outp 0
434+ |.
435+ ?: =(step reps)
436+ outp
437+ $(outp (add outp 2), step +(step))
438+
439+> (foo)
440+20
405441```
406442
407−### `|^` "barket"
443+Note that we can use `$()` to recurse back into the
444+trap, since it's a core with an `$` arm.
445+
446+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
447+
448+---
449+
450+## `|^` "barket"
408451
409452Produce a core whose battery includes a `$` arm and compute the latter.
410453
411−##### Syntax
454+#### Syntax
455+
456+One fixed argument, then a variable number of `+`-family expressions.
412457
413−Regular:
458+Tall form:
414459
415460```hoon
416461|^ a=hoon
@@ -423,17 +468,21 @@ Regular:
423468
424469Note: The `++` rune may be replaced with any other rune in the `+` family.
425470
426−AST:
471+Wide form:
427472
428−```
429−[%brkt p=hoon q=(map term tome)]
430−```
473+None.
474+
475+Irregular form:
431476
432−##### Semantics
477+None.
433478
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.
479+#### AST
480+
481+```hoon
482+[%brkt p=hoon q=(map term tome)]
483+```
435484
436−##### Expands to
485+#### Expands to
437486
438487```hoon
439488=> |%
@@ -446,86 +495,194 @@ A `|^` expression produces a multi-arm core whose battery includes a `$` arm, wh
446495$
447496```
448497
449−##### Discussion
498+#### Semantics
499+
500+A `|^` expression produces a multi-arm core whose battery includes a `$` arm,
501+which is evaluated immediately. `a` is a Hoon expression that defines the
502+product of the `$` arm. `a` is followed by a series of arm definitions for the
503+rest of the core battery arms. There must be at least one arm other than the `$`
504+arm.
505+
506+#### Discussion
450507
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.
508+The `|^` rune is useful when you define a multi-arm core in your code and a
509+particular arm in it is to be evaluated immediately.
452510
453−##### Examples
511+#### Examples
454512
455513A trivial example:
456514
457515```
458−~zod:dojo> |^
459− (add n g)
460− ++ n 42
461− ++ g 58
462− --
516+> |^
517+ (add n g)
518+ ++ n 42
519+ ++ g 58
520+ --
463521100
464522```
465523
466−### `|~` "barsig"
524+---
467525
468−Produce an iron gate.
526+## `|-` "barhep"
527+
528+Produce a trap (a core with one arm `$`) and evaluate it.
469529
470−##### Syntax
530+#### Syntax
471531
472−Regular:
532+One argument, fixed.
533+
534+Tall form:
473535
474536```hoon
475−|~ a=spec b=hoon
537+|- a
476538```
477539
478−AST:
540+Wide form:
479541
542+```hoon
543+|-(a)
480544```
481−[%brsg p=spec q=hoon]
545+
546+Irregular form:
547+
548+None.
549+
550+#### AST
551+
552+```hoon
553+[%brhp p=hoon]
554+```
555+
556+#### Expands to
557+
558+```hoon
559+=<($ |.(a=hoon))
560+```
561+
562+#### Semantics
563+
564+A `|-` expression produces a core with one arm named `$` and immediately
565+evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
566+
567+#### Discussion
568+
569+The `|-` rune can be thought of as a 'recursion point' or a 'loop starting
570+point'. Since `|-` makes a `|.` (["bardot"](#bardot), a core with one arm named
571+`$`, we can recurse back into it with `$()`.
572+
573+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
574+
575+#### Examples
576+
577+A trivial computation doesn't recurse:
578+
579+```
580+> |-(42)
581+42
582+```
583+
584+The classic loop is a decrement:
585+
586+```
587+> =foo =/ a 42
588+ =/ b 0
589+ |-
590+ ?: =(a +(b))
591+ b
592+ $(b +(b))
593+
594+> foo
595+41
596+```
597+
598+---
599+
600+## `|~` "barsig"
601+
602+Produce an iron gate.
603+
604+#### Syntax
605+
606+Two arguments, fixed.
607+
608+Tall form:
609+
610+```hoon
611+|~ a
612+b
613+```
614+
615+Wide form:
616+
617+```hoon
618+|~(a b)
482619```
483620
484−##### Semantics
621+Irregular form:
622+
623+None.
485624
486−A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines the output value of the gate.
625+#### AST
626+
627+```hoon
628+[%brsg p=spec q=hoon]
629+```
487630
488−##### Expands to
631+#### Expands to
489632
490633```hoon
491634^| |=(a b)
492635```
493636
494−##### Discussion
637+#### Semantics
638+
639+A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines
640+the output value of the gate.
641+
642+#### Discussion
495643
496644See [this discussion of core variance models](/docs/hoon/reference/advanced)
497645
498−##### Examples
646+#### Examples
499647
500648```
501−~zod:dojo> => ~ ^+(|~(a=@ *@) |=(a=* *@))
649+> => ~ ^+(|~(a=@ *@) |=(a=* *@))
502650<1|usl {a/@ $~}>
503651```
504652
505−### `|*` "bartar"
653+---
654+
655+## `|*` "bartar"
506656
507657Produce a wet gate (one-armed core with sample).
508658
509−##### Syntax
659+#### Syntax
660+
661+Two arguments, fixed.
510662
511−Regular:
663+Tall form:
512664
513665```hoon
514−|* a=spec b=hoon
666+|* a b
515667```
516668
517−AST:
669+Wide form:
518670
671+```hoon
672+|*(a b)
519673```
520−[%brtr p=spec q=hoon]
521−```
522674
523−##### Semantics
675+Irregular form:
676+
677+None.
524678
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.
679+#### AST
680+
681+```hoon
682+[%brtr p=spec q=hoon]
683+```
527684
528−##### Expands to
685+#### Expands to
529686
530687```hoon
531688=| a
@@ -535,14 +692,19 @@ is a Hoon expression that determines the output value of the gate.
535692--
536693```
537694
538−##### Discussion
695+#### Semantics
696+
697+A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b` is
698+a Hoon expression that determines the output value of the gate.
699+
700+#### Discussion
539701
540702In a normal (dry) gate, your argument is converted into the
541−sample type. In a generic (wet) gate, your argument type
703+sample type. In a generic (wet) gate, your argument type
542704passes through the function, rather as if it were a macro (there
543705is still only one copy of the code, however).
544706
545−Genericity is a powerful and dangerous tool. Use wet gates only if
707+Genericity is a powerful and dangerous tool. Use wet gates only if
546708you know what you're doing.
547709
548710Just as with a [gate](#bartis), we can recurse back into a wet gate
@@ -553,50 +715,59 @@ with `$()`.
553715`|*` can be used to make wet gates that produce structures, but this usage is
554716discouraged in favor of `|$`.
555717
556−##### Examples
718+#### Examples
557719
558720Wet and dry gates in a nutshell:
559721
560722```
561−~zod:dojo> =foo |=([a=* b=*] [b a])
723+> =foo |=([a=* b=*] [b a])
562724
563−~zod:dojo> =bar |*([a=* b=*] [b a])
725+> =bar |*([a=* b=*] [b a])
564726
565−~zod:dojo> (foo %cat %dog)
727+> (foo %cat %dog)
566728[6.778.724 7.627.107]
567729
568−~zod:dojo> (bar %cat %dog)
730+> (bar %cat %dog)
569731[%dog %cat]
570732```
571733
572734The dry gate does not preserve the type of `a` and `b`; the wet
573735gate does.
574736
575−### `|=` "bartis"
737+---
738+
739+## `|=` "bartis"
576740
577741Produce a gate (a one-armed core with a sample).
578742
579−##### Syntax
743+#### Syntax
744+
745+Two arguments, fixed.
580746
581−Regular:
747+Tall form:
582748
583749```hoon
584−|= a=spec b=hoon
750+|= a
751+b
585752```
586753
587−AST:
754+Wide form:
588755
589−```
590−[%brts p=spec q=hoon]
756+```hoon
757+|=(a b)
591758```
592759
593−##### Definition
760+Irregular form:
594761
595−The product of a `|=` expression is a dry **gate**, i.e., a Hoon function.
762+None.
596763
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.
764+#### AST
765+
766+```hoon
767+[%brts p=spec q=hoon]
768+```
598769
599−##### Expands to
770+#### Expands to
600771
601772```hoon
602773=| a=spec
@@ -604,7 +775,15 @@ The product of a `|=` expression is a dry **gate**, i.e., a Hoon function.
604775--
605776```
606777
607−##### Discussion
778+#### Definition
779+
780+The product of a `|=` expression is a dry **gate**, i.e., a Hoon function.
781+
782+`p` defines the gate sample type -- i.e., the input value type -- and usually
783+includes a sample name assignment (e.g., `a=@`). `q` is an expression that
784+determines the output value of the gate.
785+
786+#### Discussion
608787
609788Dry gates are used for the vast majority of ordinary functions in Hoon.
610789
@@ -612,33 +791,38 @@ A gate is a core with one arm named `$`, so we can recurse back into it with `$(
612791
613792> `$(...)` expands to `%=($ ...)` (["centis"](/docs/hoon/reference/rune/cen#centis)).
614793
615−##### Examples
794+#### Examples
616795
617796A trivial gate:
618797
619798```
620−~zod:dojo> =foo |=(a=@ +(a))
799+> =foo |=(a=@ +(a))
621800
622−~zod:dojo> (foo 20)
801+> (foo 20)
62380221
624803```
625804
626805A slightly less trivial gate:
627806
628807```
629−~zod:dojo> =foo |= [a=@ b=@]
630− (add a b)
631−~zod:dojo> (foo 30 400)
808+> =foo |= [a=@ b=@]
809+ (add a b)
810+
811+> (foo 30 400)
632812430
633813```
634814
635−### `|@` "barpat"
815+---
816+
817+## `|@` "barpat"
636818
637819Produce a 'wet' core `[battery payload]`.
638820
639−##### Syntax
821+#### Syntax
640822
641−Regular:
823+Arguments: a variable number of `+`-family expressions.
824+
825+Tall form:
642826
643827```hoon
644828|@
@@ -651,58 +835,86 @@ Regular:
651835
652836Note: The `++` rune may be replaced with any other rune in the `+` family.
653837
654−AST:
838+Wide form:
655839
656−```
840+None.
841+
842+Irregular form:
843+
844+None.
845+
846+#### AST
847+
848+```hoon
657849[%brpt p=(unit term) q=(map term tome)]
658850```
659851
660−##### Semantics
852+#### Semantics
853+
854+A `|@` expression produces a 'wet' core whose payload is the expression's
855+subject. The various arms in the battery are each named (`a`, `c`, and `e`
856+above) and defined explicitly with a Hoon expression (with `b`, `d`, and `f`
857+above).
661858
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).
859+#### Discussion
663860
664−##### Discussion
861+The `|@` rune is just like the `|%` rune except that instead of producing a
862+'dry' core, it produces a 'wet' one. This allows for type polymorphism of its
863+arms, using 'genericity'. See [Advanced types](/docs/hoon/reference/advanced).
665864
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).
865+---
667866
668−### `|?` "barwut"
867+## `|?` "barwut"
669868
670869Produce a lead trap.
671870
672−##### Syntax
871+#### Syntax
673872
674−Regular:
873+One argument, fixed.
874+
875+Tall form:
675876
676877```hoon
677−|? a=hoon
878+|? a
678879```
679880
680−AST:
881+Wide form:
681882
682−```
683−[%brwt p=hoon]
883+```hoon
884+|?(a)
684885```
685886
686−##### Semantics
887+Irregular form:
687888
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.
889+None.
689890
690−##### Expands to
891+#### AST
892+
893+```hoon
894+[%brwt p=hoon]
895+```
896+
897+#### Expands to
691898
692899```hoon
693900^? |. a
694901```
695902
696−##### Discussion
903+#### Semantics
904+
905+A `|?` expression produces a lead trap (i.e., a lead core with one arm named
906+`$`). `a` is a Hoon expression that defines what the `$` arm does.
907+
908+#### Discussion
697909
698910See this [discussion of the core variance model](/docs/hoon/reference/advanced).
699911
700−##### Examples
912+#### Examples
701913
702914```
703−~zod:dojo> => ~ ^+ |?(%a) |.(%a)
915+> => ~ ^+ |?(%a) |.(%a)
704916<1?pqz $~>
705917
706−~zod:dojo> => ~ ^+ |?(%a) |.(%b)
918+> => ~ ^+ |?(%a) |.(%b)
707919nest-fail
708920```