bd9ebd1 · urbit.org · git.iko.soy

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

compare with master

unifiedsplit

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

15

16```

17|_ a=spec

18−++ name-1 b=hoon

18+++ b=term c=hoon

19−++ name-2 c=hoon

19+++ d=term e=hoon

20 ...

21−++ name-n d=hoon

21+++ f=term g=hoon

22--

23```

24

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

34

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

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.

38

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

40

41## Expands to

42

43```

44−=| a

44+=| a=spec

45|%

46−++ name-1 b

46+++ b=term c=hoon

47−++ name-2 c

47+++ d=term e=hoon

48 ...

49−++ name-n d

49+++ f=term g=hoon

50--

51```

52

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

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

15

16```

17|%

18−++ name-1 a=hoon

18+++ a=term b=hoon

19−++ name-2 b=hoon

19+++ c=term d=hoon

20 ...

21−++ name-n c=hoon

21+++ e=term f=hoon

22--

23```

24

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

34

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

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.

38

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

40

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

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

32## Expands to

33

34```

35−|% ++ $ a

35+|% ++ $ a=hoon

36--

37```

38

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

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

30## Expands to

31

32```

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

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

34```

35

36## Discussion

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

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

15

16```

17|^ a=hoon

18−++ name-1 b=hoon

18+++ b=term c=hoon

19−++ name-2 c=hoon

19+++ d=term e=hoon

20 ...

21−++ name-n d=hoon

21+++ f=term g=hoon

22--

23```

24

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

26+

25AST:

27AST:

26

28

27```

29```

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

37```

39```

38=> |%

40=> |%

39 ++ $ a=hoon

41 ++ $ a=hoon

40− ++ name-1 b=hoon

42+ ++ b=term c=hoon

41− ++ name-2 c=hoon

43+ ++ d=term e=hoon

42 ...

44 ...

43− ++ name-n d=hoon

45+ ++ f=term g=hoon

44 --

46 --

45$

47$

46```

48```

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.

31## Expands to

32

33```

34−=| a

34+=| a=spec

35−|% ++ $ b

35+|% ++ $ b=hoon

36--

37```

38

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

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

15

16```

17|@

18−++ name-1 a=hoon

18+++ a=term b=hoon

19−++ name-2 b=hoon

19+++ c=term d=hoon

20 ...

21−++ name-n c=hoon

21+++ e=term f=hoon

22--

23```

24

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

32

33## Semantics

34

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

36

37## Discussion

38

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

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

25

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.

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.

29

30## Expands to

31

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

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

7

8# `%_ "cencab"`

9

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

10+Resolve a wing with changes, preserving type.

11

12−## Expands to

12+## Syntax

13+

14+Regular, tall:

13

15

14```

16```

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

17+%_ a=wing

18+ b=wing c=hoon

19+ d=wing e=hoon

20+ ...

21+ f=wing g=hoon

22+==

16```

23```

17

24

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

19

38

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+```

21

46

22## Discussion

47## Discussion

23

48

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

25

52

26## Examples

53## Examples

27

54

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

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

7

8# `%: "cencol"`

9

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

10+Call a gate with many arguments.

11

12## Syntax

13

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

14+Regular:

15

16```

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

17+%: a=hoon

18+ b=hoon

19+ c=hoon

20+ ...

21+ d=hoon

22+==

18```

23```

19

24

20−## Discussion

25+AST:

26+

27+```

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

29+```

21

30

31+## Semantics

32+

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.

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

23

36

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

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

25

38

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

29> %: add 22 33 ==

42> %: add 22 33 ==

3055

4355

31

44

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

45+> =adder |= a=*

33 =+ c=0

46 =+ c=0

34 |-

47 |-

35− ?~ a c

48+ ?@ a (add a c)

49+ ?^ -.a !!

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

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

37

51

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

52+> %: adder 22 33 44 ==

3999

5399

40

54

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

56+154

57+

41> %:(adder 22 33 44 ~)

58> %:(adder 22 33 44 ~)

4299

5999

43```

60```

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

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

7

8# `%. "cendot"`

9

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

10+Call a gate (function), inverted.

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

15−%-(q p)

17+%. a=hoon b=hoon

16```

18```

17

19

18−## Syntax

20+AST:

21+

22+```

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

24+```

19

25

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+```

21

35

22## Discussion

36## Discussion

23

37

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

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

7

8# `%- "cenhep"`

9

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

10+Call a gate (function).

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

15−%~($ p q)

17+%- a=hoon b=hoon

16```

18```

17

19

18−## Syntax

20+Irregular:

21+

22+```

23+(a=hoon b=hoon)

24+```

25+

26+AST:

19

27

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.

21

35

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

36+## Expands to

37+

38+```

39+%~($ a b)

40+```

23

41

24## Discussion

42## Discussion

25

43

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

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

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

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

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

29

46

30## Examples

47## Examples

31

48

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

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

7

8# `%^ "cenket"`

9

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

10+Call gate with triple sample.

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

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

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

16```

18```

17

19

18−## Syntax

20+AST:

21+

22+```

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

24+```

25+

26+##

27+

28+## Expands to

19

29

20−Regular: *4-fixed*.

30+```

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

32+```

21

33

22## Examples

34## Examples

23

35

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

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

7

8# `%+ "cenlus"`

9

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

10+Call gate with a cell sample.

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

15−%-(p [q r])

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

16```

18```

17

19

18−## Syntax

20+AST:

21+

22+```

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

24+```

19

25

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+```

21

35

22## Examples

36## Examples

23

37

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

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

7

8# `%~ "censig"`

9

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

10+Evaluate an arm in a door.

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

15−=+ a=q

17+%~ a=wing b=hoon

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

18+ c=hoon

17−```

19+ d=hoon

20+ ...

21+ e=hoon

22+==

18

23

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:

20

25

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:

22

30

23−Regular: *3-fixed*.

31+```

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

33+```

34+

35+## Semantics

24

36

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

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.

26−[c d e])`.

27

38

28## Discussion

39## Discussion

29

40

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

34

42

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

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

36

44

37## Examples

45## Examples

38

46

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 @@

7

8# `%* "centar"`

9

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.

11

12−## Expands to

12+## Syntax

13+

14+Regular:

13

15

14```

16```

15−=+ q

17+%* a=wing b=hoon

16−%= p

18+ c=wing d=hoon

17−r

19+ e=wing f=hoon

20+ ...

21+ g=wing h=hoon

22+==

18```

23```

19

24

20−## Syntax

25+AST:

21

26

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

27+```

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

29+```

23

30

24−## Discussion

31+## Semantics

25

32

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

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

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

34+

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

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+```

29

46

30## Examples

47## Examples

31

48

32```

49```

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

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

345

515

35

52

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+

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

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

37

60

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

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

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

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

40

63

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

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

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

43

66

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)

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

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

46```

69```

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

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

7

8# `%= "centis"`

9

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

10+Resolve a wing with changes.

11

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+```

13

24

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

25+Irregular:

15

26

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

17

28

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.

19

38

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.

21

40

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.

23

42

24## Discussion

43## Discussion

25

44

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

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

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

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

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

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

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

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

30

49

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

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