on master help sign in
rewrites section on nested cores (#710)

* exercise 1.7a (incomplete) * exercise 1.7b, no soln * emphasizes use of => * rewrite section on composing cores * shows core containment in dojo * moves content on .. from doors to arms and cores

commit2c2ed59a7550774cb59e236be85061f56f72779c authorpoprox <51337059+syzygyzer@users.noreply.github.com> dateThu 21 Nov 2019, 15:51 (7 years ago) parentb9144b2
2 files changed+148−52
tutorials/hoon/arms-and-cores.md+148−13 tutorials/hoon/doors.md−39
tutorials/hoon/arms-and-cores.md+148−13
@@ -181,7 +181,7 @@ To reinforce your newfound understanding of arms and cores, let's go over the va
181181
182182### Address-Based Wings
183183
184−In the last lesson, you saw how the following expressions return legs based on an address in the subject: `+n`, `.`, `-`, `+`, `+>`, `+<`, `->`, `-<`, `&`, `|` etc. When these resolve to the part of the subject containing an arm, they **don't** evaluate the arm. They simply return the indicated noun fragment of the subject, as if it were a leg.
184+In the [previous lesson](@../the-subject-and-its-legs.md), you saw how the following expressions return legs based on an address in the subject: `+n`, `.`, `-`, `+`, `+>`, `+<`, `->`, `-<`, `&`, `|` etc. When these resolve to the part of the subject containing an arm, they **don't** evaluate the arm. They simply return the indicated noun fragment of the subject, as if it were a leg.
185185
186186Let's use `-.c` to look at the head of `c`, i.e., the battery of the core:
187187
@@ -299,7 +299,7 @@ Hoon doesn't know whether `double` is a face or an arm name until it conducts a
29929924
300300```
301301
302−### Modifying a Core
302+### Modifying a Core's Payload
303303
304304We can produce a modified version of the core `c` in which `a` and `b` have different values. A core is just a noun in the subject, so we can modify it in the way we learned to modify legs in the last lesson. To change `a` to `99`, use `c(a 99)`:
305305
@@ -391,6 +391,46 @@ So the meaning of `two.double.c` is, roughly, '`two` in the parent core of `doub
391391
392392In each of the following examples, the only wings that matter are `c` and whichever arm name is left-most in the expression. The other arm names in the path simply resolve to their parent core, which is just `c`.
393393
394+### The `..arm` Syntax
395+
396+Let's say you have a wing that resolves to a leg of the subject. In this wing is an arm name, e.g., `a.b.arm`. As you learned in lesson 1.4, this should be read as '`a` in `b` in the parent core of `arm`'. Speaking more directly: the wing resolution path goes through the parent core of the arm, not the arm itself.
397+
398+Recall that using `.` by itself returns the whole subject. With that in mind, take a moment to answer the following question on your own. In general, what should the expression `..arm` produce?
399+
400+Do you have an answer? If not, consider going back and trying to figure it out before moving on.
401+
402+You may read `..arm` as '`.` of the parent core of `arm`'. This amounts to just the parent core of `arm`. Let's try this out with the arms of `c`:
403+
404+```
405+> ..inc:c
406+< 4.han
407+ { {our/@p now/@da eny/@uvJ}
408+ <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
409+ }
410+>
411+
412+> c
413+< 4.han
414+ { {our/@p now/@da eny/@uvJ}
415+ <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
416+ }
417+>
418+```
419+
420+Yes, they match. `..inc` of `c` is just the parent core of `inc`, `c` itself. But why would we ever use `..inc` to refer to `c`? It's much simpler to use `c`.
421+
422+Sometimes the `..arm` syntax is quite useful. Often there is a core in the subject without a face bound to it; i.e., the core might be nameless. In that case you can use an arm name in that core to refer to the whole core.
423+
424+For an example of this, consider the `add` arm of the Hoon standard library. This arm is in a nameless core. To see the parent core of `add`, try `..add`:
425+
426+```
427+> ..add
428+<74.dbd 1.qct $141>
429+```
430+
431+Here you see a core with a battery of 74 arms (!), and whose payload is another core with one arm.
432+
433+
394434### Evaluating an Arm Against a Modified Core
395435
396436Assume `this.is.a.wing` is a wing that resolves to an arm. You can use the `this.is.a.wing(face new-value)` syntax to compute the arm against a modified version of the parent core of `this.is.a.wing`.
@@ -410,7 +450,7 @@ This almost looks like a function call of sorts.
410450
411451Let's take a quick look at the battery of one core in the dojo to show that this is true by inputting one into the dojo.
412452
413−```hoon
453+```
414454> =dec |%
415455 ++ dec
416456 |= a=@
@@ -420,7 +460,6 @@ Let's take a quick look at the battery of one core in the dojo to show that this
420460 ?: =(a +(b)) b
421461 $(b +(b))
422462 --
423−
424463```
425464
426465This core has one arm `dec` which implements decrement. If we look at the head of the core we'll see the Nock.
@@ -449,29 +488,125 @@ This core has one arm `dec` which implements decrement. If we look at the head o
449488
450489Again, being able to read Nock is not essential to understanding Hoon.
451490
452−Let's take a quick look at how cores can be combined to build up larger structures.
491+### Core Nesting
492+
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.
453494
454495```hoon
455496=>
456497|%
457−++ dec
498+++ foo
458499 |= a=@
459− ?< =(0 a)
460− =+ b=0
461− |- ^- @
462− ?: =(a +(b)) b
463− $(b +(b))
500+ (mul a 2)
464501--
465502|%
503+++ bar
504+ |= a=@
505+ (mul (foo a) 2)
506+--
507+```
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.
509+
510+Let's take a look inside of `hoon.hoon`, where the standard library is located, to see how this is being used.
511+
512+The first core listed here has just one arm.
513+```hoon
514+|%
515+++ hoon-version 141
516+--
517+```
518+This is reflected in the subject of `hoon-version`.
519+```
520+> ..hoon-version
521+<1.ane $141>
522+```
523+
524+After several lines that we'll ignore for pedagogical purposes, we see
525+```hoon
526+|%
527+:: # %math
528+:: unsigned arithmetic
529++| %math
466530++ add
531+ ~/ %add
532+ :: unsigned addition
533+ ::
534+ :: a: augend
535+ :: b: addend
467536 |= [a=@ b=@]
537+ :: sum
468538 ^- @
469539 ?: =(0 a) b
470540 $(a (dec a), b +(b))
541+::
542+++ dec
543+```
544+and so on, down to
545+```hoon
546+++ unit
547+ |$ [item]
548+ :: maybe
549+ ::
550+ :: mold generator: either `~` or `[~ u=a]` where `a` is the
551+ :: type that was passed in.
552+ ::
553+ $@(~ [~ u=item])
471554--
472555```
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`.
557+```
558+> ..add
559+<41.mac 1.ane $141>
560+```
561+Now though, we see that the section 1 core is contained within the core containing `hoon-version`.
473562
474−Here you can see the style of wrapping one core in another. This technique is used frequently in Hoon, particularly in the standard library. `dec` is used in the subsequent core. This can be a useful code organization technique. Gates and Traps are both special kinds of cores, as you will see in later lessons.
563+Next, [section two](@/docs/reference/library/2a.md) starts:
564+```
565+=>
566+:: ::
567+:::: 2: layer two ::
568+```
569+...
570+```
571+|%
572+:: ::
573+:::: 2a: unit logic ::
574+ :: ::
575+ :: biff, bind, bond, both, clap, drop, ::
576+ :: fall, flit, lift, mate, need, some ::
577+ ::
578+++ biff :: apply
579+ |* {a/(unit) b/$-(* (unit))}
580+ ?~ a ~
581+ (b u.a)
582+```
583+If you counted the arms in this core by hand, you'll come up with 126 arms. This is also reflected in the dojo:
584+```
585+> ..biff
586+<126.xjf 41.mac 1.ane $141>
587+```
588+and we also see the section 1 core and the core containing `hoon-version` in the subject.
589+
590+We can also confirm that `add` is in the subject of `biff`
591+```
592+> add:biff
593+<1.vwd {{a/@ b/@} <41.mac 1.ane $141>}>
594+```
595+and that `biff` is not in the subject of `add`.
596+```
597+> biff:add
598+-find.biff
599+```
600+
601+Lastly, let's check the subject of the last arm in `hoon.hoon` (as of November 2019)
602+```
603+> ..pi-tell
604+<92.nnn 247.tye 51.mvt 126.xjf 41.mac 1.ane $141>
605+```
606+This confirms for us, then, that `hoon.hoon` consists of six nested cores, with the `hoon-version` core at the top.
607+
608+#### 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`.
475610
476611## Casts
477612
@@ -488,4 +623,4 @@ You can now unbind `c` in the dojo -- this will help to keep your dojo subject t
488623
489624> c
490625-find.c
491−```
626+```
tutorials/hoon/doors.md−39
@@ -81,45 +81,6 @@ Let's try out these arms, using them for function calls:
8181
8282Notice that each arm in core `c` is able to call the other arms of `c` -- `add-two` uses the `inc` arm to increment a number twice. As a reminder, each arm is evaluated with is parent core as the subject. In the case of `add-two` the parent core is `c`, which has `inc` in it.
8383
84−### The `..arm` Syntax
85−
86−Let's say you have a wing that resolves to a leg of the subject. In this wing is an arm name, e.g., `a.b.arm`. As you learned in lesson 1.4, this should be read as '`a` in `b` in the parent core of `arm`'. Speaking more directly: the wing resolution path goes through the parent core of the arm, not the arm itself.
87−
88−Recall that using `.` by itself returns the whole subject. With that in mind, take a moment to answer the following question on your own. In general, what should the expression `..arm` produce?
89−
90−Do you have an answer? If not, consider going back and trying to figure it out before moving on.
91−
92−You may read `..arm` as '`.` of the parent core of `arm`'. This amounts to just the parent core of `arm`. Let's try this out with the arms of `c`:
93−
94−```
95−> ..inc:c
96−< 4.han
97− { {our/@p now/@da eny/@uvJ}
98− <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
99− }
100−>
101−
102−> c
103−< 4.han
104− { {our/@p now/@da eny/@uvJ}
105− <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
106− }
107−>
108−```
109−
110−Yes, they match. `..inc` of `c` is just the parent core of `inc`, `c` itself. But why would we ever use `..inc` to refer to `c`? It's much simpler to use `c`.
111−
112−Sometimes the `..arm` syntax is quite useful. Often there is a core in the subject without a face bound to it; i.e., the core might be nameless. In that case you can use an arm name in that core to refer to the whole core.
113−
114−For an example of this, consider the `add` arm of the Hoon standard library. This arm is in a nameless core. To see the parent core of `add`, try `..add`:
115−
116−```
117−> ..add
118−<74.dbd 1.qct $141>
119−```
120−
121−Here you see a core with a battery of 74 arms (!), and whose payload is another core with one arm.
122−
12384### Mutating a Gate
12485
12586Let's say you want to modify the default sample of the gate for `double`. We can infer the default sample by calling `double` with no argument: