@@ -8,12 +8,80 @@ Core expressions produce cores. A core is a cell of `[battery payload]`.
8The `battery` is code, a battery of Nock formulas. The `payload` is the data
8The `battery` is code, a battery of Nock formulas. The `payload` is the data
9needed to run those formulas correctly.
9needed to run those formulas correctly.
11−Four core runes (`|=`, `|.`, `|-`, and `|*`) produce a
11+Five core runes (`|=`, `|.`, `|-`, `|*`, and `|$`) produce a
12−core with a single arm, named `$`. We can recompute this arm
12+core with a single arm, named `$`. As with all arms, we can recompute `$``
13−with changes, which useful for recursion among other things:
13+with changes, which is useful for recursion among other things.
19+Declares a mold builder wet gate with one or more molds as its
26+|$ a=(lest term) b=spec
31+[%brbs sample=(lest term) body=spec]
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`.
49+|* [a=$~(* $-(* *)) b=$~(* $-(* *))]
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.
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).
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.
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`.
77+~zod:dojo> =foo |$([a b] [b a])
79+~zod:dojo> =bar (foo [@ @tas])
81+~zod:dojo> (bar %cat 3)
17### `|_` "barcab"
85### `|_` "barcab"
19Produce a **door** (a core with a sample).
87Produce a **door** (a core with a sample).
@@ -230,7 +298,7 @@ AST:
230[%brdt p=hoon]
298[%brdt p=hoon]
233−Semantics:
301+##### Semantics
235A `|.` 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.
303A `|.` 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.
@@ -454,7 +522,8 @@ AST:
455##### Semantics
523##### Semantics
525+A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b`
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.
526+is a Hoon expression that determines the output value of the gate.
459##### Expands to
528##### Expands to
@@ -481,6 +550,9 @@ with `$()`.
482> `$(...)` expands to `%=($ ...)` (["centis"](@/docs/reference/hoon-expressions/rune/cen.md#centis)).
551> `$(...)` expands to `%=($ ...)` (["centis"](@/docs/reference/hoon-expressions/rune/cen.md#centis)).
553+`|*` can be used to make wet gates that produce structures, but this usage is
554+discouraged in favor of `|$`.
484##### Examples
556##### Examples
486Wet and dry gates in a nutshell:
558Wet and dry gates in a nutshell: