@@ -7,9 +7,8 @@ aliases = ["docs/reference/hoon-expressions/rune/buc/"]
77The `$` family of runes is used for defining custom types. Strictly speaking,
88these runes are used to produce 'structures'. A structure is a compile-time
99value that at runtime can be converted to either an example value (sometimes
10−called a 'bunt' value) for its corresponding type, or to a 'factory' (sometimes
11−called a 'mold'). An example value is used as a placeholder for sample values,
12−among other things. A factory/mold is used as a data validator.
10+called a 'bunt' value) for its corresponding type, or to a 'mold'. An example value is used as a placeholder for sample values,
11+among other things. A mold is used as a data validator.
1312
1413## Overview
1514
@@ -22,10 +21,10 @@ x)))`, it's a normalizer and can be used as a mold.
2221statically, so we can't actually tell if a mold matches this
2322definition perfectly. This is not actually a problem.)
2423
25−Validation, though very
26−important, is a rare use case. Except for direct raw input,
27−it's generally a faux pas to rectify nouns at runtime -- or even
28−in userspace.
24+Validation (done with [`$|`](#bucbar), though very important, is a rare use
25+case. Except for direct raw input, it's generally a faux pas to rectify nouns at runtime -- or even
26+in userspace. Nonetheless they are sometimes utilized for structures that will
27+be faster to use if they satisfy some validating gate.
2928
3029In any case, since molds are just functions, we can use
3130functional programming to assemble interesting molds. For
@@ -55,7 +54,79 @@ Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
5554
5655### $| "bucbar"
5756
58−`[%bsbr p=spec q=hoon]` Something about validating...
57+`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
58+
59+##### Expands to
60+
61+Still need help with this. From hoon.hoon:
62+```hoon
63+ :: verify, $|
64+ ::
65+ {$bsbr *}
66+ ^- hoon
67+ :: push the raw product
68+ ::
69+ :+ %tsls relative(mod p.mod)
70+ ^- hoon
71+ :: assert
72+ ::
73+ :+ %wtbn
74+ :: run the verifier
75+ ::
76+ [%cnhp [%tsbn $/3 q.mod] $/2]
77+ :: produce verified product
78+ ::
79+ $/2
80+```
81+
82+
83+##### Syntax
84+
85+Regular: **2-fixed**
86+
87+##### Discussion
88+
89+`$|` takes two arguments, a mold and a Hoon expression that is typically a gate
90+that is used to validate the structure produced by the mold to ensure that the noun
91+has a certain shape. It crashes if the input fails the validation test.
92+
93+For example, the elements of a `set` are treated as being
94+unordered, but the values will necessarily possess an order by where they are in
95+the memory. Thus if every `set` is stored using the same order scheme then faster algorithms involving `set`s may be
96+written. This is not the same thing as casting - it is forcing a
97+type to have a more specific set of values than its mold would suggest. This
98+rune should rarely be used, but it is extremely important when it is.
99+
100+##### Examples
101+
102+```
103+~zod:dojo> =foo $| (list @)
104+ |=(a=(list) (lth (lent a) 4))
105+```
106+This creates a structure `foo` whose values are `list`s with length less than 4.
107+```
108+> (foo ~[1 2 3])
109+~[1 2 3]
110+> (foo ~[1 2 3 4])
111+ford: %ride failed to execute:
112+```
113+
114+
115+The definition of `+set` in `hoon.hoon` is the following:
116+```hoon
117+++ set
118+ |$ [item] :: set
119+ $| (tree item)
120+ |=(a=(tree) ~(apt in a))
121+```
122+Here [`|$`](@/docs/reference/hoon-expressions/rune/bar.md#barbuc) is used to
123+define a mold builder that takes in a mold (given the face `item`) and creates a
124+structure consisting of a `tree` of `item`s with `$|` that is validated with the
125+gate `|=(a=(tree) ~(apt in a))`. `in` is a door in `hoon.hoon` with functions
126+for handling `set`s, and `apt` is an arm in that door that checks that the
127+values in the `tree` are arranged in the particular way that `set`s are arranged
128+in Hoon, namely 'ascending `+mug` hash order'.
129+
59130
60131
61132### $_ "buccab"