bd9ebd1 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

reorg of % runes, minor fixes for | runes

commitbd9ebd13a272a487c4cf0101863d1aac4b2976db authorjoshuareagan <josh@tlon.io> dateMon 22 Oct 2018, 16:19 (8 years ago) parentf5bad36

17 files changed+270−107

compare with master

unifiedsplit

docs/reference/rune/bar/cab.udon+8−8

@@ -15,10 +15,10 @@ Regular:

1515

1616```

1717|_ a=spec

18−++ name-1 b=hoon

19−++ name-2 c=hoon

18+++ b=term c=hoon

19+++ d=term e=hoon

2020 ...

21−++ name-n d=hoon

21+++ f=term g=hoon

2222--

2323```

2424

@@ -34,19 +34,19 @@ AST:

3434

3535The 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.

3636

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.

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 (`b`, `d`, and `f` above), which is followed by the expression (`c`, `e`, and `g` above) that defines the arm product.

3838

3939The context of the door is the subject of the `|_` expression.

4040

4141## Expands to

4242

4343```

44−=| a

44+=| a=spec

4545|%

46−++ name-1 b

47−++ name-2 c

46+++ b=term c=hoon

47+++ d=term e=hoon

4848 ...

49−++ name-n d

49+++ f=term g=hoon

5050--

5151```

5252

docs/reference/rune/bar/cen.udon+4−4

@@ -15,10 +15,10 @@ Regular:

1515

1616```

1717|%

18−++ name-1 a=hoon

19−++ name-2 b=hoon

18+++ a=term b=hoon

19+++ c=term d=hoon

2020 ...

21−++ name-n c=hoon

21+++ e=term f=hoon

2222--

2323```

2424

@@ -34,7 +34,7 @@ AST:

3434

3535The product of a `|%` expression is a dry core with one or more arms in the battery.

3636

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.

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 (`a`, `c`, and `e` above), which is followed by the expression (`b`, `d`, and `f` above) that defines the arm product.

3838

3939The core payload is the subject of the `|%` expression.

4040

docs/reference/rune/bar/dot.udon+1−1

@@ -32,7 +32,7 @@ The payload of the core is the subject of the `|.` expression.

3232## Expands to

3333

3434```

35−|% ++ $ a

35+|% ++ $ a=hoon

3636--

3737```

3838

docs/reference/rune/bar/hep.udon+1−1

@@ -30,7 +30,7 @@ A `|-` expression produces a core with one arm named `$` and immediately evaluat

3030## Expands to

3131

3232```

33−=<($ |.(a))

33+=<($ |.(a=hoon))

3434```

3535

3636## Discussion

docs/reference/rune/bar/ket.udon+8−6

@@ -15,13 +15,15 @@ Regular:

1515

1616```

1717|^ a=hoon

18−++ name-1 b=hoon

19−++ name-2 c=hoon

18+++ b=term c=hoon

19+++ d=term e=hoon

2020 ...

21−++ name-n d=hoon

21+++ f=term g=hoon

2222--

2323```

2424

25+Note: The `++` rune may be replaced with any other rune in the `+` family.

26+

2527AST:

2628

2729```

@@ -37,10 +39,10 @@ A `|^` expression produces a multi-arm core whose battery includes a `$` arm, wh

3739```

3840=> |%

3941 ++ $ a=hoon

40− ++ name-1 b=hoon

41− ++ name-2 c=hoon

42+ ++ b=term c=hoon

43+ ++ d=term e=hoon

4244 ...

43− ++ name-n d=hoon

45+ ++ f=term g=hoon

4446 --

4547$

4648```

docs/reference/rune/bar/tis.udon+2−2

@@ -31,8 +31,8 @@ The product of a `|=` expression is a dry *gate*, i.e., a Hoon function.

3131## Expands to

3232

3333```

34−=| a

35−|% ++ $ b

34+=| a=spec

35+|% ++ $ b=hoon

3636--

3737```

3838

docs/reference/rune/bar/vat.udon+4−4

@@ -15,10 +15,10 @@ Regular:

1515

1616```

1717|@

18−++ name-1 a=hoon

19−++ name-2 b=hoon

18+++ a=term b=hoon

19+++ c=term d=hoon

2020 ...

21−++ name-n c=hoon

21+++ e=term f=hoon

2222--

2323```

2424

@@ -32,7 +32,7 @@ AST:

3232

3333## Semantics

3434

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).

35+A `|@` expression produces a 'wet' core whose payload is the expression's subject. The various arms in the battery are each named (`a`, `c`, and `e` above) and defined explicitly with a Hoon expression (with `b`, `d`, and `f` above).

3636

3737## Discussion

3838

docs/reference/rune/bar/wut.udon+1−1

@@ -25,7 +25,7 @@ AST:

2525

2626## Semantics

2727

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.

28+A `|?` expression produces a lead trap (i.e., a lead core with one arm named `$`). `a` is a Hoon expression that defines what the `$` arm does.

2929

3030## Expands to

3131

docs/reference/rune/cen/cab.udon+33−6

@@ -7,21 +7,48 @@

88# `%_ "cencab"`

10−`[%cncb p=wing q=(list (pair wing hoon))]`: resolve a wing with changes, preserving type.

10+Resolve a wing with changes, preserving type.

1111

12−## Expands to

12+## Syntax

13+

14+Regular, tall:

1315

1416```

15−^+(p %=(p q))

17+%_ a=wing

18+ b=wing c=hoon

19+ d=wing e=hoon

20+ ...

21+ f=wing g=hoon

22+==

1623```

1724

18−## Syntax

25+Regular, flat:

26+

27+```

28+%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)

29+```

30+

31+AST:

32+

33+```

34+[%cncb p=wing q=(list (pair wing hoon))]

35+```

36+

37+## Semantics

1938

20−Regular: *1-fixed*, then *jogging*.

39+A `%_` expression resolves to the value of the subject at wing `a`, but modified according to a series of changes: `b` is replaced with the product of `c`, `d` with the product of `e`, and so on. At compile time a type check is performed to ensure that the resulting value is of the same type as `a`.

40+

41+## Expands to

42+

43+```

44+^+(a %=(a b c, d e, ...))

45+```

2146

2247## Discussion

2348

24−`%_` is different from `%=` because `%=` can change the type of a limb with mutations. `%_` preserves the limb type.

49+`%_` is different from `%=` because `%=` can change the type of a wing with mutations. `%_` preserves the wing type.

50+

51+See [how wings are resolved](../../limb/wing).

2552

2653## Examples

2754

docs/reference/rune/cen/col.udon+26−9

@@ -7,19 +7,32 @@

88# `%: "cencol"`

10−`[%cncl p=hoon q=(list hoon)]`: call gate `p` with sample `q`.

10+Call a gate with many arguments.

1111

1212## Syntax

1313

14−Regular: *1-fixed* then *running*.

14+Regular:

1515

1616```

17−%: p=hoon r=hoon s=hoon ... z=hoon ==

17+%: a=hoon

18+ b=hoon

19+ c=hoon

20+ ...

21+ d=hoon

22+==

1823```

1924

20−## Discussion

25+AST:

26+

27+```

28+[%cncl p=hoon q=(list hoon)]

