on master help sign in
Merge pull request #885 from urbit/bucpam
ac27980poprox
reference/hoon-expressions/rune/buc.md+43−1
@@ -301,11 +301,52 @@ Regular: **2-fixed**.
301[%baz p=0]
301[%baz p=0]
302```
302```
303
303
304+### $& "bucpam"
305+
306+`[%bspd p=spec q=hoon]`: repair a value of a tagged union type
307+
308+##### Syntax
309+
310+Regular: **2-fixed**.
311+
312+```hoon
313+$&(combined-mold=spec normalizing-gate=hoon)
314+```
315+Here `combined-mold` is a tagged union type (typically made with `$%`) and `normalizing-gate` is a
316+gate which accepts values of `combined-mold` and normalizes them to be of one particular type
317+in `combined-mold`.
318+
319+##### Normalizes to
320+
321+The product of the normalizing gate and sample.
322+
323+##### Defaults to
324+
325+The default of the last type listed in `p`, normalized with the normalizing gate.
326+
327+##### Discussion
328+
329+This rune is used to "upgrade" or "repair" values of a structure, typically from
330+an old version to a new version. For example, this may happen when migrating state after
331+updating an app.
332+
333+##### Examples
334+
335+```hoon
336++$ old [%0 @]
337++$ new [%1 ^]
338++$ combined $%(old new)
339++$ adapting $&(combined |=(?-(-.a %0 [%1 1 +.a], %1 a)))
340+```
341+Here `adapting` is a structure that bunts to `[%1 ^]` but also normalizes from
342+`[%0 @]` if called on such a noun.
343+
344+
304### `$~` "bucsig"
345### `$~` "bucsig"
305
346
306`[%bssg p=hoon q=spec]`: define a custom type default value
347`[%bssg p=hoon q=spec]`: define a custom type default value
307
348
308−## Product
349+##### Product
309
350
310Creates a structure (custom type) just like `q`, except its default value is `p`.
351Creates a structure (custom type) just like `q`, except its default value is `p`.
311
352
@@ -343,6 +384,7 @@ First, let's define a type without using `$~`:
343[%two 478.560.413.032]
384[%two 478.560.413.032]
344
385
345> *b
386> *b
387+
346%$
388%$
347
389
348> *@tas
390> *@tas