@@ -56,12 +56,26 @@ Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
5656
5757`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
5858
59−##### Expands to
59+##### Syntax
60+
61+Regular: **2-fixed**
62+
63+##### Discussion
64+
65+`$|` is used for validation of values at a finer level than that of types.
66+Recall that a given value of `type` can be equivalently defined by more than one
67+`spec`. For performance reasons, it may be beneficial to restrict oneself to
68+values of a given type that adhere to an abstract syntax tree specified by some
69+subset of those `spec`s that may be used to define a given type.
70+
71+`$|` takes two arguments: a structure `a` and a gate `b` that produces a `flag`
72+that is used to validate values produced by the mold generated by `a` at
73+runtime. `$|(a b)` is a gate that takes in a noun `x` and first pins the product
74+of clamming `a` with `x`, call this `foo`. Then it calls `b` on `foo`. It
75+asserts that the product of `(b foo)` is `&`, and then produces `foo`. This is
76+equivalent to the following (which is not how `$|` is actually defined but has
77+the same behavior):
6078
61−```hoon
62−$|(a b)
63−```
64−expands to
6579```hoon
6680|= x=*
6781=/ foo ;;(a x)
@@ -69,28 +83,13 @@ expands to
6983foo
7084```
7185
72−##### Syntax
73−
74−Regular: **2-fixed**
75−
76−##### Discussion
77−
78−`$|` takes two arguments, a mold and a gate that produces a `flag` or loobean that is used to validate the structure produced by the mold to ensure that the noun
79−has a certain shape. It crashes if the input fails the validation test. Else it
80−produces a mold-gate that does the following.
81−
82−`$|(a b)` is a gate that takes in a noun `x` and first pins the product of
83−clamming `a` with `x`, call this `foo`. Then it calls `b` on `foo`. It asserts
84−that the product of `(b foo)` is `&`, and then produces `foo`. This sequence of
85−events can be seen from the Expands To section above.
86−
87−For example, the elements of a `set` are treated as being
88−unordered, but the values will necessarily possess an order by where they are in
89−the memory. Thus if every `set` is stored using the same order scheme then faster algorithms involving `set`s may be
90−written. Furthermore, if you just place elements in the `set` randomly, it may
91−be mistreated by algorithms already in place that are expecting a certain order.
92−This is not the same thing as casting - it is forcing a
93−type to have a more specific set of values than its mold would suggest. This
86+For example, the elements of a `set` are treated as being unordered, but the
87+values will necessarily possess an order by where they are in the memory. Thus
88+if every `set` is stored using the same order scheme then faster algorithms
89+involving `set`s may be written. Furthermore, if you just place elements in the
90+`set` randomly, it may be mistreated by algorithms already in place that are
91+expecting a certain order. This is not the same thing as casting - it is forcing
92+a type to have a more specific set of values than its mold would suggest. This
9493rune should rarely be used, but it is extremely important when it is.
9594
9695##### Examples