568abcd · urbit.org · git.iko.soy

docs/reference/rune/bar/cab.udon+6−10

compare with master

unifiedsplit

@@ -1,13 +1,13 @@

1:- :~ navhome/'/docs/'

2 next/'true'

3 sort/'5'

4− title/'|= "barcab"'

4+ title/'|_ "barcab"'

5 ==

6;>

7

8# `|_ "barcab"`

9

10−`[%brcb p=spec q=(map term hoon)]`: form a door, a many-armed core

10+`[%brcb p=spec q=(map term hoon)]`: produce a door, a many-armed core

11with a sample.

12

13## Expands to

@@ -27,15 +27,11 @@ Regular: *1-fixed*, then *battery*.

27A door is the general case of a gate (function). A gate is a

28door with only one arm, which has the empty name `$`.

29

30−Other languages have no real equivalent of a door, but we often

30+Calling a door is like calling a gate except the caller also needs

31−see the pattern of multiple functions with the same argument

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

32−list, or with shared argument structure. In Hoon, this shared

33−structure becomes a door.

34

32

35−Calling a door is just like calling a gate, but the caller needs

36−to specify the arm. For instance, to call the gate `foo` as a

37−door, instead of `(foo bar)` we would write `~($ foo bar)`. This

33+Because 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

38−is an irregular form for `%~($ foo bar)`, ["censig"](../../cen/sig).

34+is an irregular form for `%~($ foo baz)`, [%~](../../cen/sig).

39

35

40## Examples

36## Examples

41

37

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

@@ -19,6 +19,10 @@ Regular: *battery*.

19

20## Discussion

21

22+A core is a cell of `[battery payload]`, where the `battery` is code and the `payload` is data. The `battery` is one or more arms. An arm is a computation that takes the core itself as its subject.

23+

24+The `|%` rune is used to construct a core from a series of arm definitions. Each arm definition in the expression begins with an arm rune (`++`, `+$`, or `+*`). These arms make up the `battery`. The subject of the `|%` expression is used to make the core's `payload`.

25+

22A core is like an "object" in a conventional language, but its

26A core is like an "object" in a conventional language, but its

23attributes (_arms_) are functions on the core, not the core and

27attributes (_arms_) are functions on the core, not the core and

24an argument. A "method" on a core is an arm producing a gate.

28an argument. A "method" on a core is an arm producing a gate.

docs/reference/rune/bar/col.udon+3−1

@@ -7,7 +7,7 @@

7

8# `|: "barcol"`

9

10−`[%brcl p=hoon q=hoon]`: form a gate with burnt sample.

10+`[%brcl p=hoon q=hoon]`: form a gate with a custom sample.

11

12## Expands to

13

@@ -21,6 +21,8 @@

21Pick your own default value for the sample. Note that `p` is an ordinary expression, not a type; `|:` doesn't bunt a sample as

22[`|=`](../tis) does.

23

24+This 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+

24## Syntax

26## Syntax

25

27

26Regular: *2-fixed*.

28Regular: *2-fixed*.

docs/reference/rune/bar/dot.udon+4−2

@@ -22,7 +22,7 @@ Regular: *1-fixed*.

22

23## Discussion

24

25−A trap is a deferred computation.

25+A trap is used to defer a computation.

26

27## Examples

28

@@ -30,8 +30,10 @@ A trivial trap:

30

31```

32~zod:dojo> =foo |.(42)

33+

33~zod:dojo> $:foo

34~zod:dojo> $:foo

3442

3542

36+

35~zod:dojo> (foo)

37~zod:dojo> (foo)

3642

3842

37```

39```

@@ -53,4 +55,4 @@ A more interesting trap:

53Note that we can use `$()` to recurse back into the

55Note that we can use `$()` to recurse back into the

54trap, since it's a core with an `$` arm.

56trap, since it's a core with an `$` arm.

55

57

56−> `$()` expands to `%=($)` (["centis"](../../cen/tis)), accepting a *jogging* body containing a list of changes to the subject.

58+> `$()` expands to `%=($)` (["centis"](../../cen/tis)).

docs/reference/rune/bar/hep.udon+5−8

@@ -7,7 +7,7 @@

7

8# `|- "barhep"`

9

10−`[%brhp p=hoon]`: form a trap and kick ("*call*") it.

10+`[%brhp p=hoon]`: form a trap and evaluate it.

11

12## Expands to

13

@@ -21,17 +21,14 @@ Regular: *1-fixed*.

21

22## Discussion

23

24−The `|-` ("barhep") rune can be thought of as a "recursion

24+The `|-` rune can be thought of as a 'recursion

25−point". Since `|-` makes a `|.` (["bardot"](../dot), a core

26−with one arm named `$`, we can recurse back into it with `$()`.

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

27

26

28−> `$()` expands to `%=($)` (["centis"](../../cen/tis)),

27+> `$()` expands to `%=($)` (["centis"](../../cen/tis)).

29− accepting a *jogging* body containing a list of changes to

30− the subject.

31

28

32## Examples

29## Examples

33

30

34−A trivial loop doesn't even recurse:

31+A trivial computation doesn't recurse:

35

32

36```

