@@ -5,7 +5,7 @@ template = "doc.html"
5aliases = ["docs/reference/hoon-expressions/rune/buc/"]
5aliases = ["docs/reference/hoon-expressions/rune/buc/"]
8−The `$` family of runes is used for defining custom types. Strictly speaking,
8+The `$` family of runes is used for defining custom types. Strictly speaking,
9these runes are used to produce `spec`s, which we call 'structures'.
9these runes are used to produce `spec`s, which we call 'structures'.
11## Overview
11## Overview
@@ -46,35 +46,45 @@ it's generally a faux pas to validate structure at runtime -- or even in userspa
46Nonetheless they are sometimes utilized for types that will be more performant
46Nonetheless they are sometimes utilized for types that will be more performant
47if they satisfy some validating gate.
47if they satisfy some validating gate.
49−## Base Structures
49+---
51−`[%base p=$@(?(%noun %cell %flag %null %void) [%atom p=aura])]`: trivial structures (types).
51+## `$|` "bucbar"
53−##### Produces
53+Structure that satisfies a validator.
55−A structure is a noun produced, usually at compile-time, for use in tracking types. In most cases, structures don't exist in the runtime semantics.
57−A structure for the base in `p`. `%noun` is any noun; `%atom` is any
58−atom; `%cell` is a cell of nouns; `%flag` is a loobean, ``?(`@f`0
59−`@f`1)``. `%null` is zero with aura `@n`, `%void` is the empty set.
61−##### Syntax
55+#### Syntax
63−Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
64−`%bean`, `~` makes `%null`, `@aura` makes atom `aura`.
71−`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
73−##### Syntax
60+<tr><th>Form</th><th>Syntax</th></tr>
78+<tr><td>Irregular</td><td>None.</td></tr>
75−Regular: **2-fixed**
83+```hoon
77−##### Discussion
87+#### Discussion
79`$|` is used for validation of values at a finer level than that of types.
89`$|` is used for validation of values at a finer level than that of types.
80Recall that a given value of `type` can be equivalently defined by more than one
90Recall that a given value of `type` can be equivalently defined by more than one
@@ -106,316 +116,584 @@ expecting a certain order. This is not the same thing as casting - it is forcing
106a type to have a more specific set of values than its mold would suggest. This
116a type to have a more specific set of values than its mold would suggest. This
107rune should rarely be used, but it is extremely important when it is.
117rune should rarely be used, but it is extremely important when it is.
109−##### Examples
119+#### Examples
112−~zod:dojo> =foo $| (list @)
122+> =foo $| (list @)
113− |=(a=(list) (lth (lent a) 4))
123+ |=(a=(list) (lth (lent a) 4))
115This creates a structure `foo` whose values are `list`s with length less than 4.
126This creates a structure `foo` whose values are `list`s with length less than 4.
117> (foo ~[1 2 3])
129> (foo ~[1 2 3])
119> (foo ~[1 2 3 4])
132> (foo ~[1 2 3 4])
120ford: %ride failed to execute:
133ford: %ride failed to execute:
124The definition of `+set` in `hoon.hoon` is the following:
136The definition of `+set` in `hoon.hoon` is the following:
127− |$ [item] :: set
140+ |$ [item]
128 $| (tree item)
141 $| (tree item)
129− |=(a=(tree) ~(apt in a))
142+ |=(a=(tree) ?:(=(~ a) & ~(apt in a)))
131−Here [`|$`](/docs/hoon/reference/rune/bar#barbuc) is used to
132−define a mold builder that takes in a mold (given the face `item`) and creates a
133−structure consisting of a `tree` of `item`s with `$|` that is validated with the
134−gate `|=(a=(tree) ~(apt in a))`. `in` is a door in `hoon.hoon` with functions
135−for handling `set`s, and `apt` is an arm in that door that checks that the
136−values in the `tree` are arranged in the particular way that `set`s are arranged
137−in Hoon, namely 'ascending `+mug` hash order'.
145+Here [`|$`](/docs/hoon/reference/rune/bar#barbuc) is used to define a mold
146+builder that takes in a mold (given the face `item`) and creates a structure
147+consisting of a `tree` of `item`s with `$|` that is validated with the gate
148+`|=(a=(tree) ?:(=(~ a) & ~(apt in a)))`. `in` is a door in `hoon.hoon` with
149+functions for handling `set`s, and `apt` is an arm in that door that checks that
150+the values in the `tree` are arranged in the particular way that `set`s are
151+arranged in Hoon, namely 'ascending `+mug` hash order'.
140−### `$_` "buccab"
155+## `$_` "buccab"
142−`[%bscb p=hoon]`: structure that normalizes to an example.
157+Structure that normalizes to an example.
144−##### Expands to
161+One argument, fixed.
164+<tr><th>Form</th><th>Syntax</th></tr>
147−|=(* p)
194+[%bccb p=hoon]
150−##### Syntax
197+#### Expands to
152−Regular: **1-fixed**.
154−Irregular: `_foo` is `$_(foo)`.
199+```hoon
156−##### Discussion
203+#### Discussion
158−`$_` discards the sample it's supposedly normalizing
205+`$_` discards the sample it's supposedly normalizing and produces its
159−and produces its **example** instead.
206+**example** instead.
161−##### Examples
208+#### Examples
164−~zod:dojo> =foo $_([%foobaz %moobaz])
211+> =foo $_([%foobaz %moobaz])
166−~zod:dojo> (foo %foo %baz)
213+> (foo %foo %baz)
167[%foobaz %moobaz]
214[%foobaz %moobaz]
169−~zod:dojo> `foo`[%foobaz %moobaz]
216+> `foo`[%foobaz %moobaz]
170[%foobaz %moobaz]
217[%foobaz %moobaz]
172−~zod:dojo $:foo
219+> $:foo
173[%foobaz %moobaz]
220[%foobaz %moobaz]
176−### `$%` "buccen"
223+---
178−`[%bscn p=(list spec)]`: structure which recognizes a union tagged by head atom.
225+## `$%` "buccen"
180−##### Defaults to
227+Structure which recognizes a union tagged by head atom.
182−The default of the last item `i` in `p`. Crashes if `p` is empty.
229+#### Syntax
231+A variable number of arguments.
234+<tr><th>Form</th><th>Syntax</th></tr>
251+$%([%p1 ...] [%p2 ...] [%p3 ...] [%pn ...])
255+<tr><td>Irregular</td><td>None.</td></tr>
258+Each item may be an atom or (more commonly) a cell. The atom or head of the cell
259+_must_ be a constant (`%foo`, `%1`, `%.y`, etc).
264+[%bccn p=(list spec)]
184−##### Syntax
267+#### Defaults to
186−Regular form: **2-running**.
269+The default of the last item `i` in `p`. Crashes if `p` is empty.
188−##### Discussion
271+#### Discussion
190A `$%` is a tagged union, a common data model.
273A `$%` is a tagged union, a common data model.
192Make sure the last item in your `$%` terminates, or the default will
275Make sure the last item in your `$%` terminates, or the default will
193−be an infinite loop! Alteratively, you can use `$~` to define a custom
276+be an infinite loop! Alteratively, you can use `$~` to define a custom
194type default value.
277type default value.
196−##### Examples
279+#### Examples
199−~zod:dojo> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
282+> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
201−~zod:dojo> (foo [%foo 4 2])
284+> (foo [%foo 4 2])
202[%foo p=4 q=2]
285[%foo p=4 q=2]
204−~zod:dojo> (foo [%baz 37])
287+> (foo [%baz 37])
205[%baz p=37]
288[%baz p=37]
207−~zod:dojo> $:foo
290+> $:foo
208[%baz p=0]
291[%baz p=0]
211−### `$:` "buccol"
294+---
213−`[%bscl p=(list spec)]`: form a cell type.
296+## `$:` "buccol"
215−##### Normalizes to
298+Form a cell type.
217−The tuple the length of `p`, normalizing each item.
300+#### Syntax
219−##### Defaults to
302+A variable number of arguments.
305+<tr><th>Form</th><th>Syntax</th></tr>
327+<td>Irregular (noun mode)</td>
335+<td>Irregular (structure mode)</td>
221−The tuple the length of `p`.
346+```hoon
347+[%bccl p=(list spec)]
223−##### Syntax
352+The tuple the length of `p`, normalizing each item.
225−Regular: **running**.
354+#### Defaults to
227−Irregular (noun mode): `,[a b c]` is `$:(a b c)`.
356+The tuple the length of `p`.
228−Irregular (structure mode): `[a b c]` is `$:(a b c)`.
230−##### Examples
358+#### Examples
233−~zod:dojo> =foo $:(p=@ud q=@tas)
361+> =foo $:(p=@ud q=@tas)
235−~zod:dojo> (foo 33 %foo)
363+> (foo 33 %foo)
236[p=33 q=%foo]
364[p=33 q=%foo]
238−~zod:dojo> `foo`[33 %foo]
366+> `foo`[33 %foo]
239[p=33 q=%foo]
367[p=33 q=%foo]
241−~zod:dojo> $:foo
369+> $:foo
242[p=0 q=%$]
370[p=0 q=%$]
246−### `$<` "bucgal"
375+## `$<` "bucgal"
248−`[%bsld p=spec q=spec]`: Filters a pre-existing mold to obtain a mold
377+Filters a pre-existing mold to obtain a mold that excludes a particular
249−that excludes a particular structure.
378+structure.
251−##### Syntax
380+#### Syntax
253−Regular: **2-fixed**.
382+Two arguments, fixed.
385+<tr><th>Form</th><th>Syntax</th></tr>
403+<tr><td>Irregular</td><td>None.</td></tr>
409+[%bcgl p=spec q=spec]
255−##### Discussion
412+#### Discussion
257This can be used to obtain type(s) from a list of types `q` that do not satisfy a
414This can be used to obtain type(s) from a list of types `q` that do not satisfy a
258requirement given by `p`.
415requirement given by `p`.
260−##### Examples
417+#### Examples
263−~zod:dojo> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
420+> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
265−~zod:dojo> =m $<(%bar foo)
422+> =m $<(%bar foo)
267−~zod:dojo> (m [%bar 2 4])
424+> (m [%bar 2 4])
268ford: %ride failed to execute:
425ford: %ride failed to execute:
270−~zod:dojo> (m [%baz 2])
427+> (m [%baz 2])
271[%baz p=2]
428[%baz p=2]
273−~zod:dojo> ;;($<(%foo [@tas *]) [%foo 1])
430+> ;;($<(%foo [@tas *]) [%foo 1])
274ford: %ride failed to execute:
431ford: %ride failed to execute:
276−~zod:dojo> ;;($<(%foo [@tas *]) [%bar 1])
433+> ;;($<(%foo [@tas *]) [%bar 1])
281−### `$>` "bucgar"
439+## `$>` "bucgar"
283−`[%bsbn p=spec q=spec]`: Filters a mold to obtain a new mold
284−matching a particular structure.
441+Filters a mold to obtain a new mold matching a particular structure.
286−##### Syntax
443+#### Syntax
288−Regular: **2-fixed**.
445+Two arguments, fixed.
448+<tr><th>Form</th><th>Syntax</th></tr>
466+<tr><td>Irregular</td><td>None.</td></tr>
472+[%bcgr p=spec q=spec]
290−##### Discussion
475+#### Discussion
292This can be used to obtain type(s) from a list of types `q` that satisfy a
477This can be used to obtain type(s) from a list of types `q` that satisfy a
293requirement given by `p`.
478requirement given by `p`.
295−##### Examples
480+#### Examples
297Examples with `$%`:
482Examples with `$%`:
299−~zod:dojo> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
485+> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
301−~zod:dojo> =m $>(%bar foo)
487+> =m $>(%bar foo)
303−~zod:dojo> (m [%bar 2 4])
489+> (m [%bar 2 4])
304[%bar p=2 q=4]
490[%bar p=2 q=4]
306−>~zod:dojo> (m [%baz 2])
492+> (m [%baz 2])
307ford: %ride failed to execute:
493ford: %ride failed to execute:
310Examples with `;;`:
496Examples with `;;`:
312−~zod:dojo> ;;([@tas *] [%foo 1])
499+> ;;([@tas *] [%foo 1])
315−~zod:dojo> ;;([@tas *] [%bar 1])
502+> ;;([@tas *] [%bar 1])
318−~zod:dojo> ;;($>(%foo [@tas *]) [%foo 1])
505+> ;;($>(%foo [@tas *]) [%foo 1])
321−~zod:dojo> ;;($>(%foo [@tas *]) [%bar 1])
508+> ;;($>(%foo [@tas *]) [%bar 1])
322ford: %ride failed to execute:
509ford: %ride failed to execute:
326−### `$-` "buchep"
516+Structure that normalizes to an example gate.
328−`[%bshp p=spec q=spec]`: structure that normalizes to an example gate.
518+#### AST
521+[%bchp p=spec q=spec]
330−##### Expands to
524+#### Expands to
337−##### Syntax
531+#### Syntax
533+Two arguments, fixed.
339−Regular: **2-fixed**.
535+<table>
536+<tr><th>Form</th><th>Syntax</th></tr>
554+<tr><td>Irregular</td><td>None.</td></tr>
341−##### Discussion
557+`p` is the type the gate takes and `q` is the type the gate produces.
343−Since a `$-` reduces to a [`$_`](#buccab), it is not useful for normalizing, just for typechecking. In particular, the existence of `$-`s does **not** let us send gates or other cores over the network!
559+#### Discussion
561+Since a `$-` reduces to a [`$_`](#buccab), it is not useful for normalizing, just for typechecking. In particular, the existence of `$-`s does **not** let us send gates or other cores over the network!
345−##### Examples
563+#### Examples
348−~zod:dojo> =foo $-(%foo %baz)
566+> =foo $-(%foo %baz)
350−~zod:dojo> ($:foo %foo)
568+> ($:foo %foo)
576+Structure which normalizes a union tagged by head depth (cell).
355−### `$^` "bucket"
580+Two arguments, fixed.
583+<tr><th>Form</th><th>Syntax</th></tr>
601+<tr><td>Irregular</td><td>None.</td></tr>
357−`[%bskt p=spec q=spec]`: structure which normalizes a union tagged by head depth (cell).
606+```hoon
607+[%bckt p=spec q=spec]
359−##### Normalizes to
610+#### Normalizes to
361Default, if the sample is an atom; `p`, if the head of the sample
612Default, if the sample is an atom; `p`, if the head of the sample
362is an atom; `q` otherwise.
613is an atom; `q` otherwise.
364−##### Defaults to
615+#### Defaults to
366The default of `p`.
617The default of `p`.
370−Regular: **2-fixed**.
372−##### Examples
619+#### Examples
375−~zod:dojo> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
622+> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
377−~zod:dojo> =b $^([a a] a)
624+> =b $^([a a] a)
379−~zod:dojo> (b [[%baz 33] [%foo 19 22]])
626+> (b [[%baz 33] [%foo 19 22]])
380[[%baz p=33] [%foo p=19 q=22]]
627[[%baz p=33] [%foo p=19 q=22]]
382−~zod:dojo> (b [%foo 19 22])
629+> (b [%foo 19 22])
383[%foo p=19 q=22]
630[%foo p=19 q=22]
385−~zod:dojo> $:b
632+> $:b
386[%baz p=0]
633[%baz p=0]
389−### $& "bucpam"
636+---
391−`[%bspd p=spec q=hoon]`: repair a value of a tagged union type
638+## $& "bucpam"
393−##### Syntax
640+Repair a value of a tagged union type.
395−Regular: **2-fixed**.
642+#### Syntax
644+Two arguments, fixed.
647+<tr><th>Form</th><th>Syntax</th></tr>
665+<tr><td>Irregular</td><td>None.</td></tr>
398$&(combined-mold=spec normalizing-gate=hoon)
669$&(combined-mold=spec normalizing-gate=hoon)
400−Here `combined-mold` is a tagged union type (typically made with `$%`) and `normalizing-gate` is a
401−gate which accepts values of `combined-mold` and normalizes them to be of one particular type
672+Here `combined-mold` is a tagged union type (typically made with `$%`) and
673+`normalizing-gate` is a gate which accepts values of `combined-mold` and
674+normalizes them to be of one particular type in `combined-mold`.
679+[%bcpm p=spec q=hoon]
404−##### Normalizes to
682+#### Normalizes to
406The product of the normalizing gate and sample.
684The product of the normalizing gate and sample.
408−##### Defaults to
686+#### Defaults to
410The default of the last type listed in `p`, normalized with the normalizing gate.
688The default of the last type listed in `p`, normalized with the normalizing gate.
412−##### Discussion
690+#### Discussion
414This rune is used to "upgrade" or "repair" values of a structure, typically from
692This rune is used to "upgrade" or "repair" values of a structure, typically from
415−an old version to a new version. For example, this may happen when migrating state after
693+an old version to a new version. For example, this may happen when migrating
416−updating an app.
694+state after updating an app.
418−##### Examples
696+#### Examples
421+$ old [%0 @]
699+$ old [%0 @]
@@ -423,39 +701,69 @@ updating an app.
423+$ combined $%(old new)
701+$ combined $%(old new)
424+$ adapting $&(combined |=(?-(-.a %0 [%1 1 +.a], %1 a)))
702+$ adapting $&(combined |=(?-(-.a %0 [%1 1 +.a], %1 a)))
426Here `adapting` is a structure that bunts to `[%1 ^]` but also normalizes from
705Here `adapting` is a structure that bunts to `[%1 ^]` but also normalizes from
427`[%0 @]` if called on such a noun.
706`[%0 @]` if called on such a noun.
430−### `$~` "bucsig"
710+## `$~` "bucsig"
432−`[%bssg p=hoon q=spec]`: define a custom type default value
434−##### Product
712+Define a custom type default value.
436−Creates a structure (custom type) just like `q`, except its default value is `p`.
714+#### Syntax
438−##### Defaults to
716+Two arguments, fixed.
719+<tr><th>Form</th><th>Syntax</th></tr>
737+<tr><td>Irregular</td><td>None.</td></tr>
740+`p` defines the default value, and `q` defines everything else about the
440−The product of `p`.
745+```hoon
746+[%bcsg p=hoon q=spec]
442−##### Syntax
749+#### Product
444−Regular: **2-fixed**.
751+Creates a structure (custom type) just like `q`, except its default value is `p`.
446−```hoon
753+#### Defaults to
450−`p` defines the default value, and `q` defines everything else about the structure.
755+The product of `p`.
452−##### Discussion
757+#### Discussion
454−You should make sure that the product type of `p` nests under `q`. You can check the default value of some structure (custom type) `r` with `*r`. (See the [`^*` rune](/docs/hoon/reference/rune/ket#kettar).)
759+You should make sure that the product type of `p` nests under `q`. You can check
760+the default value of some structure (custom type) `r` with `*r`. (See the [`^*`
761+rune](/docs/hoon/reference/rune/ket#kettar).)
763+Do not confuse the `$~` rune with the constant type for null, `$~`. (The latter
456−Do not confuse the `$~` rune with the constant type for null, `$~`. (The latter uses older Hoon syntax that is still accepted. Preferably it would be `%~`.)
764+uses older Hoon syntax that is still accepted. Preferably it would be `%~`.)
458−##### Examples
766+#### Examples
460First, let's define a type without using `$~`:
768First, let's define a type without using `$~`:
@@ -491,116 +799,217 @@ Using `$~`:
491%default-value
799%default-value
494−### `$@` "bucpat"
802+---
496−`[%bsvt p=spec q=spec]`: structure which normalizes a union tagged by head depth (atom).
804+## `$@` "bucpat"
498−##### Normalizes to
806+Structure which normalizes a union tagged by head depth (atom).
500−`p`, if the sample is an atom; `q`, if the sample is a cell.
808+#### Syntax
502−##### Defaults to
810+Two arguments, fixed.
813+<tr><th>Form</th><th>Syntax</th></tr>
831+<tr><td>Irregular</td><td>None.</td></tr>
504−The default of `p`.
836+```hoon
837+[%bcpt p=spec q=spec]
506−#### Syntax
840+#### Normalizes to
842+`p`, if the sample is an atom; `q`, if the sample is a cell.
508−Regular: **2-fixed**.
844+#### Defaults to
510−Product: a structure which applies `p` if its sample is an atom,
846+The default of `p`.
511−`q` if its sample is a cell.
513−Regular form: **2-fixed**.
848+#### Produces
515−Example:
850+A structure which applies `p` if its sample is an atom, `q` if its sample is a
518−~zod:dojo> =a $@(%foo $:(p=%baz q=@ud))
856+> =a $@(%foo $:(p=%baz q=@ud))
520−~zod:dojo> (a %foo)
858+> (a %foo)
523−~zod:dojo> `a`[%baz 99]
861+> `a`[%baz 99]
524[p=%baz q=99]
862[p=%baz q=99]
526−~zod:dojo> $:a
864+> $:a
531−### `$=` "buctis"
872+Structure which wraps a face around another structure.
533−`[%bsts p=skin q=spec]`: structure which wraps a face around another structure.
874+#### Syntax
535−##### Expands to
876+Two arguments, fixed.
879+<tr><th>Form</th><th>Syntax</th></tr>
538−|= *
910+[%bcts p=skin q=spec]
542−##### Syntax
913+#### Expands to
544−Regular: **2-fixed**.
915+```hoon
546−Irregular (structure mode): `foo=baz` is `$=(foo baz)`.
917+^=(p %-(q +6))
548−##### Discussion
920+#### Discussion
550Note that the Hoon compiler is at least slightly clever about
922Note that the Hoon compiler is at least slightly clever about
551compiling structures, and almost never has to actually put in a gate
923compiling structures, and almost never has to actually put in a gate
552layer (as seen in the expansion above) to apply a `$=`.
924layer (as seen in the expansion above) to apply a `$=`.
554−##### Examples
926+#### Examples
557−~zod:dojo> =a $=(p %foo)
929+> =a $=(p %foo)
559−~zod:dojo> (a %foo)
931+> (a %foo)
562−~zod:dojo> (a %baz)
934+> (a %baz)
563ford: %ride failed to execute:
935ford: %ride failed to execute:
566−### `$?` "bucwut"
938+---
568−`[%bswt p=(list spec)]`: form a type from a union of other types.
940+## `$?` "bucwut"
570−##### Normalizes to
942+Form a type from a union of other types.
572−The first item in `p` which normalizes the sample to itself.
944+#### Syntax
574−Void, if `p` is empty.
946+Variable number of arguments.
949+<tr><th>Form</th><th>Syntax</th></tr>
983+[%bcwt p=(list spec)]
576−##### Defaults to
986+#### Normalizes to
578−The first item in `p`.
988+The last item in `p` which normalizes the sample to itself.
580−##### Syntax
990+Void, if `p` is empty.
582−Regular: **running**.
992+#### Defaults to
584−Irregular: `?(%foo %baz)` is `$?(%foo %baz)`.
994+The last item in `p`.
586−##### Discussion
996+#### Discussion
588−For a union of atoms, a `$?` is fine. For more complex nouns,
998+For a union of atoms, a `$?` is fine. For more complex nouns, always try to use
589−always try to use a [`$%`](#buccen), [`$@`](#bucpat) or
999+a [`$%`](#buccen), [`$@`](#bucpat) or [`$^`](#bucket), at least if you expect
590−[`$^`](#bucket), at least if you expect your structure to be used as a
1000+your structure to be used as a normalizer.
593−##### Examples
1002+#### Examples
596−~zod:dojo> =a ?(%foo %baz %baz)
1005+> =a ?(%foo %baz %baz)
598−~zod:dojo> (a %baz)
1007+> (a %baz)
601−~zod:dojo> (a [37 45])
1010+> (a [37 45])
602ford: %ride failed to execute:
1011ford: %ride failed to execute:
604−~zod:dojo> $:a
1013+> $:a