@@ -8,12 +8,80 @@ Core expressions produce cores. A core is a cell of `[battery payload]`.
88The `battery` is code, a battery of Nock formulas. The `payload` is the data
99needed to run those formulas correctly.
1010
11−Four core runes (`|=`, `|.`, `|-`, and `|*`) produce a
12−core with a single arm, named `$`. We can recompute this arm
13−with changes, which useful for recursion among other things:
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.
1414
1515## Runes
1616
17+### |$ "barbuc"
18+
19+Declares a mold builder wet gate with one or more molds as its
20+sample.
21+
22+##### Syntax
23+
24+Regular:
25+```hoon
26+|$ a=(lest term) b=spec
27+```
28+
29+AST:
30+```hoon
31+[%brbs sample=(lest term) body=spec]
32+```
33+
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
42+
43+```hoon
44+|$ [a b]
45+body
46+```
47+becomes
48+```hoon
49+|* [a=$~(* $-(* *)) b=$~(* $-(* *))]
50+^:
51+body
52+```
53+
54+##### Discussion
55+
56+A mold builder is a wet gate from one or more molds to a mold. A mold is a
57+function from nouns to nouns with types that may be partial, is always
58+idempotent, and usually the identity function on the noun itself.
59+
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).
65+
66+Like other single-arm cores, the arm for `|$` is named `$` and this can be used to
67+define recursive structures. Note however that Hoon is evaluated eagerly, and so
68+infinite structures are not permitted.
69+
70+Proper style for `|$` is to enclose the first argument with brackets, even if it
71+is 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`.
73+
74+##### Examples
75+
76+```
77+~zod:dojo> =foo |$([a b] [b a])
78+
79+~zod:dojo> =bar (foo [@ @tas])
80+
81+~zod:dojo> (bar %cat 3)
82+[%cat 3]
83+```
84+
1785### `|_` "barcab"
1886
1987Produce a **door** (a core with a sample).
@@ -230,7 +298,7 @@ AST:
230298[%brdt p=hoon]
231299```
232300
233−Semantics:
301+##### Semantics
234302
235303A `|.` 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.
236304
@@ -454,7 +522,8 @@ AST:
454522
455523##### Semantics
456524
457−A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b` is a Hoon expression that determines the output value of the gate.
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.
458527
459528##### Expands to
460529
@@ -481,6 +550,9 @@ with `$()`.
481550
482551> `$(...)` expands to `%=($ ...)` (["centis"](@/docs/reference/hoon-expressions/rune/cen.md#centis)).
483552
553+`|*` can be used to make wet gates that produce structures, but this usage is
554+discouraged in favor of `|$`.
555+
484556##### Examples
485557
486558Wet and dry gates in a nutshell: