2c2ed59 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

rewrites section on nested cores (#710)

2c2ed59poprox7 years ago

tutorials/hoon/arms-and-cores.md+148−13

compare with master

unifiedsplit

@@ -181,7 +181,7 @@ To reinforce your newfound understanding of arms and cores, let's go over the va

181

182### Address-Based Wings

183

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.

185

186Let's use `-.c` to look at the head of `c`, i.e., the battery of the core:

187

@@ -299,7 +299,7 @@ Hoon doesn't know whether `double` is a face or an arm name until it conducts a

29924

300```

301

302−### Modifying a Core

302+### Modifying a Core's Payload

303

304We 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)`:

305

@@ -391,6 +391,46 @@ So the meaning of `two.double.c` is, roughly, '`two` in the parent core of `doub

391

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

393

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+

394### Evaluating an Arm Against a Modified Core

434### Evaluating an Arm Against a Modified Core

395

435

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

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

410

450

411Let'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.

451Let'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.

412

452

413−```hoon

453+```

414> =dec |%

454> =dec |%

415 ++ dec

455 ++ dec

416 |= a=@

456 |= a=@

@@ -420,7 +460,6 @@ Let's take a quick look at the battery of one core in the dojo to show that this

420 ?: =(a +(b)) b

460 ?: =(a +(b)) b

421 $(b +(b))

461 $(b +(b))

422 --

462 --

423−

424```

463```

425

464

426This core has one arm `dec` which implements decrement. If we look at the head of the core we'll see the Nock.

465This 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

449

488

450Again, being able to read Nock is not essential to understanding Hoon.

489Again, being able to read Nock is not essential to understanding Hoon.

451

490

491+### Core Nesting

492+

452−Let's take a quick look at how cores can be combined to build up larger structures.

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.

453

494

454```hoon

495```hoon

455=>

496=>

456|%

497|%

457−++ dec

498+++ foo

458 |= a=@

499 |= a=@

459− ?< =(0 a)

500+ (mul a 2)

460− =+ b=0

461− |- ^- @

462− ?: =(a +(b)) b

463− $(b +(b))

464--

501--

465|%

502|%

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

466++ add

530++ add

531+ ~/ %add

532+ :: unsigned addition

533+ ::

534+ :: a: augend

535+ :: b: addend

467 |= [a=@ b=@]

536 |= [a=@ b=@]

537+ :: sum

468 ^- @

538 ^- @

469 ?: =(0 a) b

539 ?: =(0 a) b

470 $(a (dec a), b +(b))

540 $(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])

471--

554--

472```

555```

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

473

562

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

475

610

476## Casts

611## Casts

477

612

@@ -488,4 +623,4 @@ You can now unbind `c` in the dojo -- this will help to keep your dojo subject t

488

623

489> c

624> c

490-find.c

625-find.c

491−```

626+```

tutorials/hoon/doors.md−39

@@ -81,45 +81,6 @@ Let's try out these arms, using them for function calls:

82Notice 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.

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−

123### Mutating a Gate

84### Mutating a Gate

124

125Let'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:

86Let'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: