on master help sign in
Merge pull request #887 from urbit/nesting-context

Hoon school lesson on =>

commit7b55239d778de7dc6f99ca4acfe21ae07623369d authorpoprox <51337059+syzygyzer@users.noreply.github.com> dateTue 23 Jun 2020, 14:13 (6 years ago) parent50f38a45c56367
1 file changed+36−10
tutorials/hoon/arms-and-cores.md+36−10
tutorials/hoon/arms-and-cores.md+36−10
@@ -99,7 +99,7 @@ First let's use the dojo to bind the face `a` to the value `12`, and the face `b
9999
100100Now use the following multi-line expression to bind `c` to a core. As before, feel free to cut and paste the following expression into the dojo (starting at `=c`):
101101
102−```hoon
102+```
103103> =c |%
104104 ++ two 2
105105 ++ inc (add 1 a)
@@ -215,7 +215,7 @@ The result is a tree of uncomputed Nock formulas. But you virtually never need
215215
216216To get the arm of a core to compute you must use its name. The arm names of `c` are in the expression used to create `c`:
217217
218−```hoon
218+```
219219> =c |%
220220 ++ two 2
221221 ++ inc (add 1 a)
@@ -488,10 +488,25 @@ This core has one arm `dec` which implements decrement. If we look at the head o
488488
489489Again, being able to read Nock is not essential to understanding Hoon.
490490
491−### Core Nesting
491+### Cores and Contexts
492492
493−Let's take a quick look at how cores can be combined with `=>` to build up larger structures. `=> p=hoon q=hoon` allows you to take the product of `q` with the product of `p` taken as the subject.
493+Let's take a quick look at how cores can be combined with `=>` to build up
494+larger structures. `=> p=hoon q=hoon` yields the product of `q` with the product of `p` taken as the subject.
494495
496+We can use this to set the context of cores. Recall that the payload of a gate
497+is a cell of `[sample context]`. For example:
498+```
499+~zod:dojo> =foo =>([1 2] |=(@ 15))
500+> +3:foo
501+[0 1 2]
502+```
503+Here we have created a gate with `[1 2]` as its context that takes in an `@` and
504+returns `15`. `+3:foo` shows the payload of the core to be `[0 [1 2]]`. Here `0`
505+is the default value of `@` and is the sample, while `[1 2]` is the context that
506+was given to `foo`.
507+
508+`=>` (and its reversed version `=<`) are used extensively to put cores into the
509+context of other cores.
495510```hoon
496511=>
497512|%
@@ -505,9 +520,15 @@ Let's take a quick look at how cores can be combined with `=>` to build up large
505520 (mul (foo a) 2)
506521--
507522```
508−In this core, `foo` is in the subject of `bar`, and so `bar` is able to call `foo`. On the other hand, `bar` is not in the subject of `foo`, so `foo` cannot call `bar` - you will get a `-find.bar` error.
523+At the level of arms, `+foo` is in the subject of `+bar`, and so `+bar` is able to call `+foo`. On the other hand, `+bar` is not in the subject of `+foo`, so `+foo` cannot call `+bar` - you will get a `-find.bar` error.
524+
525+At the level of cores, the `=>` sets the context of the core containing `+bar` to be the core
526+containing `+foo`. Recall that arms are evaluated with the parent core as the
527+subject. Thus `+bar` is evaluated with the core containing it as the subject,
528+which has the core containing `+foo` in its context. So this is why `+foo` is in
529+the scope of `+bar` but not vice versa.
509530
510−Let's take a look inside of `hoon.hoon`, where the standard library is located, to see how this is being used.
531+Let's look inside `hoon.hoon`, where the standard library is located, to see how this is being used.
511532
512533The first core listed here has just one arm.
513534```hoon
@@ -553,12 +574,13 @@ and so on, down to
553574 $@(~ [~ u=item])
554575--
555576```
556−This core contains the arms in parts [1a-1c of the standard library documentation](@/docs/reference/library/1a.md). If you count them, there are 41 arms in the core from `++ add` down to `++ unit`. We again can see this fact reflected in the Dojo by looking at the subject of `add`.
577+This core contains the arms in parts [1a-1c of the standard library documentation](@/docs/reference/library/1a.md). If you count them, there are 41 arms in the core from `++ add` down to `++ unit`. We again can see this fact reflected in the dojo by looking at the subject of `add`.
557578```
558579> ..add
559580<41.mac 1.ane $141>
560581```
561−Now though, we see that the section 1 core is contained within the core containing `hoon-version`.
582+Here we see that core containing `hoon-version` is in the subject of the
583+section one core.
562584
563585Next, [section two](@/docs/reference/library/2a.md) starts:
564586```
@@ -603,10 +625,14 @@ Lastly, let's check the subject of the last arm in `hoon.hoon` (as of November 2
603625> ..pi-tell
604626<92.nnn 247.tye 51.mvt 126.xjf 41.mac 1.ane $141>
605627```
606−This confirms for us, then, that `hoon.hoon` consists of six nested cores, with the `hoon-version` core at the top.
628+This confirms for us, then, that `hoon.hoon` consists of six nested cores, with one
629+inside the payload of the next, with
630+the `hoon-version` core most deeply nested.
607631
608632#### Exercise 1.7a
609−Pick a couple of arms in `hoon.hoon` and check to make sure that they are only referenced in the layer they exist in or a deeper layer. This is easily accomplished with `Ctrl-F`.
633+Pick a couple of arms in `hoon.hoon` and check to make sure that they are only
634+referenced in its parent core or core(s) that have the parent core put in its
635+context via the `=>` or `=<` runes.
610636
611637## Casts
612638