git.iko.soy/urbit.org
on master help sign in
reorg of | runes
f5bad36joshuareagan
docs/reference/rune/bar/cab.udon+38−10
compare with master
unifiedsplit
@@ -7,28 +7,56 @@
7
7
8# `|_ "barcab"`
8# `|_ "barcab"`
9
9
10−`[%brcb p=spec q=(map term hoon)]`: produce a door, a many-armed core
11−with a sample.
10+Produce a *door* (a core with a sample).
12
11
13−## Expands to
12+## Syntax
13+
14+Regular:
14
15
15```
16```
16−=| p
17+|_ a=spec
17−|% q
18+++ name-1 b=hoon
18−==
19+++ name-2 c=hoon
20+ ...
21+++ name-n d=hoon
22+--
19```
23```
20
24
21−## Syntax
25+Note: The `++` rune may be replaced with any other rune in the `+` family.
26+
27+AST:
28+
29+```
30+[%brcb p=spec q=alas r=(map term tome)]
31+```
22
32
23−Regular: *1-fixed*, then *battery*.
33+## Semantics
34+
35+The product of a `|_` expression is a *door*, a core with one or more arms whose payload includes a sample. That is, a door is a cell of `[battery [sample context]]`, where the `battery` contains one or more arms.
36+
37+`a` defines the door sample type and usually includes a name assignment (e.g., `n=@`). `a` is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name, which is followed by the expression (`b`, `c`, and `d` above) that defines the arm product.
38+
39+The context of the door is the subject of the `|_` expression.
40+
41+## Expands to
42+
43+```
44+=| a
45+|%
46+++ name-1 b
47+++ name-2 c
48+ ...
49+++ name-n d
50+--
51+```
24
52
25## Discussion
53## Discussion
26
54
27A door is the general case of a gate (function). A gate is a
55A door is the general case of a gate (function). A gate is a
28−door with only one arm, which has the empty name `$`.
56+door with only one arm, which has the name `$`.
29
57
30Calling a door is like calling a gate except the caller also needs
58Calling a door is like calling a gate except the caller also needs
31−to specify the arm to be computed. So, for example, if you have some door `d` which contains some arm `a`, and you want to pass some argument (i.e., input value `arg`, you would call it with `~(a d arg)`.
59+to specify the arm to be computed. So, for example, if you have some door `door` which contains some arm `arm`, and you want to pass some argument (i.e., input value `arg`), you would call it with `~(arm door arg)`.
32
60
33Because gates are also doors, you can call them the same way. To call the gate `foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This
61Because gates are also doors, you can call them the same way. To call the gate `foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This
34is an irregular form for `%~($ foo baz)`, [%~](../../cen/sig).
62is an irregular form for `%~($ foo baz)`, [%~](../../cen/sig).
docs/reference/rune/bar/cen.udon+27−6
@@ -7,15 +7,36 @@
7
7
8# `|% "barcen"`
8# `|% "barcen"`
9
9
10−[%brcn p=(map term hoon)]: Form a core `[battery payload]` with subject as the payload.
10+Produce a core, `[battery payload]`.
11
11
12−## Produces
12+## Syntax
13
13
14−A core with battery `p`. Payload is the subject.
14+Regular:
15
15
16−## Syntax
16+```
17+|%
18+++ name-1 a=hoon
19+++ name-2 b=hoon
20+ ...
21+++ name-n c=hoon
22+--
23+```
24+
25+Note: The `++` rune may be replaced with any other rune in the `+` family.
26+
27+AST:
28+
29+```
30+[%brcn p=(unit term) q=(map term tome)]
31+```
32+
33+## Semantics
34+
35+The product of a `|%` expression is a dry core with one or more arms in the battery.
36+
37+The `|%` rune is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name, which is followed by the expression (`a`, `b`, and `c` above) that defines the arm product.
17
38
18−Regular: *battery*.
39+The core payload is the subject of the `|%` expression.
19
40
20## Discussion
41## Discussion
21
42
@@ -25,7 +46,7 @@ The `|%` rune is used to construct a core from a series of arm definitions. Eac
25
46
26A core is like an "object" in a conventional language, but its
47A core is like an "object" in a conventional language, but its
27attributes (_arms_) are functions on the core, not the core and
48attributes (_arms_) are functions on the core, not the core and
28−an argument. A "method" on a core is an arm producing a gate.
49+an argument. A "method" on a core is an arm that produces a gate.
29
50
30## Examples
51## Examples
31
52
docs/reference/rune/bar/col.udon+32−6
@@ -7,22 +7,48 @@
7
7
8# `|: "barcol"`
8# `|: "barcol"`
9
9
10+Produce a gate with a custom sample.
11+
12+## Syntax
13+
14+Regular:
15+
16+```
17+|: a=hoon b=hoon
18+```
19+
20+AST:
21+
22+```
10−`[%brcl p=hoon q=hoon]`: form a gate with a custom sample.
23+[%brcl p=hoon q=hoon]
24+```
25+
26+## Semantics
27+
28+`a` is a Hoon expression whose product type defines which values the gate accepts, and it usually includes a name (e.g., `n=1`). The product of `a` also serves as the default value of the sample. `b` is a Hoon expression that determines the product value of the gate.
11
29
12## Expands to
30## Expands to
13
31
14```
32```
15−=> ^~ p
33+=> ^~ a
16− |. q
34+ |. b
17```
35```
18
36
19## Discussion
37## Discussion
20
38
21−Pick your own default value for the sample. Note that `p` is an ordinary expression, not a type; `|:` doesn't bunt a sample as
39+Pick your own default value for the sample. Note that `a` is an ordinary expression, not a type; `|:` doesn't bunt a sample as
22[`|=`](../tis) does.
40[`|=`](../tis) does.
23
41
24This is useful if you want a gate to have a sample of a particular type, but you don't want the default value of the gate to be the default value of that type.
42This is useful if you want a gate to have a sample of a particular type, but you don't want the default value of the gate to be the default value of that type.
25
43
26−## Syntax
44+## Examples
27
45
28−Regular: *2-fixed*.
46+```
47+> =add-ten |:(n=`@`2 (add n 10))
48+
49+> (add-ten 10)
50+20
51+
52+> (add-ten)
53+12
54+```
docs/reference/rune/bar/dot.udon+24−8
@@ -7,22 +7,38 @@
7
7
8# `|. "bardot"`
8# `|. "bardot"`
9
9
10−`[%brdt p=hoon]`: form a trap, a core with one arm `$`.
10+Produce a trap (a core with one arm `$`).
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−|% ++ $ p
17+|. a=hoon
16−--
17```
18```
18
19
19−## Syntax
20+AST:
21+
22+```
23+[%brdt p=hoon]
24+```
20
25
21−Regular: *1-fixed*.
26+Semantics:
27+
28+A `|.` expression produces a core with a single arm, `$`. The core isn't explicitly given a sample. `a` is a Hoon expression that defines the computation of the `$` arm.
29+
30+The payload of the core is the subject of the `|.` expression.
31+
32+## Expands to
33+
34+```
35+|% ++ $ a
36+--
37+```
22
38
23## Discussion
39## Discussion
24
40
25−A trap is used to defer a computation.
41+A trap is generally used to defer a computation.
26
42
27## Examples
43## Examples
28
44
@@ -55,4 +71,4 @@ A more interesting trap:
55Note that we can use `$()` to recurse back into the
71Note that we can use `$()` to recurse back into the
56trap, since it's a core with an `$` arm.
72trap, since it's a core with an `$` arm.
57
73
58−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
74+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
docs/reference/rune/bar/hep.udon+21−8
@@ -7,24 +7,37 @@
7
7
8# `|- "barhep"`
8# `|- "barhep"`
9
9
10−`[%brhp p=hoon]`: form a trap and evaluate it.
10+Produce a trap (a core with one arm `$`) and evaluate it.
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−=<($ |.(p))
17+|- a=hoon
16```
18```
17
19
18−## Syntax
20+AST:
21+
22+```
23+[%brhp p=hoon]
24+```
19
25
20−Regular: *1-fixed*.
26+## Semantics
27+
28+A `|-` expression produces a core with one arm named `$` and immediately evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
29+
30+## Expands to
31+
32+```
33+=<($ |.(a))
34+```
21
35
22## Discussion
36## Discussion
23
37
24−The `|-` rune can be thought of as a 'recursion
25−point' or a 'loop starting point'. Since `|-` makes a `|.` (["bardot"](../dot), a core with one arm named `$`, we can recurse back into it with `$()`.
38+The `|-` rune can be thought of as a 'recursion point' or a 'loop starting point'. Since `|-` makes a `|.` (["bardot"](../dot), a core with one arm named `$`, we can recurse back into it with `$()`.
26
39
27−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
40+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
28
41
29## Examples
42## Examples
30
43
docs/reference/rune/bar/ket.udon+30−8
@@ -7,25 +7,47 @@
7
7
8# `|^ "barket"`
8# `|^ "barket"`
9
9
10−`[%brkt p=hoon q=(map term hoon)]`: form a core whose battery includes a `$` arm `$`, and compute the latter.
10+Produce a core whose battery includes a `$` arm and compute the latter.
11+
12+## Syntax
13+
14+Regular:
15+
16+```
17+|^ a=hoon
18+++ name-1 b=hoon
19+++ name-2 c=hoon
20+ ...
21+++ name-n d=hoon
22+--
23+```
24+
25+AST:
26+
27+```
28+[%brkt p=hoon q=(map term tome)]
29+```
30+
31+## Semantics
32+
33+A `|^` expression produces a multi-arm core whose battery includes a `$` arm, which is evaluated immediately. `a` is a Hoon expression that defines the product of the `$` arm. `a` is followed by a series of arm definitions for the rest of the core battery arms. There must be at least one arm other than the `$` arm.
11
34
12## Expands to
35## Expands to
13
36
14```
37```
15=> |%
38=> |%
16− ++ $ p
39+ ++ $ a=hoon
17− q
40+ ++ name-1 b=hoon
41+ ++ name-2 c=hoon
42+ ...
43+ ++ name-n d=hoon
18 --
44 --
19$
45$
20```
46```
21
47
22−## Syntax
23−
24−Regular: *1-fixed*, then *battery*.
25−
26## Discussion
48## Discussion
27
49
28−The `|^` rune is useful when you want to construct a multi-arm core and you immediately want to evaluate a particular arm in it.
50+The `|^` rune is useful when you define a multi-arm core in your code and a particular arm in it is to be evaluated immediately.
29
51
30## Examples
52## Examples
31
53
docs/reference/rune/bar/sig.udon+19−5
@@ -7,17 +7,31 @@
7
7
8# `|~ "barsig"`
8# `|~ "barsig"`
9
9
10−`[%brsg p=spec q=hoon]`: form an iron gate.
10+Produce an iron gate.
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−^| |=(p q)
17+|~ a=spec b=hoon
16```
18```
17
19
18−## Syntax
20+AST:
21+
22+```
23+[%brsg p=spec q=hoon]
24+```
19
25
20−Regular: *2-fixed*.
26+## Semantics
27+
28+A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines the output value of the gate.
29+
30+## Expands to
31+
32+```
33+^| |=(a b)
34+```
21
35
22## Discussion
36## Discussion
23
37
docs/reference/rune/bar/tar.udon+24−10
@@ -7,21 +7,35 @@
7
7
8# `|* "bartar"`
8# `|* "bartar"`
9
9
10−`[%brtr p=spec q=hoon]`: produce a wet one-armed core with sample.
10+Produce a wet gate (one-armed core with sample).
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−=| p
17+|* a=spec b=hoon
16−|%
17−+- $
18− q
19−--
20```
18```
21
19
22−## Syntax
20+AST:
21+
22+```
23+[%brtr p=spec q=hoon]
24+```
23
25
24−Regular: *2-fixed*.
26+## Semantics
27+
28+A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b` is a Hoon expression that determines the output value of the gate.
29+
30+## Expands to
31+
32+```
33+=| a
34+|@
35+++ $
36+ b
37+--
38+```
25
39
26## Discussion
40## Discussion
27
41
@@ -36,7 +50,7 @@ you know what you're doing.
36Just as with a [gate](../tis), we can recurse back into a wet gate
50Just as with a [gate](../tis), we can recurse back into a wet gate
37with `$()`.
51with `$()`.
38
52
39−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
53+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
40
54
41## Examples
55## Examples
42
56
docs/reference/rune/bar/tis.udon+25−11
@@ -7,28 +7,42 @@
7
7
8# `|= "bartis"`
8# `|= "bartis"`
9
9
10−`[%brts p=spec q=hoon]`: form a gate, a dry one-armed core with sample.
10+Produce a gate (a one-armed core with a sample).
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−=| p
17+|= a=spec b=hoon
16−|% ++ $ q
17−--
18```
18```
19
19
20−## Syntax
20+AST:
21+
22+```
23+[%brts p=spec q=hoon]`
24+
25+## Definition
21
26
22−Regular: *2-fixed*.
27+The product of a `|=` expression is a dry *gate*, i.e., a Hoon function.
28+
29+`p` defines the gate sample type -- i.e., the input value type -- and usually includes a sample name assignment (e.g., `a=@`). `q` is an expression that determines the output value of the gate.
30+
31+## Expands to
32+
33+```
34+=| a
35+|% ++ $ b
36+--
37+```
23
38
24## Discussion
39## Discussion
25
40
26−Dry gates are used for the vast majority of ordinary functions in Hoon. `p` defines the type of the 'sample', i.e., the input value of the function, and usually assigns it a name (e.g., `a=@`). `q` defines the product or the output of the function.
41+Dry gates are used for the vast majority of ordinary functions in Hoon.
27
42
28−A gate is a core with one arm named `$`, so, just as with
43+A gate is a core with one arm named `$`, so we can recurse back into it with `$()`.
29−[`|-`](../hep), we can recurse back into it with `$()`.
30
44
31−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
45+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
32
46
33## Examples
47## Examples
34
48
docs/reference/rune/bar/vat.udon+22−5
@@ -7,15 +7,32 @@
7
7
8# `|@ "barvat"`
8# `|@ "barvat"`
9
9
10−[%brvt p=(map term hoon)]: Form a 'wet' core `[battery payload]` with subject as the payload.
10+Produce a 'wet' core `[battery payload]`.
11
11
12−## Produces
12+## Syntax
13
13
14−A wet core with battery `p`. Payload is the subject.
14+Regular:
15
15
16−## Syntax
16+```
17+|@
18+++ name-1 a=hoon
19+++ name-2 b=hoon
20+ ...
21+++ name-n c=hoon
22+--
23+```
24+
25+Note: The `++` rune may be replaced with any other rune in the `+` family.
26+
27+AST:
28+
29+```
30+[%brvt p=(unit term) q=(map term tome)]
31+```
32+
33+## Semantics
17
34
18−Regular: *battery*.
35+A `|@` expression produces a 'wet' core whose payload is the expression's subject. The various arms in the battery are named and defined explicitly (with `a` through `c` above).
19
36
20## Discussion
37## Discussion
21
38
docs/reference/rune/bar/wut.udon+19−5
@@ -7,17 +7,31 @@
7
7
8# `|? "barwut"`
8# `|? "barwut"`
9
9
10−`[%brwt p=hoon]`: form a lead trap.
10+Produce a lead trap.
11
11
12−## Expands to
12+## Syntax
13+
14+Regular:
13
15
14```
16```
15−^? |. p
17+|? a=hoon
16```
18```
17
19
18−## Syntax
20+AST:
21+
22+```
23+[%brwt p=hoon]
24+```
19
25
20−Regular: *1-fixed*.
26+## Semantics
27+
28+A `|?` expression produces a lead trap (i.e., a lead core with one arm named `$`). `a` is a Hoon expression that defines the product of the `$` arm.
29+
30+## Expands to
31+
32+```
33+^? |. a
34+```
21
35
22## Discussion
36## Discussion
23
37