@@ -5,7 +5,7 @@ template = "doc.html"
55aliases = ["docs/reference/hoon-expressions/rune/buc/"]
66+++
77
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,
99these runes are used to produce `spec`s, which we call 'structures'.
1010
1111## Overview
@@ -46,35 +46,45 @@ it's generally a faux pas to validate structure at runtime -- or even in userspa
4646Nonetheless they are sometimes utilized for types that will be more performant
4747if they satisfy some validating gate.
4848
49−## Base Structures
49+---
5050
51−`[%base p=$@(?(%noun %cell %flag %null %void) [%atom p=aura])]`: trivial structures (types).
51+## `$|` "bucbar"
5252
53−##### Produces
53+Structure that satisfies a validator.
5454
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.
56−
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.
60−
61−##### Syntax
62−
63−Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
64−`%bean`, `~` makes `%null`, `@aura` makes atom `aura`.
65−
66−
67−## Runes
68−
69−### $| "bucbar"
70−
71−`[%bsbr p=spec q=hoon]`: structure that satisfies a validator.
55+#### Syntax
7256
73−##### Syntax
57+Two arguments, fixed.
58+
59+<table>
60+<tr><th>Form</th><th>Syntax</th></tr>
61+<tr>
62+<td>Tall</td>
63+<td>
64+<pre>
65+$| p
66+q
67+</pre>
68+</td>
69+</tr>
70+<tr>
71+<td>Wide</td>
72+<td>
73+<pre>
74+$|(p q)
75+</pre>
76+</td>
77+</tr>
78+<tr><td>Irregular</td><td>None.</td></tr>
79+</table>
80+
81+#### AST
7482
75−Regular: **2-fixed**
83+```hoon
84+[%bcbr p=spec q=hoon]
85+```
7686
77−##### Discussion
87+#### Discussion
7888
7989`$|` is used for validation of values at a finer level than that of types.
8090Recall 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
106116a type to have a more specific set of values than its mold would suggest. This
107117rune should rarely be used, but it is extremely important when it is.
108118
109−##### Examples
119+#### Examples
110120
111121```
112−~zod:dojo> =foo $| (list @)
113− |=(a=(list) (lth (lent a) 4))
122+> =foo $| (list @)
123+ |=(a=(list) (lth (lent a) 4))
114124```
125+
115126This creates a structure `foo` whose values are `list`s with length less than 4.
127+
116128```
117129> (foo ~[1 2 3])
118130~[1 2 3]
131+
119132> (foo ~[1 2 3 4])
120133ford: %ride failed to execute:
121134```
122135
123−
124136The definition of `+set` in `hoon.hoon` is the following:
137+
125138```hoon
126139++ set
127− |$ [item] :: set
140+ |$ [item]
128141 $| (tree item)
129− |=(a=(tree) ~(apt in a))
142+ |=(a=(tree) ?:(=(~ a) & ~(apt in a)))
130143```
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'.
138144
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'.
152+
153+---
139154
140−### `$_` "buccab"
155+## `$_` "buccab"
141156
142−`[%bscb p=hoon]`: structure that normalizes to an example.
157+Structure that normalizes to an example.
158+
159+#### Syntax
143160
144−##### Expands to
161+One argument, fixed.
162+
163+<table>
164+<tr><th>Form</th><th>Syntax</th></tr>
165+<tr>
166+<td>Tall</td>
167+<td>
168+<pre>
169+$_ p
170+</pre>
171+</td>
172+</tr>
173+<tr>
174+<td>Wide</td>
175+<td>
176+<pre>
177+$_(p)
178+</pre>
179+</td>
180+</tr>
181+<tr>
182+<td>Irregular</td>
183+<td>
184+<pre>
185+_p
186+</pre>
187+</td>
188+</tr>
189+</table>
190+
191+#### AST
145192
146193```hoon
147−|=(* p)
194+[%bccb p=hoon]
148195```
149196
150−##### Syntax
151−
152−Regular: **1-fixed**.
197+#### Expands to
153198
154−Irregular: `_foo` is `$_(foo)`.
199+```hoon
200+|=(* p)
201+```
155202
156−##### Discussion
203+#### Discussion
157204
158−`$_` discards the sample it's supposedly normalizing
159−and produces its **example** instead.
205+`$_` discards the sample it's supposedly normalizing and produces its
206+**example** instead.
160207
161−##### Examples
208+#### Examples
162209
163210```
164−~zod:dojo> =foo $_([%foobaz %moobaz])
211+> =foo $_([%foobaz %moobaz])
165212
166−~zod:dojo> (foo %foo %baz)
213+> (foo %foo %baz)
167214[%foobaz %moobaz]
168215
169−~zod:dojo> `foo`[%foobaz %moobaz]
216+> `foo`[%foobaz %moobaz]
170217[%foobaz %moobaz]
171218
172−~zod:dojo $:foo
219+> $:foo
173220[%foobaz %moobaz]
174221```
175222
176−### `$%` "buccen"
223+---
177224
178−`[%bscn p=(list spec)]`: structure which recognizes a union tagged by head atom.
225+## `$%` "buccen"
179226
180−##### Defaults to
227+Structure which recognizes a union tagged by head atom.
181228
182−The default of the last item `i` in `p`. Crashes if `p` is empty.
229+#### Syntax
230+
231+A variable number of arguments.
232+
233+<table>
234+<tr><th>Form</th><th>Syntax</th></tr>
235+<tr>
236+<td>Tall</td>
237+<td>
238+<pre>
239+$% [%p1 ...]
240+ [%p2 ...]
241+ [%p3 ...]
242+ [%pn ...]
243+==
244+</pre>
245+</td>
246+</tr>
247+<tr>
248+<td>Wide</td>
249+<td>
250+<pre>
251+$%([%p1 ...] [%p2 ...] [%p3 ...] [%pn ...])
252+</pre>
253+</td>
254+</tr>
255+<tr><td>Irregular</td><td>None.</td></tr>
256+</table>
257+
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).
260+
261+#### AST
262+
263+```hoon
264+[%bccn p=(list spec)]
265+```
183266
184−##### Syntax
267+#### Defaults to
185268
186−Regular form: **2-running**.
269+The default of the last item `i` in `p`. Crashes if `p` is empty.
187270
188−##### Discussion
271+#### Discussion
189272
190273A `$%` is a tagged union, a common data model.
191274
192275Make 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
194277type default value.
195278
196−##### Examples
279+#### Examples
197280
198281```
199−~zod:dojo> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
282+> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
200283
201−~zod:dojo> (foo [%foo 4 2])
284+> (foo [%foo 4 2])
202285[%foo p=4 q=2]
203286
204−~zod:dojo> (foo [%baz 37])
287+> (foo [%baz 37])
205288[%baz p=37]
206289
207−~zod:dojo> $:foo
290+> $:foo
208291[%baz p=0]
209292```
210293
211−### `$:` "buccol"
294+---
212295
213−`[%bscl p=(list spec)]`: form a cell type.
296+## `$:` "buccol"
214297
215−##### Normalizes to
298+Form a cell type.
216299
217−The tuple the length of `p`, normalizing each item.
300+#### Syntax
218301
219−##### Defaults to
302+A variable number of arguments.
303+
304+<table>
305+<tr><th>Form</th><th>Syntax</th></tr>
306+<tr>
307+<td>Tall</td>
308+<td>
309+<pre>
310+$: p1
311+ p2
312+ p3
313+ pn
314+==
315+</pre>
316+</td>
317+</tr>
318+<tr>
319+<td>Wide</td>
320+<td>
321+<pre>
322+$:(p1 p2 p3 pn)
323+</pre>
324+</td>
325+</tr>
326+<tr>
327+<td>Irregular (noun mode)</td>
328+<td>
329+<pre>
330+,[p1 p2 p3 pn]
331+</pre>
332+</td>
333+</tr>
334+<tr>
335+<td>Irregular (structure mode)</td>
336+<td>
337+<pre>
338+[p1 p2 p3 pn]
339+</pre>
340+</td>
341+</tr>
342+</table>
343+
344+#### AST
220345
221−The tuple the length of `p`.
346+```hoon
347+[%bccl p=(list spec)]
348+```
349+
350+#### Normalizes to
222351
223−##### Syntax
352+The tuple the length of `p`, normalizing each item.
224353
225−Regular: **running**.
354+#### Defaults to
226355
227−Irregular (noun mode): `,[a b c]` is `$:(a b c)`.
228−Irregular (structure mode): `[a b c]` is `$:(a b c)`.
356+The tuple the length of `p`.
229357
230−##### Examples
358+#### Examples
231359
232360```
233−~zod:dojo> =foo $:(p=@ud q=@tas)
361+> =foo $:(p=@ud q=@tas)
234362
235−~zod:dojo> (foo 33 %foo)
363+> (foo 33 %foo)
236364[p=33 q=%foo]
237365
238−~zod:dojo> `foo`[33 %foo]
366+> `foo`[33 %foo]
239367[p=33 q=%foo]
240368
241−~zod:dojo> $:foo
369+> $:foo
242370[p=0 q=%$]
243371```
244372
373+---
245374
246−### `$<` "bucgal"
375+## `$<` "bucgal"
247376
248−`[%bsld p=spec q=spec]`: Filters a pre-existing mold to obtain a mold
249−that excludes a particular structure.
377+Filters a pre-existing mold to obtain a mold that excludes a particular
378+structure.
250379
251−##### Syntax
380+#### Syntax
252381
253−Regular: **2-fixed**.
382+Two arguments, fixed.
383+
384+<table>
385+<tr><th>Form</th><th>Syntax</th></tr>
386+<tr>
387+<td>Tall</td>
388+<td>
389+<pre>
390+$< p
391+q
392+</pre>
393+</td>
394+</tr>
395+<tr>
396+<td>Wide</td>
397+<td>
398+<pre>
399+$<(p q)
400+</pre>
401+</td>
402+</tr>
403+<tr><td>Irregular</td><td>None.</td></tr>
404+</table>
405+
406+#### AST
254407
255−##### Discussion
408+```hoon
409+[%bcgl p=spec q=spec]
410+```
411+
412+#### Discussion
256413
257414This can be used to obtain type(s) from a list of types `q` that do not satisfy a
258415requirement given by `p`.
259416
260−##### Examples
417+#### Examples
261418
262419```
263−~zod:dojo> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
420+> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
264421
265−~zod:dojo> =m $<(%bar foo)
422+> =m $<(%bar foo)
266423
267−~zod:dojo> (m [%bar 2 4])
424+> (m [%bar 2 4])
268425ford: %ride failed to execute:
269426
270−~zod:dojo> (m [%baz 2])
427+> (m [%baz 2])
271428[%baz p=2]
272429
273−~zod:dojo> ;;($<(%foo [@tas *]) [%foo 1])
430+> ;;($<(%foo [@tas *]) [%foo 1])
274431ford: %ride failed to execute:
275432
276−~zod:dojo> ;;($<(%foo [@tas *]) [%bar 1])
433+> ;;($<(%foo [@tas *]) [%bar 1])
277434[%bar 1]
278− ```
435+```
279436
437+---
280438
281−### `$>` "bucgar"
439+## `$>` "bucgar"
282440
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.
285442
286−##### Syntax
443+#### Syntax
287444
288−Regular: **2-fixed**.
445+Two arguments, fixed.
446+
447+<table>
448+<tr><th>Form</th><th>Syntax</th></tr>
449+<tr>
450+<td>Tall</td>
451+<td>
452+<pre>
453+$> p
454+q
455+</pre>
456+</td>
457+</tr>
458+<tr>
459+<td>Wide</td>
460+<td>
461+<pre>
462+$>(p q)
463+</pre>
464+</td>
465+</tr>
466+<tr><td>Irregular</td><td>None.</td></tr>
467+</table>
468+
469+#### AST
289470
290−##### Discussion
471+```hoon
472+[%bcgr p=spec q=spec]
473+```
474+
475+#### Discussion
291476
292477This can be used to obtain type(s) from a list of types `q` that satisfy a
293478requirement given by `p`.
294479
295−##### Examples
480+#### Examples
296481
297482Examples with `$%`:
483+
298484```
299−~zod:dojo> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
485+> =foo $%([%bar p=@ud q=@ud] [%baz p=@ud])
300486
301−~zod:dojo> =m $>(%bar foo)
487+> =m $>(%bar foo)
302488
303−~zod:dojo> (m [%bar 2 4])
489+> (m [%bar 2 4])
304490[%bar p=2 q=4]
305491
306−>~zod:dojo> (m [%baz 2])
492+> (m [%baz 2])
307493ford: %ride failed to execute:
308494```
309495
310496Examples with `;;`:
497+
311498```
312−~zod:dojo> ;;([@tas *] [%foo 1])
499+> ;;([@tas *] [%foo 1])
313500[%foo 1]
314501
315−~zod:dojo> ;;([@tas *] [%bar 1])
502+> ;;([@tas *] [%bar 1])
316503[%bar 1]
317504
318−~zod:dojo> ;;($>(%foo [@tas *]) [%foo 1])
505+> ;;($>(%foo [@tas *]) [%foo 1])
319506[%foo 1]
320507
321−~zod:dojo> ;;($>(%foo [@tas *]) [%bar 1])
508+> ;;($>(%foo [@tas *]) [%bar 1])
322509ford: %ride failed to execute:
323− ```
510+```
511+
512+---
324513
514+## `$-` "buchep"
325515
326−### `$-` "buchep"
516+Structure that normalizes to an example gate.
327517
328−`[%bshp p=spec q=spec]`: structure that normalizes to an example gate.
518+#### AST
519+
520+```hoon
521+[%bchp p=spec q=spec]
522+```
329523
330−##### Expands to
524+#### Expands to
331525
332526```hoon
333527$_ ^|
334528|=(p $:q)
335529```
336530
337−##### Syntax
531+#### Syntax
532+
533+Two arguments, fixed.
338534
339−Regular: **2-fixed**.
535+<table>
536+<tr><th>Form</th><th>Syntax</th></tr>
537+<tr>
538+<td>Tall</td>
539+<td>
540+<pre>
541+$- p
542+q
543+</pre>
544+</td>
545+</tr>
546+<tr>
547+<td>Wide</td>
548+<td>
549+<pre>
550+$-(p q)
551+</pre>
552+</td>
553+</tr>
554+<tr><td>Irregular</td><td>None.</td></tr>
555+</table>
340556
341−##### Discussion
557+`p` is the type the gate takes and `q` is the type the gate produces.
342558
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
344560
345−##### Examples
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!
562+
563+#### Examples
346564
347565```
348−~zod:dojo> =foo $-(%foo %baz)
566+> =foo $-(%foo %baz)
349567
350−~zod:dojo> ($:foo %foo)
568+> ($:foo %foo)
351569%baz
352570```
353571
572+---
573+
574+## `$^` "bucket"
575+
576+Structure which normalizes a union tagged by head depth (cell).
577+
578+#### Syntax
354579
355−### `$^` "bucket"
580+Two arguments, fixed.
581+
582+<table>
583+<tr><th>Form</th><th>Syntax</th></tr>
584+<tr>
585+<td>Tall</td>
586+<td>
587+<pre>
588+$^ p
589+q
590+</pre>
591+</td>
592+</tr>
593+<tr>
594+<td>Wide</td>
595+<td>
596+<pre>
597+$^(p q)
598+</pre>
599+</td>
600+</tr>
601+<tr><td>Irregular</td><td>None.</td></tr>
602+</table>
603+
604+#### AST
356605
357−`[%bskt p=spec q=spec]`: structure which normalizes a union tagged by head depth (cell).
606+```hoon
607+[%bckt p=spec q=spec]
608+```
358609
359−##### Normalizes to
610+#### Normalizes to
360611
361612Default, if the sample is an atom; `p`, if the head of the sample
362613is an atom; `q` otherwise.
363614
364−##### Defaults to
615+#### Defaults to
365616
366617The default of `p`.
367618
368−##### Syntax
369−
370−Regular: **2-fixed**.
371−
372−##### Examples
619+#### Examples
373620
374621```
375−~zod:dojo> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
622+> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
376623
377−~zod:dojo> =b $^([a a] a)
624+> =b $^([a a] a)
378625
379−~zod:dojo> (b [[%baz 33] [%foo 19 22]])
626+> (b [[%baz 33] [%foo 19 22]])
380627[[%baz p=33] [%foo p=19 q=22]]
381628
382−~zod:dojo> (b [%foo 19 22])
629+> (b [%foo 19 22])
383630[%foo p=19 q=22]
384631
385−~zod:dojo> $:b
632+> $:b
386633[%baz p=0]
387634```
388635
389−### $& "bucpam"
636+---
390637
391−`[%bspd p=spec q=hoon]`: repair a value of a tagged union type
638+## $& "bucpam"
392639
393−##### Syntax
640+Repair a value of a tagged union type.
394641
395−Regular: **2-fixed**.
642+#### Syntax
643+
644+Two arguments, fixed.
645+
646+<table>
647+<tr><th>Form</th><th>Syntax</th></tr>
648+<tr>
649+<td>Tall</td>
650+<td>
651+<pre>
652+$& p
653+q
654+</pre>
655+</td>
656+</tr>
657+<tr>
658+<td>Wide</td>
659+<td>
660+<pre>
661+$&(p q)
662+</pre>
663+</td>
664+</tr>
665+<tr><td>Irregular</td><td>None.</td></tr>
666+</table>
396667
397668```hoon
398669$&(combined-mold=spec normalizing-gate=hoon)
399670```
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
402−in `combined-mold`.
403671
404−##### Normalizes to
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`.
675+
676+#### AST
677+
678+```hoon
679+[%bcpm p=spec q=hoon]
680+```
681+
682+#### Normalizes to
405683
406684The product of the normalizing gate and sample.
407685
408−##### Defaults to
686+#### Defaults to
409687
410688The default of the last type listed in `p`, normalized with the normalizing gate.
411689
412−##### Discussion
690+#### Discussion
413691
414692This 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
416−updating an app.
693+an old version to a new version. For example, this may happen when migrating
694+state after updating an app.
417695
418−##### Examples
696+#### Examples
419697
420698```hoon
421699+$ old [%0 @]
@@ -423,39 +701,69 @@ updating an app.
423701+$ combined $%(old new)
424702+$ adapting $&(combined |=(?-(-.a %0 [%1 1 +.a], %1 a)))
425703```
704+
426705Here `adapting` is a structure that bunts to `[%1 ^]` but also normalizes from
427706`[%0 @]` if called on such a noun.
428707
708+---
429709
430−### `$~` "bucsig"
431−
432−`[%bssg p=hoon q=spec]`: define a custom type default value
710+## `$~` "bucsig"
433711
434−##### Product
712+Define a custom type default value.
435713
436−Creates a structure (custom type) just like `q`, except its default value is `p`.
714+#### Syntax
437715
438−##### Defaults to
716+Two arguments, fixed.
717+
718+<table>
719+<tr><th>Form</th><th>Syntax</th></tr>
720+<tr>
721+<td>Tall</td>
722+<td>
723+<pre>
724+$~ p
725+q
726+</pre>
727+</td>
728+</tr>
729+<tr>
730+<td>Wide</td>
731+<td>
732+<pre>
733+$~(p q)
734+</pre>
735+</td>
736+</tr>
737+<tr><td>Irregular</td><td>None.</td></tr>
738+</table>
739+
740+`p` defines the default value, and `q` defines everything else about the
741+structure.
742+
743+#### AST
439744
440−The product of `p`.
745+```hoon
746+[%bcsg p=hoon q=spec]
747+```
441748
442−##### Syntax
749+#### Product
443750
444−Regular: **2-fixed**.
751+Creates a structure (custom type) just like `q`, except its default value is `p`.
445752
446−```hoon
447−$~ p=hoon q=spec
448−```
753+#### Defaults to
449754
450−`p` defines the default value, and `q` defines everything else about the structure.
755+The product of `p`.
451756
452−##### Discussion
757+#### Discussion
453758
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).)
455762
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 `%~`.)
763+Do not confuse the `$~` rune with the constant type for null, `$~`. (The latter
764+uses older Hoon syntax that is still accepted. Preferably it would be `%~`.)
457765
458−##### Examples
766+#### Examples
459767
460768First, let's define a type without using `$~`:
461769
@@ -491,116 +799,217 @@ Using `$~`:
491799%default-value
492800```
493801
494−### `$@` "bucpat"
802+---
495803
496−`[%bsvt p=spec q=spec]`: structure which normalizes a union tagged by head depth (atom).
804+## `$@` "bucpat"
497805
498−##### Normalizes to
806+Structure which normalizes a union tagged by head depth (atom).
499807
500−`p`, if the sample is an atom; `q`, if the sample is a cell.
808+#### Syntax
501809
502−##### Defaults to
810+Two arguments, fixed.
811+
812+<table>
813+<tr><th>Form</th><th>Syntax</th></tr>
814+<tr>
815+<td>Tall</td>
816+<td>
817+<pre>
818+$@ p
819+q
820+</pre>
821+</td>
822+</tr>
823+<tr>
824+<td>Wide</td>
825+<td>
826+<pre>
827+$@(p q)
828+</pre>
829+</td>
830+</tr>
831+<tr><td>Irregular</td><td>None.</td></tr>
832+</table>
833+
834+#### AST
503835
504−The default of `p`.
836+```hoon
837+[%bcpt p=spec q=spec]
838+```
505839
506−#### Syntax
840+#### Normalizes to
841+
842+`p`, if the sample is an atom; `q`, if the sample is a cell.
507843
508−Regular: **2-fixed**.
844+#### Defaults to
509845
510−Product: a structure which applies `p` if its sample is an atom,
511−`q` if its sample is a cell.
846+The default of `p`.
512847
513−Regular form: **2-fixed**.
848+#### Produces
514849
515−Example:
850+A structure which applies `p` if its sample is an atom, `q` if its sample is a
851+cell.
852+
853+#### Examples
516854
517855```
518−~zod:dojo> =a $@(%foo $:(p=%baz q=@ud))
856+> =a $@(%foo $:(p=%baz q=@ud))
519857
520−~zod:dojo> (a %foo)
858+> (a %foo)
521859%foo
522860
523−~zod:dojo> `a`[%baz 99]
861+> `a`[%baz 99]
524862[p=%baz q=99]
525863
526−~zod:dojo> $:a
864+> $:a
527865%foo
528866```
529867
868+---
869+
870+## `$=` "buctis"
530871
531−### `$=` "buctis"
872+Structure which wraps a face around another structure.
532873
533−`[%bsts p=skin q=spec]`: structure which wraps a face around another structure.
874+#### Syntax
534875
535−##### Expands to
876+Two arguments, fixed.
877+
878+<table>
879+<tr><th>Form</th><th>Syntax</th></tr>
880+<tr>
881+<td>Tall</td>
882+<td>
883+<pre>
884+$= p
885+q
886+</pre>
887+</td>
888+</tr>
889+<tr>
890+<td>Wide</td>
891+<td>
892+<pre>
893+$=(p q)
894+</pre>
895+</td>
896+</tr>
897+<tr>
898+<td>Irregular</td>
899+<td>
900+<pre>
901+p=q
902+</pre>
903+</td>
904+</tr>
905+</table>
906+
907+#### AST
536908
537909```hoon
538−|= *
539−^=(p %-(q +6))
910+[%bcts p=skin q=spec]
540911```
541912
542−##### Syntax
913+#### Expands to
543914
544−Regular: **2-fixed**.
545−
546−Irregular (structure mode): `foo=baz` is `$=(foo baz)`.
915+```hoon
916+|= *
917+^=(p %-(q +6))
918+```
547919
548−##### Discussion
920+#### Discussion
549921
550922Note that the Hoon compiler is at least slightly clever about
551923compiling structures, and almost never has to actually put in a gate
552924layer (as seen in the expansion above) to apply a `$=`.
553925
554−##### Examples
926+#### Examples
555927
556928```
557−~zod:dojo> =a $=(p %foo)
929+> =a $=(p %foo)
558930
559−~zod:dojo> (a %foo)
931+> (a %foo)
560932p=%foo
561933
562−~zod:dojo> (a %baz)
934+> (a %baz)
563935ford: %ride failed to execute:
564936```
565937
566−### `$?` "bucwut"
938+---
567939
568−`[%bswt p=(list spec)]`: form a type from a union of other types.
940+## `$?` "bucwut"
569941
570−##### Normalizes to
942+Form a type from a union of other types.
571943
572−The first item in `p` which normalizes the sample to itself.
944+#### Syntax
573945
574−Void, if `p` is empty.
946+Variable number of arguments.
947+
948+<table>
949+<tr><th>Form</th><th>Syntax</th></tr>
950+<tr>
951+<td>Tall</td>
952+<td>
953+<pre>
954+$? p1
955+ p2
956+ p3
957+ pn
958+==
959+</pre>
960+</td>
961+</tr>
962+<tr>
963+<td>Wide</td>
964+<td>
965+<pre>
966+$?(p1 p2 p3 pn)
967+</pre>
968+</td>
969+</tr>
970+<tr>
971+<td>Irregular</td>
972+<td>
973+<pre>
974+?(p1 p2 p3 pn)
975+</pre>
976+</td>
977+</tr>
978+</table>
979+
980+#### AST
981+
982+```hoon
983+[%bcwt p=(list spec)]
984+```
575985
576−##### Defaults to
986+#### Normalizes to
577987
578−The first item in `p`.
988+The last item in `p` which normalizes the sample to itself.
579989
580−##### Syntax
990+Void, if `p` is empty.
581991
582−Regular: **running**.
992+#### Defaults to
583993
584−Irregular: `?(%foo %baz)` is `$?(%foo %baz)`.
994+The last item in `p`.
585995
586−##### Discussion
996+#### Discussion
587997
588−For a union of atoms, a `$?` is fine. For more complex nouns,
589−always try to use a [`$%`](#buccen), [`$@`](#bucpat) or
590−[`$^`](#bucket), at least if you expect your structure to be used as a
591−normalizer.
998+For a union of atoms, a `$?` is fine. For more complex nouns, always try to use
999+a [`$%`](#buccen), [`$@`](#bucpat) or [`$^`](#bucket), at least if you expect
1000+your structure to be used as a normalizer.
5921001
593−##### Examples
1002+#### Examples
5941003
5951004```
596−~zod:dojo> =a ?(%foo %baz %baz)
1005+> =a ?(%foo %baz %baz)
5971006
598−~zod:dojo> (a %baz)
1007+> (a %baz)
5991008%baz
6001009
601−~zod:dojo> (a [37 45])
1010+> (a [37 45])
6021011ford: %ride failed to execute:
6031012
604−~zod:dojo> $:a
1013+> $:a
6051014%baz
6061015```