@@ -56,12 +56,26 @@ Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
57`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
57`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
59−##### Expands to
59+##### Syntax
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.
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
67=/ foo ;;(a x)
81=/ foo ;;(a x)
@@ -69,28 +83,13 @@ expands to
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.
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.
87−For example, the elements of a `set` are treated as being
86+For example, the elements of a `set` are treated as being unordered, but the
88−unordered, but the values will necessarily possess an order by where they are in
87+values will necessarily possess an order by where they are in the memory. Thus
89−the memory. Thus if every `set` is stored using the same order scheme then faster algorithms involving `set`s may be
88+if every `set` is stored using the same order scheme then faster algorithms
90−written. Furthermore, if you just place elements in the `set` randomly, it may
89+involving `set`s may be written. Furthermore, if you just place elements in the
91−be mistreated by algorithms already in place that are expecting a certain order.
90+`set` randomly, it may be mistreated by algorithms already in place that are
92−This is not the same thing as casting - it is forcing a
91+expecting a certain order. This is not the same thing as casting - it is forcing
93−type to have a more specific set of values than its mold would suggest. This
92+a type to have a more specific set of values than its mold would suggest. This
94rune should rarely be used, but it is extremely important when it is.
93rune should rarely be used, but it is extremely important when it is.
96##### Examples
95##### Examples