@@ -4,38 +4,51 @@ weight = 12
44template = "doc.html"
55aliases = ["docs/reference/hoon-expressions/rune/buc/"]
66+++
7+
78The `$` family of runes is used for defining custom types. Strictly speaking,
8−these runes are used to produce 'structures'. A structure is a compile-time
9−value that at runtime can be converted to either an example value (sometimes
10−called a 'bunt' value) for its corresponding type, or to a 'mold'. An example
11−value is used as a placeholder for sample values, among other things. A
12−mold is an idempotent function used as a data validator.
9+these runes are used to produce `spec`s, which we call 'structures'.
1310
1411## Overview
1512
16−A correct mold is a **normalizer**: an idempotent function across
17−all nouns. If the sample of a gate has type `%noun`, and its
18−body obeys the constraint that for any x, `=((mold x) (mold (mold
19−x)))`, it's a normalizer and can be used as a mold.
20−
21−(Hoon is not dependently typed and so can't check idempotence
22−statically, so we can't actually tell if a mold matches this
23−definition perfectly. This is not actually a problem.)
24−
25−Validation, though very
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
28−in userspace.
29−
30−In any case, since molds are just functions, we can use
31−functional programming to assemble interesting molds. For
32−instance, `(map foo bar)` is a table from mold `foo` to mold
33−`bar`. `map` is not a mold; it's a function that makes a mold.
34−Molds and mold builders are generally described together.
13+Structures are abstract syntax trees for `type`s (see the documentation on
14+[basic](@/docs/reference/hoon-expressions/basic.md) and
15+[advanced](@/docs/reference/hoon-expressions/advanced.md) types for the
16+precise definition of `type`). Structures are compile-time values of `type` which
17+at runtime may be used to produce a 'mold'.
18+
19+A mold is a function from nouns to nouns used to validate values of the type to
20+which the structure defines. A mold can do two things at runtime. First, it may
21+'clam' a noun, which validates the shape of the noun to be one that fits the
22+abstract syntax tree given by the `spec` that produced the mold. Failing this
23+validation results in a crash. Secondly, a mold may also be used to produce an
24+example value of the type to which is corresponds, called the 'bunt value'. The
25+bunt value is used as a placeholder for sample values that may be passed to a
26+gate that accepts the corresponding type.
27+
28+A correct mold is a **normalizer**: an idempotent function across all nouns. If
29+the sample of a gate has type `%noun`, and its body obeys the constraint that
30+for any x, `=((mold x) (mold (mold x)))`, it's a normalizer and can be used as a
31+mold. Hoon is not dependently typed and so can't check idempotence statically,
32+so we can't actually tell if a mold matches this definition perfectly. This is
33+not actually a problem.
34+
35+In any case, since molds are just functions, we can use functional programming
36+to assemble interesting molds. For instance, `(map foo bar)` is a table from
37+mold `foo` to mold `bar`. `map` is not a mold; it's a function that makes a
38+mold. Molds and mold builders are generally described together.
39+
40+`spec`s contain more information and draw finer distinctions than `type`s,
41+which is to say that a given type may have more than one valid `spec` defining
42+it, and thus downconversion from `spec` to `type` is lossy. Thus structure
43+validation (done with [`$|`](#bucbar), which is a more restrictive validation
44+than that performed by molds, is a rare use case. Except for direct raw input,
45+it's generally a faux pas to validate structure at runtime -- or even in userspace.
46+Nonetheless they are sometimes utilized for types that will be more performant
47+if they satisfy some validating gate.
3548
3649## Base Structures
3750
38−`[%base p=$@(?(%noun %cell %bean %null) [%atom p=aura])]`: trivial structures (types).
51+`[%base p=$@(?(%noun %cell %flag %null %void) [%atom p=aura])]`: trivial structures (types).
3952
4053##### Produces
4154
@@ -43,13 +56,14 @@ A structure is a noun produced, usually at compile-time, for use in tracking typ
4356
4457A structure for the base in `p`. `%noun` is any noun; `%atom` is any
4558atom; `%cell` is a cell of nouns; `%flag` is a loobean, ``?(`@f`0
46−`@f`1)``. `%null` is zero with aura `@n`.
59+`@f`1)``. `%null` is zero with aura `@n`, `%void` is the empty set.
4760
4861##### Syntax
4962
5063Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
5164`%bean`, `~` makes `%null`, `@aura` makes atom `aura`.
5265
66+
5367## Runes
5468
5569### $| "bucbar"