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
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:
> -:!>(add)#t/<1.otf [[a=@ b=@] <33.sam 1.pnw %139>]>> -<:!>(add)%hold
/sys/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== ::
%nounis the superset of all nouns.%voidis the empty noun, but won't occur in practice.%atomspans the set of all atoms.%cellcontains ordered pairs.
The other types are more complex:
%coreis the descriptor type for a core. Besides the+$type, it uses a+$coil, which is a tuple of variance information, context, and chapters (limbs).%facespans the same set as nouns but includes a face.%forkis a union, or choice over options.%hintis an annotation for the compiler (Nock Eleven).%holdtypes are lazily evaluated, such as a recursive type (like the++listmold builder).%holdtypes are why the compiler can have trouble with lists at runtime, such as needing to distinguish alestor the TMI problem with++snag&c.- A
%holdtype 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
hoonof 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).
> =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:
> ;;($>(%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.
> =- ?>(?=(%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
The most common way to get a vase is using the !> zapgar rune.
> !>('Hello Mars')[#t/@t q=545.182.085.650.269.906.691.400]
A vase can also be manually constructed, e.g.
> `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
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.)
> !<(@ !>(4))4> !<(path !>(/===))/~zod/base/~2023.8.30..19.57.38..6b94
;;micmic is a safer coercion which applies thespecto thehoonand yields a mold-coerced form (structurally nests).
> ;;(@ 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
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↗ for kernel work, so read through these concepts several times and ask dumb questions.
The ++slap/++slop vase algebra provides a framework for working through Hoon expressions at an abstract level.
++slap: Envase Hoon
++slap runs a hoon against a vase and produces a vase of the result.
++ 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.
> => [one=1 two=2 tri=3]!= [one two][[0 2] 0 6][[0 2] [0 6]]
Examples:
> (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 combines a cell of vases into a vase of a cell.
++ slop :: cons two vases|= [hed=vase tal=vase]^- vase[[%cell p.hed p.tal] [q.hed q.tal]]
Examples:
> (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:
=/ 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 accepts a gate as a vase and appropriate arguments.
(This is an older implementation that's cleaner to interpet.)
++ slam|= [gat=vase arg=vase]^- vase(slap (slop gat arg) !,(*hoon (- +)))
Example:
> ;;($>(%hold type) -:(slam !>(dec) !>(5)))[ %hold#t/<1.hkg [a=@ <33.sam 1.pnw %139>]>q[ %sgcbp[ p=[%rock p=%tas q=1.717.658.988]q[ %knitp~[100 101 99 114 101 109 101 110 116 45 117 110 100 101 114 102 108 111 119]]]q[ %wtglp=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]]q[ %tslsp=[%ktts p=term=%b q=[%sand p=%ud q=0]]q[ %brhpp[ %kthpp=[%base p=[%atom p=~.]]q[ %wtclp=[%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 can be used to decompose vases.
++ 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?
> =+ -:!>(+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?
> =+ -:!>(+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↗.
- Hoon, “Vases”
- ~rovnys-ricfer, “Hoon Vases”↗ (older version but has some diagrams that aren't in the docs version)
The Compiler Stack
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:
- A text file containing Hoon code, processed via the
%hoonmark. - A text
cordcontaining Hoon code, processed via the++reamarm - 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 accepts a pair of +$type and an atom (really a cord) of text containing Hoon code.
++ 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
+$typeand acord.
- Accept a
^- (pair type nock)- A pair of
+$typeand compiled+$nockresult. Anockis 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.
- A pair of
~> %slog.[0 leaf/"ride: parsing"]- Issue a raw hint to output a starting message.
=/ gen (ream txt)++reamthecord, 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.
- Do the shovel work of compiling the parsed AST into Nock code, using the type
As another example, ++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.
++ make|= txt=@q:(~(mint ut %noun) %noun (ream txt))
Given a Hoon expression, convert it to $nock.
> (make '~[1 2 3]')[%1 p=[1 2 3 0]]
Text cord → AST +$hoon
++ream
To take a cord containing Hoon code and transform it to an AST, use +ream:
> (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:
++ 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:
> (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).
++ 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.
> (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.
> (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)'))[ %cnsgp=~[%$]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)')))[ %cntrp=~[%$]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)'))))[ %tslsp=[%wing p=~[%add]]q[ %cntsp=~[%$ [%.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)')))))[ %tsgrp=[p=[%wing p=~[%add]] q=[%$ p=1]]q[ %cntsp=~[%$ [%.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=~]]]]
Examine
++open:apin/sys/hoon.hoonto see how desugaring proceeds.
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? 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
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.
sutis the subject typegolis a product constraint (result type must nest ingol, passed around to support accurate stack traces)doxis 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 as well, which also uses ++fond under the hood.
> (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 +$types 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.
++mintitself takes a pair oftypandhoon, a Hoon AST.++mintproduces a pair oftypeandnock.- It features a lot of
++nice(++nest) checks. - Each branch in the main
switchoperates on an AST tag to convert it recursively to+$nock.
> (~(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:
> .*(. (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.
> (~(mint ut -:!>(.)) %noun ~(open ap (ream '(add 1 2)')))[ #t/@q[ %8p=[%9 p=36 q=[%0 p=2.047]]q[ %9p=2q[ %10p=[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 12)'))))[ %hold#t/<1.otf [[a=@ b=@] <33.sam 1.pnw %139>]>q[ %kthpp=[%base p=[%atom p=~.]]q[ %wtclp=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]]q=[%wing p=~[%b]]r[ %cntsp=~[%$]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' tall:(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.
> +:(~(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.
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.
+$ 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)
++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 ++slops that vase with %zuse to yield the new build subject, the new vase. That combined vase is the subject when Ford ++slaps 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 vases.
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.
-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
:::: +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
The |$ 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:
|$ [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.
++ 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:
++ exqe |.(;~(goop lynx loan)) :: list of names then spec
In this expression, there are three new names:
+goopis a separatedlistwith doccord compatible docs included.+lynxis a parser foraor[a b c]ora b c ==.+loanparses aspec.
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:
[%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:
=+ :: 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:
|* [a=$~(* $-(* *)) b=$~(* $-(* *))]^:body
Exercise
- Carry out the foregoing analysis for another sugar rune, such as
?~,:~,=., or=/.
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
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.)
> +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[ %notep[ %helpp[ cuff=~crib[ summary='unsigned addition'details=~[~[[p=%.y q='a: augend'] [p=%.y q='b: addend']]]]]]q[ %brtsp[ %bcclp[ i=[%bcts p=term=%a q=[%base p=[%atom p=~.]]]t=[i=[%bcts p=term=%b q=[%base p=[%atom p=~.]]] t=~]]]q[ %kthpp=[%base p=[%atom p=~.]]q[ %wtclp=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]]q=[%wing p=~[%b]]r[ %cntsp=~[%$]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=~]]]]]]]
> +20:!>(*add)%core> +23:!>(*add)q[ p=[%base p=[%atom p=~.]]q[ %wtclp=[%dtts p=[%sand p=%ud q=0] q=[%wing p=~[%a]]]q=[%wing p=~[%b]]r[ %cntsp=~[%$]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
- 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 gatesshould 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 valuepand the context is the subject against which the;<was expressed. Now it works just like=/.
- Exercise: Write your own
++slamusing++slapand++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.hoonautomatically and have it update in place. Alternatively, implement the ;. micdot rune.