diff options
Diffstat (limited to 'docs/core-academy/ca01.md')
| -rw-r--r-- | docs/core-academy/ca01.md | 995 |
1 files changed, 995 insertions, 0 deletions
diff --git a/docs/core-academy/ca01.md b/docs/core-academy/ca01.md new file mode 100644 index 0000000..c225119 --- /dev/null +++ b/docs/core-academy/ca01.md @@ -0,0 +1,995 @@ +--- +description: "Core Academy lesson on the Hoon compiler covering vase-mode programming with +slap/+slop algebra, the compilation pipeline from text to AST to Nock, type system mechanics, and Ford file building." +layout: + title: + visible: true + description: + visible: false + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true +--- + +# 2. Building Hoon + +*This lesson explains vase-mode Hoon, including the arms `+slap`, `+slop`, `+slot`, and `+slam`. We examine the compiler stack, and how Ford uses vase mode to process file inclusions.* + +## Vase-Mode Hoon {#vase-mode-hoon} + +A `vase` is a pair `[type noun]` used to describe data of a type unknown at compile time. (For instance, this can result from compiling and running Hoon code.) We use vases throughout the kernel, such as to run userspace agents in Gall or to upgrade Arvo itself. + +What do we mean when we talk about `[type noun]`? Nouns are straightforward but what is a `$type`? + +### `$type` {#type} + +Hoon uses the word “type” a few different ways casually (mold, mark, &c.). `$type` is also a core definition of Hoon, a way of specifying a set of nouns, such as all atoms or all cells. One challenge in interpreting a vase in the Dojo is that the prettyprinter obscures these. Take the type spear of a gate like `+add`, for instance: + +```hoon +> -:!>(add) +#t/<1.otf [[a=@ b=@] <33.sam 1.pnw %139>]> + +> -<:!>(add) +%hold +``` + +**`/sys/hoon.hoon`** + +```hoon ++$ type $~ %noun :: + $@ $? %noun :: any nouns + %void :: no noun + == :: + $% [%atom p=term q=(unit @)] :: atom / constant + [%cell p=type q=type] :: ordered pair + [%core p=type q=coil] :: object + [%face p=$@(term tune) q=type] :: namespace + [%fork p=(set type)] :: union + [%hint p=(pair type note) q=type] :: annotation + [%hold p=type q=hoon] :: lazy evaluation + == :: +``` + +- `%noun` is the superset of all nouns. +- `%void` is the empty noun, but won't occur in practice. +- `%atom` spans the set of all atoms. +- `%cell` contains ordered pairs. + +The other types are more complex: + +- `%core` is the descriptor type for a core. Besides the `$type`, it uses a `$coil`, which is a tuple of variance information, context, and chapters (limbs). +- `%face` spans the same set as nouns but includes a face. +- `%fork` is a union, or choice over options. +- `%hint` is an annotation for the compiler (Nock Eleven). +- `%hold` types are lazily evaluated, such as a recursive type (like the `+list` mold builder). + - `%hold` types are why the compiler can have trouble with lists at runtime, such as needing to distinguish a `lest` or the TMI problem with `+snag` &c. + - A `%hold` type is a “finite subtype” of an infinite type. Hoon doesn't actually know about these directly, just in that it can be lazy about evaluating recursions. + - They result from arms in cores because the `hoon` of the arm is played against the core type as the subject type to get the result. This permits wetness and variance, since the core can be modified to have a sample of a different type. + > One can "evaluate" a hold by asking the compiler to "play" the hoon against the subject type, meaning to infer what type of value would result from running that hoon against a value of the subject type. For a recursive type, this result type refers to the same hold, usually in one or more of the cases of a `%fork`. (~rovnys-ricfer) + +For instance, let's evaluate a value of the type `(list @ud)`. + +```hoon +> =a `(list @ud)`~[1 2 3] + +> !>(a) +[#t/it(@ud) q=[1 2 3 0]] + +> -<:!>(a) +%hold + +> -<:!>(?~(a 0 a)) +%fork + +> ->-:!>(?~(a 0 a)) +#t/@ud +[%atom p=%ud q=~] + +> ->+<:!>(?~(a 0 a)) +l=[#t/[i=@ud t=it(@ud)] l=~ r=~] +``` + +The prettyprinter really wants to gussy these up for you, so you have to play some tricks to see the value unexpurgated: + +```hoon +> ;;($>(%atom type) -:!>(3)) +[%atom p=%ud q=~] + +> ;;($>(?(%core %hold) type) -:!>(dec)) +[ %hold +... +] + +> =+ r=~(repo ut ~(repo ut -:!>(dec))) ?>(?=(%core -.r) r) +[ %core + #t/[a=@ <33.sam 1.pnw %139>] + q + [ p=[p=~ q=%dry r=%gold] + ... + ] +] + +> ?? 4 + [%atom %ud ~] +4 +``` + +A `%hold` can be resolved by one step using `(~(play ut type) hoon)`, which type-infers what the result of running that `hoon` would be against a subject of that `type`. + +```hoon +> =- ?>(?=(%fork -<) -) ~(repo ut -:!>(*(list @))) +[%fork p=[#t/%~ l=[#t/[i=@ t=it(@)] l=~ r=~] r=~]] +``` + +Whenever we talk about `$type`, this is it. This may in some ways feel odd to those coming from other languages, since we can—and often will—talk about the “type of the subject” for instance. That means this head of the vase, or the type used to interpret the associated noun. + +### Building Vases {#building-vases} + +The most common way to get a vase is using the `!>` zapgar rune. + +```hoon +> !>('Hello Mars') +[#t/@t q=545.182.085.650.269.906.691.400] +``` + +A vase can also be manually constructed, e.g. + +```hoon +> `vase`[`type`[%atom %ud `4] 4] +[#t/%4 q=4] +``` + +(This is the approach that the Hoon compiler will use internally when it processes structures.) + +### Eliminating Vases {#eliminating-vases} + +> An elimination form for a vase is something that converts a vase to a statically typed value. + +There are three common ways to eliminate a vase back into a value: + +- `!<` zapgal is an unsafe form which accepts a mold and a vase. (It's unsafe because it doesn't guarantee the value has the type, an evil vase.) + +```hoon +> !<(@ !>(4)) +4 + +> !<(path !>(/===)) +/~zod/base/~2023.8.30..19.57.38..6b94 +``` + +- `;;` micmic is a safer coercion which applies the `spec` to the `hoon` and yields a mold-coerced form (structurally nests). + +```hoon +> ;;(@ 4) +4 + +> ;;(path /===) +/~zod/base/~2023.8.30..19.58.47..d09f +``` + +- A mold is a straightforward way to eliminate the vase, à la `;;` micmic. + +### Vase Algebra {#vase-algebra} + +Given a vase that contains an expression of data and its type, how can we use it besides to just eliminate it back to a static value? We will use vases to build Hoon code, so let's get good at combining and manipulating vases. Facility with vase mode is one of [the bright-line ideas](https://www.joelonsoftware.com/2005/12/29/the-perils-of-javaschools-2/) for kernel work, so read through these concepts several times and ask dumb questions. + +The [`+slap`/`+slop` vase algebra](/guides/additional/vases#slap'n'slop-vase-algebra) provides a framework for working through Hoon expressions at an abstract level. + +#### `+slap`: Envase Hoon + +[`+slap`](/hoon/reference/stdlib/5c#slap) runs a `hoon` against a `vase` and produces a `vase` of the result. + +```hoon +++ slap + |= [vax=vase gen=hoon] ^- vase :: untyped vase .* + =+ gun=(~(mint ut p.vax) %noun gen) + [p.gun .*(q.vax q.gun)] +``` + +First this gate compiles the parsed Hoon expression to Nock against the type of a passed subject using `+mint:ut` (on which more later). Then it envases the product type and the actual evaluation of that Nock against the subject (value) passed in. + +Since any Nock formula is resolved against a subject, `+slap` is Hoon's answer to raw `.*` Nock Two evaluation. The type of the subject contains the information about the arms, faces, and raw subject axes. + +```hoon +> => [one=1 two=2 tri=3] + != [one two] +[[0 2] 0 6] +[[0 2] [0 6]] +``` + +Examples: + +```hoon +> (slap !>(3) (ream '.')) +[#t/@ud q=3] + +> (slap !>(3) (ream '+(.)')) +[#t/@ q=4] + +> (slap !>(3) (ream '[33 44]')) +[#t/[@ud @ud] q=[33 44]] + +> (slap !>(3) (ream '%foo')) +[#t/%foo q=7.303.014] + +> (slap !>([33 44]) (ream '.')) +[#t/[@ud @ud] q=[33 44]] + +> (slap !>([33 44]) (ream '-')) +[#t/@ud q=33] + +> (slap !>([33 44]) (ream '+')) +[#t/@ud q=44] + +> (slap !>([foo=33 bar=44]) (ream '.')) +[#t/[foo=@ud bar=@ud] q=[33 44]] + +> (slap !>([foo=33 bar=44]) (ream 'foo')) +[#t/@ud q=33] + +> (slap !>([foo=33 bar=44]) (ream 'bar')) +[#t/@ud q=44] + +> (slap !>([foo=33 bar=44]) (ream '+(foo)')) +[#t/@ q=34] +``` + +#### `+slop`: Combine Vases + +[`+slop`](/hoon/reference/stdlib/5c#slop) combines a `cell` of `vase`s into a `vase` of a `cell`. + +```hoon +++ slop :: cons two vases + |= [hed=vase tal=vase] + ^- vase + [[%cell p.hed p.tal] [q.hed q.tal]] +``` + +Examples: + +```hoon +> (slop !>(3) !>(4)) +[#t/[@ud @ud] q=[3 4]] + +> (slop !>(foo=3) !>(4)) +[#t/[foo=@ud @ud] q=[3 4]] + +> (slop !>(foo=3) !>(bar=4)) +[#t/[foo=@ud bar=@ud] q=[3 4]] + +> (slop !>(foo=3) !>([bar=4 baz=5])) +[#t/[foo=@ud bar=@ud baz=@ud] q=[3 4 5]] + +> (slop !>(foo=%foo) !>([bar=[4 5] baz=%baz])) +[#t/[foo=%foo bar=[@ud @ud] baz=%baz] q=[7.303.014 [4 5] 8.020.322]] +``` + +#### Vase Algebra Operations + +With `+slap` and `+slop`, we have the ability to build higher-level operators. Each value is a `vase` and the fundamental operators are `+slap` and `+slop`. + +``` + +slap + / \ + +slop h2 + / \ + v1 +slop + / \ + v2 +slap + / \ + v3 h1 + +(slap (slop v1 (slop v2 (slap v3 h1))) h2) +``` + +A concrete example in Hoon: + +```hoon +=/ v1=vase !>(%foo) +=/ v2=vase !>(%bar) +=/ v3=vase !>(%baz) +=/ h1=hoon (ream '%qux') +=/ h2=hoon (ream '[%result .]') +:: +%+ slap + %+ slop v1 + %+ slop v2 + (slap v3 h1) +h2 + +:: result +[#t/[%result %foo %bar %qux] q=[128.009.175.786.866 7.303.014 7.496.034 7.894.385]] +``` + +Compilation and execution take place using vase mode, including many operators built of `+slap` and `+slop`. For instance, this is how Ford imports library cores when a file is built to code. + +#### `+slam`: Slam Gate with Sample + +[`+slam`](/hoon/reference/stdlib/5c#slam) accepts a gate as a `vase` and appropriate arguments. + +(This is an older implementation that's cleaner to interpet.) + +```hoon +++ slam + |= [gat=vase arg=vase] + ^- vase + (slap (slop gat arg) !,(*hoon (- +))) +``` + +Example: + +```hoon +> ;;($>(%hold type) -:(slam !>(dec) !>(5))) +[ %hold + #t/<1.hkg [a=@ <33.sam 1.pnw %139>]> + q + [ %sgcb + p + [ p=[%rock p=%tas q=1.717.658.988] + q + [ %knit + p + ~[100 101 99 114 101 109 101 110 116 45 117 110 100 101 114 102 108 111 119] + ] + ] + q + [ %wtgl + p=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]] + q + [ %tsls + p=[%ktts p=term=%b q=[%sand p=%ud q=0]] + q + [ %brhp + p + [ %kthp + p=[%base p=[%atom p=~.]] + q + [ %wtcl + p=[%dtts p=[%wing p=~[%a]] q=[%dtls p=[%wing p=~[%b]]]] + q=[%wing p=~[%b]] + r=[%cnts p=~[%$] q=[i=[p=~[%b] q=[%dtls p=[%wing p=~[%b]]]] t=~]] + ] + ] + ] + ] + ] + ] +] +``` + +- How do we get the result back out? (Elimination mode, such as `!<`.) + +#### `+slot`: Retrieve Noun + +[`+slot`](/hoon/reference/stdlib/5c#slot) can be used to decompose vases. + +```hoon +++ slot :: got axis in vase + |= [axe=@ vax=vase] ^- vase + [(~(peek ut p.vax) %free axe) .*(q.vax [0 axe])] +``` + +`(slot 2 vase)` and `(slot 3 vase)` decompose the `vase` back into constituent types and values. + +#### Tutorial: Finding the Sample + +- How can you retrieve the type of the sample from a vase for a gate? + +```hoon +> =+ -:!>(+6:add) + ?>(?=([%cell *] -) -) +p=[%cell #t/a=@ #t/b=@] + +> =+ -:!>(+6:|=([p=@tas q=@da r=^] ~)) + ?>(?=([%cell *] -) -) +p=[%cell #t/p=@tas #t/[q=@da r=[* *]]] +``` + +- How can you examine the faces of the sample? + +```hoon +> =+ -:!>(+12:|=([p=@tas q=@da r=^] ~)) + ?>(?=([%face *] -) -) +p=[%face p=%p #t/@tas] +``` + +Some places to examine vase mode: + +- Dojo uses vase mode to evaluate statements. +- ~rovnys-ricfer produces a simplified Gall using vase mode in [this video](https://drive.google.com/file/d/10SaE5doCfdeqc2j945t8GvGvexKIBBZq/view). +- [Hoon, “Vases”](/guides/additional/vases) +- [~rovnys-ricfer, “Hoon Vases”](https://rovnys.cataphract.us/vases) (older version but has some diagrams that aren't in the docs version) + + +## The Compiler Stack {#the-compiler-stack} +### The Lifecycle of Hoon (`+ride` or Die) {#the-lifecycle-of-hoon-ride-or-die} + +Hoon code begins life as text, presumably a `cord` `@t` value. If we would like to go from text interpretable as Hoon code to executable Nock, what does that look like? + +There are a few different paths Hoon can take to run the gauntlet: + +1. A text file containing Hoon code, processed via the `%hoon` mark. +2. A text `cord` containing Hoon code, processed via the `+ream` arm +3. A noun interpretable as a Hoon AST. + +We need to go from Hoon code to a Hoon abstract syntax tree (AST), then from the AST to Nock. We can build and describe this process at several layers of granularity. For instance, `+ride` accomplishes this in one step. + +[`+ride`](/hoon/reference/stdlib/5d#ride) accepts a pair of `$type` and an atom (really a `cord`) of text containing Hoon code. + +```hoon +++ ride + |= [typ=type txt=@] + ^- (pair type nock) + ~> %slog.[0 leaf/"ride: parsing"] + =/ gen (ream txt) + ~> %slog.[0 leaf/"ride: compiling"] + ~< %slog.[0 leaf/"ride: compiled"] + (~(mint ut typ) %noun gen) +``` + +Line by line: + +- `|= [typ=type txt=@]` + - Accept a `$type` and a `cord`. +- `^- (pair type nock)` + - A pair of `$type` and compiled `$nock` result. A `nock` is a cell of numbers interpretable as a Nock formula. Notably, the Nock rules tend to be embedded as constants (such as `%0`), which makes it more readable than conventional Nock. +- `~> %slog.[0 leaf/"ride: parsing"]` + - Issue a raw hint to output a starting message. +- `=/ gen (ream txt)` + - `+ream` the `cord`, which compiles the Hoon expression into a Hoon abstract syntax tree (AST). +- `~> %slog.[0 leaf/"ride: compiling"]` + - Issue a raw hint to output a continuation message. +- `~< %slog.[0 leaf/"ride: compiled"]` + - Issue a raw hint to the product (so it prints after the completion). +- `(~(mint ut typ) %noun gen)` + - Do the shovel work of compiling the parsed AST into Nock code, using the type `%noun`. + +As another example, [`+make`](/hoon/reference/stdlib/5d#make) shows the process in capsule form for converting a `cord` of Hoon code into executable `$nock` Nock code. `+make` doesn't explicitly require or deal with `$type` like `+ride` does. + +```hoon +++ make + |= txt=@ + q:(~(mint ut %noun) %noun (ream txt)) +``` + +Given a Hoon expression, convert it to `$nock`. + +```hoon +> (make '~[1 2 3]') +[%1 p=[1 2 3 0]] +``` + +### Text `cord` → AST `$hoon` {#text-cord-ast-hoon} + +#### `+ream` + +To take a `cord` containing Hoon code and transform it to an AST, use [`+ream`](/hoon/reference/stdlib/5d#ream): + +```hoon +> (ream '(add 1 2)') +[%cncl p=[%wing p=~[%add]] q=~[[%sand p=%ud q=1] [%sand p=%ud q=2]]] + +> (ream '-:!>(5)') +[%tsgl p=[%cnts p=~[[%.y p=2]] q=~] q=[%zpgr p=[%sand p=%ud q=5]]] +``` + +`+ream` simply wraps `+vast`: + +```hoon +++ ream :: parse cord to hoon + |= txt=@ + ^- hoon + (rash txt vest) +``` + +Any irregular annotation is changed into its basic Hoon form. However, at this point no desugaring has taken place; equivalent forms may still have different AST representations as `$hoon`: + +```hoon +> (ream '~[1 2 3]') +[%clsg p=~[[%sand p=%ud q=1] [%sand p=%ud q=2] [%sand p=%ud q=3]]] + +> (ream '[1 2 3 ~]') +[%cltr p=~[[%sand p=%ud q=1] [%sand p=%ud q=2] [%sand p=%ud q=3] [%bust p=%null]]] +``` + +You can also clearly see how Hoon supplements "pure" values with metadata to establish context for the values. + +#### `+vast` + +`+ream` is a wrapper for the main parser `+vast`. While `+vast` spans all of Hoon parsing, it is particularly intended to parse Hoon, unsurprisingly. It starts with an attempt to parse in tall form, which will fall back to wide form as necessary. A `+gay` is a way to ignore `+gap` plural whitespace on either side of the text (file). + +```hoon +++ vest + ~/ %vest + |= tub=nail + ^- (like hoon) + %. tub + %- full + (ifix [gay gay] tall:vast) +``` + +The `+vang` wrapper lets you turn off debugging info and doccords in parsing. + +```hoon +> (rash 'goo' tall:(vang | /)) +[%wing p=~[%goo]] + +> (rash 'goo' tall:(vang & /)) +[%dbug p=[p=/ q=[p=[p=1 q=1] q=[p=1 q=4]]] q=[%wing p=~[%goo]]] +``` + +#### `+open:ap` + +A parsed Hoon AST has not yet been desugared. Many Hoon runes are simply convenience wrappers over a few fundamental runes. (For instance, most (all?) `%` cen runes reduce to `%~` censig.) `+open:ap` unwraps these one layer at a time until fundamental runes are reached in the Hoon AST. + +```hoon +> (ream '(add 1 2)') +[%cncl p=[%wing p=~[%add]] q=[i=[%sand p=%ud q=1] t=[i=[%sand p=%ud q=2] t=~]]] + +> ~(open ap (ream '(add 1 2)')) +[ %cnsg + p=~[%$] + q=[%wing p=~[%add]] + r=[i=[%sand p=%ud q=1] t=[i=[%sand p=%ud q=2] t=~]] +] + +> ~(open ap ~(open ap (ream '(add 1 2)'))) +[ %cntr + p=~[%$] + q=[%wing p=~[%add]] + r + [ i=[p=~[[%.n p=0 q=~] [%.y p=12]] q=[%sand p=%ud q=1]] + t=[i=[p=~[[%.n p=0 q=~] [%.y p=13]] q=[%sand p=%ud q=2]] t=~] + ] +] + +> ~(open ap ~(open ap ~(open ap (ream '(add 1 2)')))) +[ %tsls + p=[%wing p=~[%add]] + q + [ %cnts + p=~[%$ [%.y p=2]] + q + [ i + [p=~[[%.n p=0 q=~] [%.y p=12]] q=[%tsgr p=[%$ p=3] q=[%sand p=%ud q=1]]] + t + [ i + [ p=~[[%.n p=0 q=~] [%.y p=13]] + q=[%tsgr p=[%$ p=3] q=[%sand p=%ud q=2]] + ] + t=~ + ] + ] + ] +] + +> ~(open ap ~(open ap ~(open ap ~(open ap (ream '(add 1 2)'))))) +[ %tsgr + p=[p=[%wing p=~[%add]] q=[%$ p=1]] + q + [ %cnts + p=~[%$ [%.y p=2]] + q + [ i + [p=~[[%.n p=0 q=~] [%.y p=12]] q=[%tsgr p=[%$ p=3] q=[%sand p=%ud q=1]]] + t + [ i + [ p=~[[%.n p=0 q=~] [%.y p=13]] + q=[%tsgr p=[%$ p=3] q=[%sand p=%ud q=2]] + ] + t=~ + ] + ] + ] +] +``` + +- [Hoon, “Constants (Atoms and Strings)”](/hoon/reference/rune/constants) + +- Examine `+open:ap` in `/sys/hoon.hoon` to see how desugaring proceeds. + +### AST `$hoon` → Nock `$nock` {#ast-hoon-nock-nock} + +All Hoon code is ultimately run by `+mint:ut`, although there can be many paths there. `+mint:ut` parses from a Hoon AST into a pair of the type and the Nock. What is [`+ut`](/hoon/reference/stdlib/5c#ut)? It's the Hoon compiler backend, containing all of the arms necessary to actually process a `$hoon` into a `$nock`. + +One simple approach is to look at the 2013 Hoon compiler, which presents a relatively uncluttered version + +- [`+mint:ut` (2013)](https://github.com/urbit/archaeology/blob/6b2ce202207b9bb3f4e65fc1ea9a2fb434396dd4/urb/zod/arvo/hoon.hoon#L7698) + +In all cases, the parent door `+ut` receives the sample of `$type` when an arm is invoked. The significant arms include: + +##### `+mull:ut` + +`+mull` is an assertion for wet gates. Each place in the code that calls a wet gate needs the compiler to check in order to ensure that the wet gate when called with that sample would have the same Nock as it would otherwise. + +- `sut` is the subject type +- `gol` is a product constraint (result type must nest in `gol`, passed around to support accurate stack traces) +- `dox` is the formal subject type + +`+mull` is conceptually equivalent to saying, “compile this expression against the actual subject type `sut`, compile it again against the formal type `dox`, assert that they produce the same Nock”. + +In practice, +mull traverses both subject types at the same time, short-circuiting in a couple of scenarios, and simply crashing if the (conceptual) result would be different. + +##### `+find:ut` + +`+find` is a wing resolution arm. It tries Nock Zero first to see if the wing is a leg, then tries Nock Nine if that fails. It also needs information about the core variance (`%read`, `%rite`, `%both`, `%free`); see [`+slab`](/hoon/reference/stdlib/5c#slab) as well, which also uses `+fond` under the hood. + +```hoon +> (slab %read %$ -:!>(add)) +%.y + +> (slab %read %a -:!>(add)) +%.y + +> (slab %read %b -:!>(add)) +%.y + +> (slab %read %c -:!>(add)) +%.n +``` + +##### `+nest:ut` + +`+nest` provides a structural test on whether two `$type`s nest properly. It is called via `+nice` so that the `need`/`have` error messages can be presented neatly. + +##### `+mint:ut` + +`+mint` is quite long, but deserves some attention. + +- `+mint` itself takes a pair of `typ` and `hoon`, a Hoon AST. +- `+mint` produces a pair of `type` and `nock`. +- It features a lot of `+nice` (`+nest`) checks. +- Each branch in the main `switch` operates on an AST tag to convert it recursively to `$nock`. + +```hoon +> (~(mint ut %noun) %noun (ream '~[1 2 3]')) +[#t/[@ud @ud @ud %~] q=[%1 p=[1 2 3 0]]] +``` + +This can be evaluated as `$nock` then using `.*` dottar: + +```hoon +> .*(. (make '~[1 2 3]')) +[1 2 3 0] +``` + +`+mint:ut` is never called on its own in the compiler. It's used to generate a Nock formula then to run it against the subject to make it useful, e.g. for an agent running a formula against the standard library plus imports. + +```hoon +> (~(mint ut -:!>(.)) %noun ~(open ap (ream '(add 1 2)'))) +[ #t/@ + q + [ %8 + p=[%9 p=36 q=[%0 p=2.047]] + q + [ %9 + p=2 + q + [ %10 + p=[p=6 q=[p=[%7 p=[%0 p=3] q=[%1 p=1]] q=[%7 p=[%0 p=3] q=[%1 p=2]]]] + q=[%0 p=2] + ] + ] + ] +] + +> !=((add 1 2)) +[8 [9 36 0 2.047] 9 2 10 [6 [7 [0 3] 1 1] 7 [0 3] 1 2] 0 2] + +> ;;($>(?(%hold %core) type) -:(~(mint ut -:!>(.)) %noun ~(open ap (ream '(add 1 +2)')))) +[ %hold + #t/<1.otf [[a=@ b=@] <33.sam 1.pnw %139>]> + q + [ %kthp + p=[%base p=[%atom p=~.]] + q + [ %wtcl + p=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]] + q=[%wing p=~[%b]] + r + [ %cnts + p=~[%$] + q + [ i=[p=~[%a] q=[%cncl p=[%wing p=~[%dec]] q=[i=[%wing p=~[%a]] t=~]]] + t=[i=[p=~[%b] q=[%dtls p=[%wing p=~[%b]]]] t=~] + ] + ] + ] + ] +] + +;;($>(?(%hold %core) type) -:(~(mint ut -:!>(.)) %noun ~(open ap (rash 'add' t +all:(vang | /))))) +``` + +In the case of a core, `+mint` returns a 3-tuple. The head is the battery of the core; the middle is the default sample, or Nock One of the bunted sample; the tail is `[0 1]`, to take the subject and put it in the `context` of the core. + +```hoon +> +:(~(mint ut -:!>(~)) %noun !,(*hoon |=(@ +<))) +q=[%8 p=[%1 p=0] q=[p=[%1 p=[0 6]] q=[%0 p=1]]] +``` + +The Hoon compiler is not an optimizing compiler. It can recognize and replace some simple expressions, like Nock Seven of two Nock Zeros into a single Nock Zero. + +(As an aside, note that Hoon only uses `#` hax in a rune as a placeholder for an experimental rune, or a rune that is involved in the first stage of a multi-stage upgrade process, like swapping two runes and needing a temporary rune to use in the intermediate version of the language.) + +Ted points out that the nature of Hoon as an ergonomic harness to generate Nock code is here very apparent. There is no additional runtime system materials like C, C++, or Rust would inject; there is no extra Nock glue. Hoon is a good assembly language (which is really what it's for)—so one future of Hoon is to strip out features and make it more concrete bare-bones then build things on top of it. + +- [Hoon 141 Compiler Documentation](https://docs.google.com/document/d/1C0k0AY2vsFu5fNfp0nKiU0GsKThkLMLdHBReqAXNy_w/edit) + +Questions: + +- If you create a Gall agent with the wrong number of arms (i.e. add an arm), what goes wrong? Where does this error arise in the compilation process? + +#### `$nock` + +While there are no surprises in `$nock` as a representation of Nock nouns, the use of constants for the rules and the deferral of formulae as subnocks is very readable. + +```hoon ++$ nock $^ [p=nock q=nock] :: autocons + $% [%1 p=*] :: constant + [%2 p=nock q=nock] :: compose + [%3 p=nock] :: cell test + [%4 p=nock] :: increment + [%5 p=nock q=nock] :: equality test + [%6 p=nock q=nock r=nock] :: if, then, else + [%7 p=nock q=nock] :: serial compose + [%8 p=nock q=nock] :: push onto subject + [%9 p=@ q=nock] :: select arm and fire + [%10 p=[p=@ q=nock] q=nock] :: edit + [%11 p=$@(@ [p=@ q=nock]) q=nock] :: hint + [%12 p=nock q=nock] :: grab data from sky + [%0 p=@] :: axis select + == :: +``` + +### Files with Imports (`+ford`) {#files-with-imports-ford} + +`+ford` is the code builder arm (formerly vane) which handles producing code from a file on a desk, including library imports. Ford uses the `+slap`/`+slop` algebra to produce the subject type and value. + +For instance, with `/-` wuthep, Ford builds the `/sur` file then `+slop`s that `vase` with `%zuse` to yield the new build subject, the new `vase`. That combined vase is the subject when Ford `+slap`s the file contents. This illustrates the production of a high-level AST using the `+slap` of `vase` and `hoon` dependent on the `+slop` of two or more `vase`s. + +Clay maintains some state to trigger Ford builds, for instance if the agent is rebuilt after a `|commit`. Thus Gall can subscribe to the next revision of any query that can be sent to Clay. As of December 2022, Clay maintains an official state about which agents are supposed to be running from each desk, then eagerly runs the build. + +- [~rovnys-ricfer, “Ford Pinto Spec”](https://gist.github.com/belisarius222/dc2aae8230a22a84d389c19cb613a1d2) +- [~rovnys-ricfer, “Ford Fusion”](https://urbit.org/blog/ford-fusion) + +#### `-build-file` + +The `-build-file` and `-build-dependency` threads are the simplest way to invoke `+ford`. Ultimately these resolve through `/lib/strandio`: + +**`/lib/strandio.hoon`** + +```hoon +:: +:: +build-file: build the source file at the specified $beam +:: +++ build-file + |= [[=ship =desk =case] =spur] + =* arg +< + =/ m (strand ,(unit vase)) + ^- form:m + ;< =riot:clay bind:m + (warp ship desk ~ %sing %a case spur) + ?~ riot + (pure:m ~) + ?> =(%vase p.r.u.riot) + (pure:m (some !<(vase q.r.u.riot))) +``` + +We will consider marks and tubes in the next lesson. + +### Tutorial: Trace a Rune AST {#tutorial-trace-a-rune-ast} + +The [`|$` barbuc](/hoon/reference/rune/bar#-barbuc) rune is used to build a mold builder gate. (As such, it's fairly abstract.) Essentially, it is sugar for a certain use of [`|*` bartar](/hoon/reference/rune/bar#-bartar): + +```hoon +|$ [a b] +body + +|* [a=$~(* $-(* *)) b=$~(* $-(* *))] +^: +body +``` + +The formal AST for `%brbc` is `[%brbc sample=(lest term) body=spec]`. How is this actually built? + +Let's look at the sample first. The sample is a `(lest term)`, or a non-empty list of identifiers. Notice, however, that the actual value passed in (like `[a b]`) is _not_ a list at all. Several runes that accept a `list` type (like `:~` colsig) handle adding the terminal `~` in the first parsing step. + +The definition of `%brbc` is a little dense but it's doing the same thing, so the sample isn't explicitly a `lest` but becomes one in the first pass of building the rune AST. + +In `hoon.hoon`, find the following line: + +``` +[%brbc sample=(lest term) body=spec] :: |$ +``` + +Next, find where it is parsed in `+vast`, the main parsing core. This will tell you how the rune children are parsed. + +```hoon +++ expression + %- stew + ^. stet ^. limo + :~ :- '|' + ;~ pfix bar + %- stew + ^. stet ^. limo + :~ ['$' (rune buc %brbc exqe)] + == + == + == +``` + +In this case, the rune children are handled using `+exqe`, which automatically turns the sample into a list of names: + +```hoon +++ exqe |.(;~(goop lynx loan)) :: list of names then spec +``` + +In this expression, there are three new names: + +1. `+goop` is a separated `list` with doccord compatible docs included. +2. `+lynx` is a parser for `a` or `[a b c]` or `a b c ==`. +3. `+loan` parses a `spec`. + +So by the time the sample is processed, it has already acquired `list`-type from `+exqe`. + +Next, let's look at the direct handling of the result of `+exqe`: + +```hoon +[%brbc *] =- ?~ - !! + :+ %brtr + [%bccl -] + |- + ?. ?=([%gist *] body.gen) + [%ktcl body.gen] + [%note p.body.gen $(body.gen q.body.gen)] + %+ turn `(list term)`sample.gen + |= =term + ^- spec + =/ tar [%base %noun] + [%bcts term [%bcsg tar [%bchp tar tar]]] +``` + +Desugared and annotated: + +```hoon +=+ :: first parse the sample into a lest + %+ turn `(list term)`sample.gen + |= =term ^- spec + [%bcts term [%bcsg [%base %noun] [%bchp [%base %noun] [%base %noun]]]] + :: + :: if the foregoing turned list is empty, crash + ?~ - !! + :: otherwise, produce the desugared |* + :+ %brtr + :: this is the cell of the sample in the first arm + [%bccl -] + |- + ?: ?=([%gist *] body.gen) + :: if it's a gist, then include the doccords note + [%note p.body.gen $(body.gen q.body.gen)] + :: otherwise just include the body + [%ktcl body.gen] +``` + +Look for the structure: + +```hoon +|* [a=$~(* $-(* *)) b=$~(* $-(* *))] +^: +body +``` + +#### Exercise + +- Carry out the foregoing analysis for another sugar rune, such as `?~`, `:~`, `=.`, or `=/`. + +### Evaluating Nock {#evaluating-nock} + +As mentioned in `ca00`, Nock is dispatched to the Nock interpreter in the runtime, where it is evaluated as a mixture of Nock bytecode and runtime jets. Different parts of the system can have different Nock interpreters; for instance, in userspace, the `+mink` metacircular interpreter is used so that crashes can be handled. + +### Hoon and Nock Nine {#hoon-and-nock-nine} + +In a sense, Hoon is an assembly language macro for Nock as machine code. One of the most common patterns in Hoon is how a gate is defined as a core, then invoked into a particular instance by replacing the sample then evaluating the statement. (This happens in gate-building gates but elsewhere as well.) + +``` +> != %-(add [3 4]) +[8 [9 36 0 2.047] 9 2 10 [6 7 [0 3] 1 3 4] 0 2] +``` + +This code takes the `add` core, modifies its sample to be constant `[3 4]`, then fires the `$` arm at axis `2`. Then `[9 36 …]` fires the `add` arm of that core to get the `add` gate. + +You can connect how Nock thinks of a double Nock Nine invocation to how Hoon has a `%hold` then resolves it into a `%core`. For instance, let's look inside of `+add`, where we can get the `%hold` and then see the AST (on which more later). Here the `%hold` means that the “actual” type of `+add` has not yet been calculated—although it is a core, it will have to be built with a particular sample for it to result in a `%core`. (What I mean by this is that `%hold` is a lazy evaluation.) + +```hoon +> +2:!>(add) +#t/<1.otf [[a=@ b=@] <33.rnj 1.pnw %139>]> + +> +4:!>(add) +%hold + +> +10:!>(add) +#t/<33.rnj 1.pnw %139> + +> +22:!>(add) +%sgfs + +> +46:!>(add) +i='add' +> +47:!>(add) + q +[ %note + p + [ %help + p + [ cuff=~ + crib + [ summary='unsigned addition' + details=~[~[[p=%.y q='a: augend'] [p=%.y q='b: addend']]] + ] + ] + ] + q + [ %brts + p + [ %bccl + p + [ i=[%bcts p=term=%a q=[%base p=[%atom p=~.]]] + t=[i=[%bcts p=term=%b q=[%base p=[%atom p=~.]]] t=~] + ] + ] + q + [ %kthp + p=[%base p=[%atom p=~.]] + q + [ %wtcl + p=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]] + q=[%wing p=~[%b]] + r + [ %cnts + p=~[%$] + q + [ i=[p=~[%a] q=[%cncl p=[%wing p=~[%dec]] q=[i=[%wing p=~[%a]] t=~]]] + t=[i=[p=~[%b] q=[%dtls p=[%wing p=~[%b]]]] t=~] + ] + ] + ] + ] + ] +] +``` + +```hoon +> +20:!>(*add) +%core + +> +23:!>(*add) + q +[ p=[%base p=[%atom p=~.]] + q + [ %wtcl + p=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]] + q=[%wing p=~[%b]] + r + [ %cnts + p=~[%$] + q + [ i=[p=~[%a] q=[%cncl p=[%wing p=~[%dec]] q=[i=[%wing p=~[%a]] t=~]]] + t=[i=[p=~[%b] q=[%dtls p=[%wing p=~[%b]]]] t=~] + ] + ] + ] +] +``` + + +## Exercises {#exercises} + +- Exercise: The original `;<` micgal macro was unhygienic; that is, it introduced a spurious `$` each time it was called. This could be worked around using `=* foo $` after a `|-`, but was inconvenient. The original AST expansion of the macro was `[%cnls [%cnhp q [%ktcl p]] r [%brts p s]]:gen`; this was improved to `[%cnls [%cnhp q [%ktcl p]] r [%brts p [%tsgr $+3 s]]]:gen`. Explain how this works. + - `[%tsgr $+3 s]` is `=>(+ s)`, i.e., the body of the generated gate `s` should not be evaluated against the generated gate but against the payload at axis `+3`; this will be both the sample and context, where the sample is the newly bound value `.p` and the context is the subject against which the `;<` was expressed. Now it works just like `=/`. +- Exercise: Write your own [`+slam`](/hoon/reference/stdlib/5c#slam) using `+slap` and `+slop`. +- Exercise: Implement a rune. The easiest rune to implement is a five-tuple; let's call it `:#` colhax. The parser (`+vast`) and the AST processor (`+open:ap`) need to be modified for this rune to work. Formally this is a language change, but you should be able to just reload `/sys/hoon.hoon` automatically and have it update in place. Alternatively, implement the ;. micdot rune. |