29+```

2130

22−`p` is the gate to be called, and a noun is constructed from `r` through `z` and passed to `p`. If there is only one subexpression after `p`, its product is the sample. Otherwise a cell is constructed from the whole series of subexpressions after `p`, and that is the sample.

31+## Semantics

32+

33+A `%:` expression calls a gate with many arguments. `a` is the gate to be called, and `b` through `d` are the arguments. If there is only one subexpression after `a`, its product is the sample. Otherwise, a single argument is constructed by evaluating all of `b` through `d` -- however many subexpressions there are -- and putting the result in a cell: `[b c ... d]`.

34+

35+## Discussion

2336

2437When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.

2538

@@ -29,15 +42,19 @@ When `%:` is used in tall-form syntax, the series of expressions after `p` must

2942> %: add 22 33 ==

304355

3144

32−> =adder |= a=(list @)

45+> =adder |= a=*

3346 =+ c=0

3447 |-

35− ?~ a c

36− $(c (add i.a c), a t.a)

48+ ?@ a (add a c)

49+ ?^ -.a !!

50+ $(c (add -.a c), a +.a)

3751

38−> %: adder 22 33 44 ~ ==

52+> %: adder 22 33 44 ==

395399

4054

55+> %: adder 22 33 44 55 ==

56+154

57+

4158> %:(adder 22 33 44 ~)

425999

4360```

docs/reference/rune/cen/dot.udon+19−5

@@ -7,17 +7,31 @@

88# `%. "cendot"`

10−`[%cndt p=hoon q=hoon]`: call a gate (function), inverted.

10+Call a gate (function), inverted.

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−%-(q p)

17+%. a=hoon b=hoon

1618```

1719

18−## Syntax

20+AST:

21+

22+```

23+[%cndt p=hoon q=hoon]

24+```

1925

20−Regular: *2-fixed*.

26+## Semantics

27+

28+The `%.` rune is for evaluating the `$` arm of a gate, i.e., calling a function. `a` is for the desired sample value (i.e., input value), and `b` is the gate.

29+

30+## Expands to

31+

32+```

33+%-(b=hoon a=hoon)

34+```

2135

2236## Discussion

2337

docs/reference/rune/cen/hep.udon+26−9

@@ -7,25 +7,42 @@

88# `%- "cenhep"`

10−`[%cnhp p=hoon q=hoon]`: call a gate (function).

10+Call a gate (function).

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−%~($ p q)

17+%- a=hoon b=hoon

1618```

1719

18−## Syntax

20+Irregular:

21+

22+```

23+(a=hoon b=hoon)

24+```

25+

26+AST:

1927

20−Regular: *2-fixed*.

28+```

29+[%cnhp p=hoon q=hoon]

30+```

31+

32+## Semantics

33+

34+This rune is for evaluating the `$` arm of a gate, i.e., calling a gate as a function. `a` is the gate, and `b` is the desired sample value (i.e., input value) for the gate.

2135

22−Irregular: `(a)` is `$:a`; `(a b c d)` is `%-(a [b c d])`.

36+## Expands to

37+

38+```

39+%~($ a b)

40+```

2341

2442## Discussion

2543

