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

git.iko.soy/urbit.org

revisions to bar runes

commit568abcd2f5bd4e8831574a161f54d172120d789b authorjoshuareagan <joshuareagan@gmail.com> dateWed 10 Oct 2018, 14:36 (8 years ago) parentfc1a9ce

9 files changed+47−38

compare with master

unifiedsplit

docs/reference/rune/bar/cab.udon+6−10 docs/reference/rune/bar/cen.udon+4 docs/reference/rune/bar/col.udon+3−1 docs/reference/rune/bar/dot.udon+4−2 docs/reference/rune/bar/hep.udon+5−8 docs/reference/rune/bar/ket.udon+6−3 docs/reference/rune/bar/tar.udon+10−8 docs/reference/rune/bar/tis.udon+8−6 docs/reference/rune/bar/wut.udon+1

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

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

11:- :~ navhome/'/docs/'

22 next/'true'

33 sort/'5'

4− title/'|= "barcab"'

4+ title/'|_ "barcab"'

55 ==

66;>

88# `|_ "barcab"`

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

1111with a sample.

1212

1313## Expands to

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

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

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

2929

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

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

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

33−structure becomes a door.

30+Calling 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)`.

3432

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

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

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

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

3935

4036## Examples

4137

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

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

1919

2020## Discussion

2121

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+

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

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

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

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

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

88# `|: "barcol"`

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.

1111

1212## Expands to

1313

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

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

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

2323

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+

2426## Syntax

2527

2628Regular: *2-fixed*.

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

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

2222

2323## Discussion

2424

25−A trap is a deferred computation.

25+A trap is used to defer a computation.

2626

2727## Examples

2828

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

3030

3131```

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

33+

3334~zod:dojo> $:foo

343542

36+

3537~zod:dojo> (foo)

363842

3739```

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

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

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

5557

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

88# `|- "barhep"`

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

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

1111

1212## Expands to

1313

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

2121

2222## Discussion

2323

24−The `|-` ("barhep") 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 `$()`.

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

2726

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

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

30− the subject.

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

3128

3229## Examples

3330

34−A trivial loop doesn't even recurse:

31+A trivial computation doesn't recurse:

3532

3633```

3734~zod:dojo> |-(42)

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

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

88# `|^ "barket"`

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

11−anonymous arm `$` and kick it.

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

1211

1312## Expands to

1413

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

2423

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

2625

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+

2730## Examples

2831

29−A trivial cork:

32+A trivial example:

3033

3134```

3235~zod:dojo> |^

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

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

88# `|* "bartar"`

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.

1111

1212## Expands to

1313

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

2626## Discussion

2727

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

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

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

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

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

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

3232

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

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

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

34+you know what you're doing.

3535

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

3737with `$()`.

3838

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

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

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

4140

4241## Examples

4342

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

4544

4645```

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

47+

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

49+

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

5051[6.778.724 7.627.107]

52+

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

5254[%dog %cat]

5355```

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

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

88# `|= "bartis"`

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.

1111

1212## Expands to

1313

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

2323

2424## Discussion

2525

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+

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

2830

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

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

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

3132

3233## Examples

3334

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

3536

3637```

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

39+

3840~zod:dojo> (foo 20)

394121

4042```

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

4446```

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

4648 (add a b)

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

48−420

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

50+430

4951```

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

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

2828```

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

3030<1?pqz $~>

31+

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

3233nest-fail

3334```