git.iko.soy/urbit.org
on master help sign in
reorg of | runes
commitf5bad368caed79bfb556657c2dd62d4df5a18e6c authorjoshuareagan <josh@tlon.io> dateMon 22 Oct 2018, 13:46 (8 years ago) parentc19bc7a
11 files changed+281−82
compare with master
unifiedsplit
docs/reference/rune/bar/cab.udon+38−10 docs/reference/rune/bar/cen.udon+27−6 docs/reference/rune/bar/col.udon+32−6 docs/reference/rune/bar/dot.udon+24−8 docs/reference/rune/bar/hep.udon+21−8 docs/reference/rune/bar/ket.udon+30−8 docs/reference/rune/bar/sig.udon+19−5 docs/reference/rune/bar/tar.udon+24−10 docs/reference/rune/bar/tis.udon+25−11 docs/reference/rune/bar/vat.udon+22−5 docs/reference/rune/bar/wut.udon+19−5
docs/reference/rune/bar/cab.udon+38−10
@@ -7,28 +7,56 @@
77
88# `|_ "barcab"`
99
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).
1211
13−## Expands to
12+## Syntax
13+
14+Regular:
1415
1516```
16−=| p
17−|% q
18−==
17+|_ a=spec
18+++ name-1 b=hoon
19+++ name-2 c=hoon
20+ ...
21+++ name-n d=hoon
22+--
1923```
2024
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+```
2232
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+```
2452
2553## Discussion
2654
2755A 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 `$`.
2957
3058Calling 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)`.
3260
3361Because 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
3462is an irregular form for `%~($ foo baz)`, [%~](../../cen/sig).
docs/reference/rune/bar/cen.udon+27−6
@@ -7,15 +7,36 @@
77
88# `|% "barcen"`
99
10−[%brcn p=(map term hoon)]: Form a core `[battery payload]` with subject as the payload.
10+Produce a core, `[battery payload]`.
1111
12−## Produces
12+## Syntax
1313
14−A core with battery `p`. Payload is the subject.
14+Regular:
1515
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.
1738
18−Regular: *battery*.
39+The core payload is the subject of the `|%` expression.
1940
2041## Discussion
2142
@@ -25,7 +46,7 @@ The `|%` rune is used to construct a core from a series of arm definitions. Eac
2546
2647A core is like an "object" in a conventional language, but its
2748attributes (_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.
2950
3051## Examples
3152
docs/reference/rune/bar/col.udon+32−6
@@ -7,22 +7,48 @@
77
88# `|: "barcol"`
99
10−`[%brcl p=hoon q=hoon]`: form a gate with a custom sample.
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+```
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.
1129
1230## Expands to
1331
1432```
15−=> ^~ p
16− |. q
33+=> ^~ a
34+ |. b
1735```
1836
1937## Discussion
2038
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
2240[`|=`](../tis) does.
2341
2442This 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.
2543
26−## Syntax
44+## Examples
2745
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 @@
77
88# `|. "bardot"`
99
10−`[%brdt p=hoon]`: form a trap, a core with one arm `$`.
10+Produce a trap (a core with one arm `$`).
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−|% ++ $ p
16−--
17+|. a=hoon
1718```
1819
19−## Syntax
20+AST:
21+
22+```
23+[%brdt p=hoon]
24+```
2025
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+```
2238
2339## Discussion
2440
25−A trap is used to defer a computation.
41+A trap is generally used to defer a computation.
2642
2743## Examples
2844
@@ -55,4 +71,4 @@ A more interesting trap:
5571Note that we can use `$()` to recurse back into the
5672trap, since it's a core with an `$` arm.
5773
58−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
74+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
docs/reference/rune/bar/hep.udon+21−8
@@ -7,24 +7,37 @@
77
88# `|- "barhep"`
99
10−`[%brhp p=hoon]`: form a trap and evaluate it.
10+Produce a trap (a core with one arm `$`) and evaluate it.
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−=<($ |.(p))
17+|- a=hoon
1618```
1719
18−## Syntax
20+AST:
21+
22+```
23+[%brhp p=hoon]
24+```
1925
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+```
2135
2236## Discussion
2337
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 `$()`.
2639
27−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
40+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
2841
2942## Examples
3043
docs/reference/rune/bar/ket.udon+30−8
@@ -7,25 +7,47 @@
77
88# `|^ "barket"`
99
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.
1134
1235## Expands to
1336
1437```
1538=> |%
16− ++ $ p
17− q
39+ ++ $ a=hoon
40+ ++ name-1 b=hoon
41+ ++ name-2 c=hoon
42+ ...
43+ ++ name-n d=hoon
1844 --
1945$
2046```
2147
22−## Syntax
23−
24−Regular: *1-fixed*, then *battery*.
25−
2648## Discussion
2749
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.
2951
3052## Examples
3153
docs/reference/rune/bar/sig.udon+19−5
@@ -7,17 +7,31 @@
77
88# `|~ "barsig"`
99
10−`[%brsg p=spec q=hoon]`: form an iron gate.
10+Produce an iron gate.
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−^| |=(p q)
17+|~ a=spec b=hoon
1618```
1719
18−## Syntax
20+AST:
21+
22+```
23+[%brsg p=spec q=hoon]
24+```
1925
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+```
2135
2236## Discussion
2337
docs/reference/rune/bar/tar.udon+24−10
@@ -7,21 +7,35 @@
77
88# `|* "bartar"`
99
10−`[%brtr p=spec q=hoon]`: produce a wet one-armed core with sample.
10+Produce a wet gate (one-armed core with sample).
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−=| p
16−|%
17−+- $
18− q
19−--
17+|* a=spec b=hoon
2018```
2119
22−## Syntax
20+AST:
21+
22+```
23+[%brtr p=spec q=hoon]
24+```
2325
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+```
2539
2640## Discussion
2741
@@ -36,7 +50,7 @@ you know what you're doing.
3650Just as with a [gate](../tis), we can recurse back into a wet gate
3751with `$()`.
3852
39−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
53+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
4054
4155## Examples
4256
docs/reference/rune/bar/tis.udon+25−11
@@ -7,28 +7,42 @@
77
88# `|= "bartis"`
99
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).
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−=| p
16−|% ++ $ q
17−--
17+|= a=spec b=hoon
1818```
1919
20−## Syntax
20+AST:
21+
22+```
23+[%brts p=spec q=hoon]`
24+
25+## Definition
2126
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+```
2338
2439## Discussion
2540
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.
2742
28−A gate is a core with one arm named `$`, so, just as with
29−[`|-`](../hep), we can recurse back into it with `$()`.
43+A gate is a core with one arm named `$`, so we can recurse back into it with `$()`.
3044
31−> `$()` expands to `%=($)` (["centis"](../../cen/tis)).
45+> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
3246
3347## Examples
3448
docs/reference/rune/bar/vat.udon+22−5
@@ -7,15 +7,32 @@
77
88# `|@ "barvat"`
99
10−[%brvt p=(map term hoon)]: Form a 'wet' core `[battery payload]` with subject as the payload.
10+Produce a 'wet' core `[battery payload]`.
1111
12−## Produces
12+## Syntax
1313
14−A wet core with battery `p`. Payload is the subject.
14+Regular:
1515
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
1734
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).
1936
2037## Discussion
2138
docs/reference/rune/bar/wut.udon+19−5
@@ -7,17 +7,31 @@
77
88# `|? "barwut"`
99
10−`[%brwt p=hoon]`: form a lead trap.
10+Produce a lead trap.
1111
12−## Expands to
12+## Syntax
13+
14+Regular:
1315
1416```
15−^? |. p
17+|? a=hoon
1618```
1719
18−## Syntax
20+AST:
21+
22+```
23+[%brwt p=hoon]
24+```
1925
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+```
2135
2236## Discussion
2337