26−`%-` is used to call a function; `p` is the function ([`gate`](../../bar/tis),

27−`q` the argument. `%-` is a special case of [`%~` ("censig")](../sig), and a gate

28−is a special case of a [door](../../bar/cab).

44+`%-` is used to call a function; `a` is the function ([`gate`](../../bar/tis),

45+`q` the argument. `%-` is a special case of [`%~` ("censig")](../sig), and a gate is a special case of a [door](../../bar/cab).

2946

3047## Examples

3148

docs/reference/rune/cen/ket.udon+17−5

@@ -7,17 +7,29 @@

88# `%^ "cenket"`

10−`[%cnkt p=hoon q=hoon r=hoon s=hoon]`: call with triple sample.

10+Call gate with triple sample.

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−%-(p [q r s])

17+%^ a=hoon b=hoon c=hoon d=hoon

1618```

1719

18−## Syntax

20+AST:

21+

22+```

23+[%cnkt p=hoon q=hoon r=hoon s=hoon]

24+```

25+

26+##

27+

28+## Expands to

1929

20−Regular: *4-fixed*.

30+```

31+%-(a=hoon [b=hoon c=hoon d=hoon])

32+```

2133

2234## Examples

2335

docs/reference/rune/cen/lus.udon+19−5

@@ -7,17 +7,31 @@

88# `%+ "cenlus"`

10−`[%cnls p=hoon q=hoon r=hoon]`: call gate with a cell sample.

10+Call gate with a cell sample.

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−%-(p [q r])

17+%+ a=hoon b=hoon c=hoon

1618```

1719

18−## Syntax

20+AST:

21+

22+```

23+[%cnls p=hoon q=hoon r=hoon]

24+```

1925

20−Regular: *3-fixed*.

26+## Semantics

27+

28+A `%+` expression is for calling a gate with a cell sample. `a` is the gate to be called, `b` is for the head of the sample, and `c` is for the sample tail.

29+

30+## Expands to

31+

32+```

33+%-(a=hoon [b=hoon c=hoon])

34+```

2135

2236## Examples

2337

docs/reference/rune/cen/sig.udon+33−15

@@ -7,33 +7,51 @@

88# `%~ "censig"`

10−`[%cnsg p=wing q=hoon r=(list hoon)]`: call an arm in a door.

10+Evaluate an arm in a door.

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−=+ a=q

16−=<(p %=(a +6 r))

17−```

17+%~ a=wing b=hoon

18+ c=hoon

19+ d=hoon

20+ ...

21+ e=hoon

22+==

1823

19−> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject. It's shown here because `%=` requires a `wing`.

24+Irregular:

2025

21−## Syntax

26+`~(a b c)` is `%~(a b c)`.

27+`~(a b c d e)` is `%~(a b [c d e])`.

28+

29+AST:

2230

23−Regular: *3-fixed*.

31+```

32+[%cnsg p=wing q=hoon r=(list hoon)]

33+```

34+

35+## Semantics

2436

25−Irregular: `~(a b c)` is `%~(a b c)`; `~(a b c d e)` is `%~(a b

26−[c d e])`.

37+A `%~` expression evaluates the arm of a door (i.e., a core with a sample). `a` is a wing that resolves to the arm from within the door in question. `b` is the door itself. If there is only one subexpression after `b`, `c`, then the product of `c` becomes the door's sample value. If there are multiple subexpressions after `b`, their products are made into a cell, `[c d ... e]`, and that becomes the door's sample value.

2738

2839## Discussion

2940

30−`%~` ("censig") is the general case of a function call, `%-` ("cenhep"). In

31−both, we replace the sample (`+6`) of a core. In `%-` the

32−core is a gate and the `$` arm is evaluated. In `%~` the

33−core is a door and any arm may be evaluated. You must identify the arm to be run: `%~(arm door arg)`.

41+`%~` is the general case of a function call, `%-`. In both, we replace the sample (`+6`) of a core. In `%-` the core is a gate and the `$` arm is evaluated. In `%~` the core is a door and any arm may be evaluated. You must identify the arm to be run: `%~(arm door arg)`.

3442

3543See also [`|_`](../../bar/cab).

3644

3745## Examples

3846

39−See [`|_`](../../bar/cab).

47+```

48+> =mycore |_ a=@

49+ ++ plus-two (add 2 a)

50+ ++ double (mul 2 a)

51+ --

52+> ~(plus-two mycore 10)

53+12

54+

55+> ~(double mycore 10)

56+20

57+```

docs/reference/rune/cen/tar.udon+39−16

@@ -7,40 +7,63 @@

88# `%* "centar"`

10−`[%cntr p=wing q=hoon r=(list (pair wing hoon))]`: make with arbitrary expression.

10+Evaluate an expression, then resolve a wing with changes.

1111

12−## Expands to

12+## Syntax

13+

14+Regular:

1315

1416```

15−=+ q

16−%= p

17−r

17+%* a=wing b=hoon

18+ c=wing d=hoon

19+ e=wing f=hoon

20+ ...

21+ g=wing h=hoon

22+==

1823```

1924

20−## Syntax

25+AST:

2126

22−Regular: *2-fixed*, then *jogging*.

27+```

28+[%cntr p=wing q=hoon r=(list (pair wing hoon))]

29+```

2330

24−## Discussion

31+## Semantics

2532

26−`%*` makes a limb from an expression, with changes. It's useful when you want

27−evaluate an expression, pull out a single limb from the result,

28−and then change some parts of the limb before using it.

33+A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolves a wing of of that result, with changes. `a` is the wing to be resolved, and one or more changes is defined by the subexpressions after `b`.

34+

35+## Expands to

36+

37+```

38+=+ b=hoon

39+%= a=wing

40+ c=wing d=hoon

41+ e=wing f=hoon

42+ ...

43+ g=wing h=hoon

44+==

45+```

2946

3047## Examples

3148

3249```

33−~zod:dojo> %*($ add a 2, b 3)

50+> %*($ add a 2, b 3)

34515

3552

36−~zod:dojo> =foo [a=1 b=2 c=3 d=4]

53+> %*(b [a=[12 14] b=[c=12 d=44]] c 11)

54+[c=11 d=44]

55+

56+> %*(b [a=[12 14] b=[c=12 d=44]] c 11, d 33)

57+[c=11 d=33]

58+

59+> =foo [a=1 b=2 c=3 d=4]

3760

38−~zod:dojo> %*(+ foo c %hello, d %world)

61+> %*(+ foo c %hello, d %world)

3962[b=2 c=%hello d=%world]

4063

41−~zod:dojo> =+(foo=[a=1 b=2 c=3] foo(b 7, c 10))

64+> =+(foo=[a=1 b=2 c=3] foo(b 7, c 10))

4265[a=1 b=7 c=10]

4366

44−~zod:dojo> %*(foo [foo=[a=1 b=2 c=3]] b 7, c 10)

67+> %*(foo [foo=[a=1 b=2 c=3]] b 7, c 10)

4568[a=1 b=7 c=10]

4669```

docs/reference/rune/cen/tis.udon+29−10

@@ -7,25 +7,44 @@

88# `%= "centis"`

10−`[%cnts p=wing q=(list (pair wing hoon))]`: resolve a wing with changes.

10+Resolve a wing with changes.

1111

12−## Produces

12+## Syntax

13+

14+Regular:

15+

16+```

17+%= a=wing

18+ b=wing c=hoon

19+ d=wing e=hoon

20+ ...

21+ f=wing g=hoon

22+==

23+```

1324

14−Product of resolution to `p`, modified by the change list `q`.

25+Irregular:

1526

16−If `p` resolves to a leg, `q` is a list of changes to that leg. The modified leg is returned. If `p` resolves to an arm, `q` is a list of changes to the core containing that arm. The arm is computed with the modified core as the subject, and the product is returned.

27+`foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.

1728

18−## Syntax

29+AST:

30+

31+```

32+[%cnts p=wing q=(list (pair wing hoon))]

33+```

34+

35+## Semantics

36+

37+A `%=` expression resolves a wing of the subject, but with changes made.

1938

20−Regular: *1-fixed*, then *jogging*.

39+If `a` resolves to a leg, a series of changes are made to wings of that leg (`b`, `d`, and `f` above are replaced with the respective products of `c`, `e`, and `g` above). The modified leg is returned.

2140

22−Irregular: `foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.

41+If `a` resolves to an arm, a series of changes are made to wings of the parent core of that arm. (Again, `b`, `d`, and `f` are replaced with the respective products of `c`, `e`, and `g`.) The arm is computed with the modified core as the subject, and the product is returned.

2342

2443## Discussion

2544

26−Note that `p` is a wing, not just any expression. Knowing that a function

27−call `(foo baz)` involves making `foo`, replacing its sample

28−at slot `+6` with `baz`, and resolving to the `$` limb, you might think

45+Note that `a` is a wing, not just any expression. Knowing that a function

46+call `(foo baz)` involves evaluating `foo`, replacing its sample

47+at slot `+6` with `baz`, and then resolving to the `$` limb, you might think

2948`(foo baz)` would mean `%=(foo +6 baz)`.

3049

3150But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is