33```

37~zod:dojo> |-(42)

34~zod:dojo> |-(42)

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

@@ -7,8 +7,7 @@

7

8# `|^ "barket"`

9

10−`[%brkt p=hoon q=(map term hoon)]`: form a core with battery and

10+`[%brkt p=hoon q=(map term hoon)]`: form a core whose battery includes a `$` arm `$`, and compute the latter.

11−anonymous arm `$` and kick it.

12

11

13## Expands to

12## Expands to

14

13

@@ -24,9 +23,13 @@ $

24

23

25Regular: *1-fixed*, then *battery*.

24Regular: *1-fixed*, then *battery*.

26

25

26+## Discussion

27+

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.

29+

27## Examples

30## Examples

28

31

29−A trivial cork:

32+A trivial example:

30

33

31```

34```

32~zod:dojo> |^

35~zod:dojo> |^

docs/reference/rune/bar/tar.udon+10−8

@@ -7,7 +7,7 @@

7

8# `|* "bartar"`

9

10−`[%brtr p=spec q=hoon]`: form a gill, a wet one-armed core with sample.

10+`[%brtr p=spec q=hoon]`: produce a wet one-armed core with sample.

11

12## Expands to

13

@@ -26,18 +26,17 @@ Regular: *2-fixed*.

26## Discussion

27

28In a normal (dry) gate, your argument is converted into the

29−sample type. In a generic (wet) gate or gill, your argument type

29+sample type. In a generic (wet) gate, your argument type

30−passes through the function, rather as if it was a macro (there

30+passes through the function, rather as if it were a macro (there

31is still only one copy of the code, however).

32

33−Genericity is a powerful and dangerous tool. Use gills only if

33+Genericity is a powerful and dangerous tool. Use wet gates only if

34−you think you know what you're doing.

34+you know what you're doing.

35

36−Just as with a [gate](../tis), we can recurse back into a gill

36+Just as with a [gate](../tis), we can recurse back into a wet gate

37with `$()`.

38

39−> `$()` expands to `%=($)` (["centis"](../../cen/tis)), accepting

39+> `$()` expands to `%=($)` (["centis"](../../cen/tis)).

40−> a *jogging* body containing a list of changes to the subject.

41

40

42## Examples

41## Examples

43

42

@@ -45,9 +44,12 @@ Wet and dry gates in a nutshell:

45

44

46```

45```

47~zod:dojo> =foo |=([a=* b=*] [b a])

46~zod:dojo> =foo |=([a=* b=*] [b a])

47+

48~zod:dojo> =bar |*([a=* b=*] [b a])

49+

49~zod:dojo> (foo %cat %dog)

50~zod:dojo> (foo %cat %dog)

50[6.778.724 7.627.107]

51[6.778.724 7.627.107]

52+

51~zod:dojo> (bar %cat %dog)

53~zod:dojo> (bar %cat %dog)

52[%dog %cat]

54[%dog %cat]

53```

55```

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

@@ -7,7 +7,7 @@

7

8# `|= "bartis"`

9

10−`[%brts p=model q=hoon]`: form a gate, a dry one-armed core with sample.

10+`[%brts p=spec q=hoon]`: form a gate, a dry one-armed core with sample.

11

12## Expands to

13

@@ -23,11 +23,12 @@ Regular: *2-fixed*.

23

24## Discussion

25

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.

27+

26A gate is a core with one arm named `$`, so, just as with

28A gate is a core with one arm named `$`, so, just as with

27−[`|-` ("barhep")](../hep), we can recurse back into it with `$()`.

29+[`|-`](../hep), we can recurse back into it with `$()`.

28

30

29−> `$()` expands to `%=($)` (["centis"](../../cen/tis)), accepting

31+> `$()` expands to `%=($)` (["centis"](../../cen/tis)).

30−> a *jogging* body containing a list of changes to the subject.

31

32

32## Examples

33## Examples

33

34

@@ -35,6 +36,7 @@ A trivial gate:

35

36

36```

37```

37~zod:dojo> =foo |=(a=@ +(a))

38~zod:dojo> =foo |=(a=@ +(a))

39+

38~zod:dojo> (foo 20)

40~zod:dojo> (foo 20)

3921

4121

40```

42```

@@ -44,6 +46,6 @@ A slightly less trivial gate:

44```

46```

45~zod:dojo> =foo |= [a=@ b=@]

47~zod:dojo> =foo |= [a=@ b=@]

46 (add a b)

48 (add a b)

47−~zod:dojo> (foo 20 400)

49+~zod:dojo> (foo 30 400)

48−420

50+430

49```

51```

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

@@ -28,6 +28,7 @@ See this [discussion of the core variance model](../../../advanced).

28```

29~zod:dojo> => ~ ^+ |?(%a) |.(%a)

30<1?pqz $~>

31+

31~zod:dojo> => ~ ^+ |?(%a) |.(%b)

32~zod:dojo> => ~ ^+ |?(%a) |.(%b)

32nest-fail

33nest-fail

33```

34```