@@ -7,9 +7,8 @@ aliases = ["docs/reference/hoon-expressions/rune/buc/"]
7The `$` family of runes is used for defining custom types. Strictly speaking,
7The `$` family of runes is used for defining custom types. Strictly speaking,
8these runes are used to produce 'structures'. A structure is a compile-time
8these runes are used to produce 'structures'. A structure is a compile-time
9value that at runtime can be converted to either an example value (sometimes
9value 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,
10+called a 'bunt' value) for its corresponding type, or to 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.
11+among other things. A mold is used as a data validator.
14## Overview
13## Overview
@@ -22,10 +21,10 @@ x)))`, it's a normalizer and can be used as a mold.
22statically, so we can't actually tell if a mold matches this
21statically, so we can't actually tell if a mold matches this
23definition perfectly. This is not actually a problem.)
22definition perfectly. This is not actually a problem.)
25−Validation, though very
24+Validation (done with [`$|`](#bucbar), though very important, is a rare use
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
25+case. Except for direct raw input, it's generally a faux pas to rectify nouns at runtime -- or even
28−in userspace.
26+in userspace. Nonetheless they are sometimes utilized for structures that will
27+be faster to use if they satisfy some validating gate.
30In any case, since molds are just functions, we can use
29In any case, since molds are just functions, we can use
31functional programming to assemble interesting molds. For
30functional programming to assemble interesting molds. For
@@ -55,7 +54,79 @@ Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
56### $| "bucbar"
55### $| "bucbar"
58−`[%bsbr p=spec q=hoon]` Something about validating...
57+`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
61+Still need help with this. From hoon.hoon:
67+ :: push the raw product
69+ :+ %tsls relative(mod p.mod)
76+ [%cnhp [%tsbn $/3 q.mod] $/2]
77+ :: produce verified product
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.
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.
103+~zod:dojo> =foo $| (list @)
104+ |=(a=(list) (lth (lent a) 4))
106+This creates a structure `foo` whose values are `list`s with length less than 4.
111+ford: %ride failed to execute:
115+The definition of `+set` in `hoon.hoon` is the following:
120+ |=(a=(tree) ~(apt in a))
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'.
61### $_ "buccab"
132### $_ "buccab"