diff --git a/nix/pkgs/pill/solid.sh b/nix/pkgs/pill/solid.sh index 591a93e9a..e46aec7ac 100644 --- a/nix/pkgs/pill/solid.sh +++ b/nix/pkgs/pill/solid.sh @@ -42,6 +42,7 @@ cp $ARVO/mar/lens/* ./pier/home/mar/lens/ cp $ARVO/sur/lens.hoon ./pier/home/sur/ cp $ARVO/sur/plum.hoon ./pier/home/sur/ cp $ARVO/sur/sole.hoon ./pier/home/sur/ +cp $ARVO/sur/xray.hoon ./pier/home/sur/ # Update +solid and its dependencies cp $ARVO/lib/pill.hoon ./pier/home/lib/ diff --git a/pkg/arvo/lib/pprint.hoon b/pkg/arvo/lib/pprint.hoon index 4535b772e..7ea426485 100644 --- a/pkg/arvo/lib/pprint.hoon +++ b/pkg/arvo/lib/pprint.hoon @@ -1,4 +1,4 @@ -/- *plum +/- *plum, *xray /+ *plume, libxray=xray :: diff --git a/pkg/arvo/lib/xray.hoon b/pkg/arvo/lib/xray.hoon index 40d25e32e..bc67b0e05 100644 --- a/pkg/arvo/lib/xray.hoon +++ b/pkg/arvo/lib/xray.hoon @@ -1,4 +1,4 @@ -/- *plum +/- *plum, *xray :: :: # Type Analysis :: diff --git a/pkg/arvo/sur/xray.hoon b/pkg/arvo/sur/xray.hoon new file mode 100644 index 000000000..9faaad019 --- /dev/null +++ b/pkg/arvo/sur/xray.hoon @@ -0,0 +1,176 @@ + +:: +:: These are the public types for the `xray` library. Analysing a type +:: yields an `ximage`, and everything else here is just some structure +:: within that. +:: +:: `ximage`s can be printed as specs (hoon syntax for types), and can +:: be used to pretty-print typed data. +:: +^? |% +:: +:: An `xtable` is a graph of types referenced by the top-level type, +:: and the `root` `key` points to the node which corresponds to the +:: type under analysis. +:: ++$ ximage [root=xkey =xtable] +:: +:: A `xkey` is just an identifier for a node in the xray graph. +:: ++$ xkey @ +:: +:: An `xtable` is the xray graph itself. It contains one node for for +:: the type that was analyzed and one node for every type referenced +:: within that type. +:: +:: The `next` field is the the next available xkey (used when inserting +:: new xrays), `xrays` maps keys to graph nodes and `type-map` gives +:: the xkey corresponding to a type. +:: +:: The `type-map` is basically just the reverse of the `xrays` map. It +:: doesn't contain any new information, but is needed for performance +:: reasons. +:: ++$ xtable [next=xkey xrays=(map xkey xray) =type=(map type xkey)] +:: +:: An `xray` is a node in the `ximage` graph. It contains everything +:: we know about a certain `type`. `key` is its identifier in the graph, +:: `type` is the type that it's an xray of, and `xdat` is the basic +:: information we derived about the type. The basic references to other +:: nodes are inside the `xdat` structure, though some of the other +:: fields may contain references as well. +:: +:: - `xshape` is some more information about the xshape of data within +:: a cell. +:: - `xrole` expands on `xshape`, adding further information about the +:: xrole that a node has within a fork. +:: - `pats` is used for printing data: we want to know if this type +:: can be printed as a list, as json, as a tape literal, etc. +:: - `recipes` contains information about how a type was +:: constructed. It's used to get much nicer output when printing types. +:: - `studs` contains "standards names". I actually don't know what this is. +:: - `helps` contains all the documentation about a type. +:: - `loop` indicates whether or not a node references itself. The list +:: type is cyclical, for example. This is used when printing an +:: `ximage`. +:: ++$ xray + $: =xkey + =type + xdat=(unit xdat) + xrole=(unit xrole) + pats=(unit xpat) + studs=(set stud) + recipes=(set recipe) + helps=(set help) + xshape=(unit xshape) + loop=(unit ?) + == +:: +:: - `%void` -- impossible to create. +:: - `%noun` -- could be any noun. +:: - `%atom` -- An atom of some aura, possibly constant +:: - `%cell` -- A cell with a head and a tail. +:: - `%core` -- A core, its garb, its context type, and the types of +:: each of its arms. +:: - `%face` -- A face on another type. +:: - `%fork` -- Could be one or more other types. +:: - `%pntr` -- This is an internal hack, it should never survive +:: analysis; ignore. +:: ++$ xdat + $@ ?(%noun %void) + $% [%atom =aura constant=(unit @)] + [%cell head=xkey tail=xkey] + [%core =garb xray=xkey batt=xbat] + [%face face=$@(term tune) xray=xkey] + [%fork =(set xkey)] + [%pntr xray=xkey] + == +:: +:: The basic xshape of a type: +:: +:: - `%void` -- impossible to create. +:: - `%noun` -- could be any noun. +:: - `%atom` -- always some type of atom; never a cell +:: - `%cell` -- always some type of cell; never an atom. +:: - `%junc` -- is a fork of a cell type and an atom type. +:: ++$ xshape ?(%void %noun %atom %cell %junc) +:: +:: A `xrole` is the of a type, including a more refined understanding +:: of what xrole it plays within a fork. +:: +:: Nodes referenced within a `xrole` often do not actually exist in the +:: original type, since we need to reorganize forks in order to make +:: them more coherent. +:: +:: - `%void` -- impossible to create. +:: - `%noun` -- could be any noun. +:: - `%atom` -- always some type of atom; never a cell +:: - `%constant` -- a cell type whose head is a constant atom. +:: - `%tall` -- a cell type whose head is an atom. +:: - `%wide` -- a cell type whose head is also a cell +:: - `%instance` -- a cell type whose head is a constant atom. +:: - `%option` -- a union of types which are all constant atoms. +:: - `%union` -- a union of types which are all instances (cells whose +:: head is a constant atom). +:: - `%junction` -- a union of an atom type and a cell type. +:: - `%conjunction` -- a union of two cell types, one of them %wide +:: and the other %tall. +:: - `%misjunction` -- any other union type. There's no efficient way +:: to tell which branch to take when analyzing a fork which is a +:: %misjunction, and the type is probably improperly constructed. +:: ++$ xrole + $@ $? %void %noun %atom %tall %wide == + $% [%constant =atom] + [%instance =atom] + [%option =(map atom xkey)] + [%union =(map atom xkey)] + [%junction flat=xkey deep=xkey] + [%conjunction wide=xkey tall=xkey] + [%misjunction one=xkey two=xkey] + == +:: +:: This is just a utility type, it encodes the "battery" structure +:: within a core. +:: +:: It's a map from chapter names to the documentation and arms within +:: that chapter. +:: ++$ xbat (map term (pair what (map term xkey))) +:: +:: A recipe tells us how a type was constructed. +:: +:: - `%direct` is a simple type like `term`, or `xray`. +:: - `%synthetic` is a constructed type, like `(list @)`. +:: ++$ recipe + $% [%direct =term] + [%synthetic =term =(list xkey)] + == +:: +:: A `xpat` is high-level information about the shape of a type. This +:: is used for printing data. +:: +:: This is fairly heuristic. [%a %b %c ~] is recognized as a `path`, +:: `[3 ~[4 5 6]]` is recognized as a list, etc. +:: +:: Most of the xpats have names that make their purpose obvious: +:: for example, the %tape xpat means that data of type type can be +:: printed as if it had the `tape` type. However, `%gear` and `%gate` +:: might not be entirely obvious. +:: +:: - The %gear xpat is any core with a cell subject. +:: - The %gate xpat is a core that looks like a gate. +:: ++$ xpat + $@ ?(%hoon %manx %json %nock %path %plum %skin %spec %tape %tour %type %vase) + $% [%gate sample=xkey product=xkey] + [%gear sample=xkey context=xkey batt=xbat] + [%list item=xkey] + [%tree item=xkey] + [%unit item=xkey] + == +-- diff --git a/pkg/arvo/sys/hoon.hoon b/pkg/arvo/sys/hoon.hoon index be4824337..2ee202d4a 100644 --- a/pkg/arvo/sys/hoon.hoon +++ b/pkg/arvo/sys/hoon.hoon @@ -11425,180 +11425,6 @@ ~| %sell (~(deal us p.vax) q.vax) :: -:: These are the public types for the `xray` library. Analysing a type -:: yields an `ximage`, and everything else here is just some structure -:: within that. -:: -:: `ximage`s can be printed as specs (hoon syntax for types), and can -:: be used to pretty-print typed data. -:: -:: |% -:: -:: An `xtable` is a graph of types referenced by the top-level type, -:: and the `root` `key` points to the node which corresponds to the -:: type under analysis. -:: -+$ ximage [root=xkey =xtable] -:: -:: A `xkey` is just an identifier for a node in the xray graph. -:: -+$ xkey @ -:: -:: An `xtable` is the xray graph itself. It contains one node for for -:: the type that was analyzed and one node for every type referenced -:: within that type. -:: -:: The `next` field is the the next available xkey (used when inserting -:: new xrays), `xrays` maps keys to graph nodes and `type-map` gives -:: the xkey corresponding to a type. -:: -:: The `type-map` is basically just the reverse of the `xrays` map. It -:: doesn't contain any new information, but is needed for performance -:: reasons. -:: -+$ xtable [next=xkey xrays=(map xkey xray) =type=(map type xkey)] -:: -:: An `xray` is a node in the `ximage` graph. It contains everything -:: we know about a certain `type`. `key` is its identifier in the graph, -:: `type` is the type that it's an xray of, and `xdat` is the basic -:: information we derived about the type. The basic references to other -:: nodes are inside the `xdat` structure, though some of the other -:: fields may contain references as well. -:: -:: - `xshape` is some more information about the xshape of data within -:: a cell. -:: - `xrole` expands on `xshape`, adding further information about the -:: xrole that a node has within a fork. -:: - `pats` is used for printing data: we want to know if this type -:: can be printed as a list, as json, as a tape literal, etc. -:: - `recipes` contains information about how a type was -:: constructed. It's used to get much nicer output when printing types. -:: - `studs` contains "standards names". I actually don't know what this is. -:: - `helps` contains all the documentation about a type. -:: - `loop` indicates whether or not a node references itself. The list -:: type is cyclical, for example. This is used when printing an -:: `ximage`. -:: -+$ xray - $: =xkey - =type - xdat=(unit xdat) - xrole=(unit xrole) - pats=(unit xpat) - studs=(set stud) - recipes=(set recipe) - helps=(set help) - xshape=(unit xshape) - loop=(unit ?) - == -:: -:: - `%void` -- impossible to create. -:: - `%noun` -- could be any noun. -:: - `%atom` -- An atom of some aura, possibly constant -:: - `%cell` -- A cell with a head and a tail. -:: - `%core` -- A core, its garb, its context type, and the types of -:: each of its arms. -:: - `%face` -- A face on another type. -:: - `%fork` -- Could be one or more other types. -:: - `%pntr` -- This is an internal hack, it should never survive -:: analysis; ignore. -:: -+$ xdat - $@ ?(%noun %void) - $% [%atom =aura constant=(unit @)] - [%cell head=xkey tail=xkey] - [%core =garb xray=xkey batt=xbat] - [%face face=$@(term tune) xray=xkey] - [%fork =(set xkey)] - [%pntr xray=xkey] - == -:: -:: The basic xshape of a type: -:: -:: - `%void` -- impossible to create. -:: - `%noun` -- could be any noun. -:: - `%atom` -- always some type of atom; never a cell -:: - `%cell` -- always some type of cell; never an atom. -:: - `%junc` -- is a fork of a cell type and an atom type. -:: -+$ xshape ?(%void %noun %atom %cell %junc) -:: -:: A `xrole` is the of a type, including a more refined understanding -:: of what xrole it plays within a fork. -:: -:: Nodes referenced within a `xrole` often do not actually exist in the -:: original type, since we need to reorganize forks in order to make -:: them more coherent. -:: -:: - `%void` -- impossible to create. -:: - `%noun` -- could be any noun. -:: - `%atom` -- always some type of atom; never a cell -:: - `%constant` -- a cell type whose head is a constant atom. -:: - `%tall` -- a cell type whose head is an atom. -:: - `%wide` -- a cell type whose head is also a cell -:: - `%instance` -- a cell type whose head is a constant atom. -:: - `%option` -- a union of types which are all constant atoms. -:: - `%union` -- a union of types which are all instances (cells whose -:: head is a constant atom). -:: - `%junction` -- a union of an atom type and a cell type. -:: - `%conjunction` -- a union of two cell types, one of them %wide -:: and the other %tall. -:: - `%misjunction` -- any other union type. There's no efficient way -:: to tell which branch to take when analyzing a fork which is a -:: %misjunction, and the type is probably improperly constructed. -:: -+$ xrole - $@ $? %void %noun %atom %tall %wide == - $% [%constant =atom] - [%instance =atom] - [%option =(map atom xkey)] - [%union =(map atom xkey)] - [%junction flat=xkey deep=xkey] - [%conjunction wide=xkey tall=xkey] - [%misjunction one=xkey two=xkey] - == -:: -:: This is just a utility type, it encodes the "battery" structure -:: within a core. -:: -:: It's a map from chapter names to the documentation and arms within -:: that chapter. -:: -+$ xbat (map term (pair what (map term xkey))) -:: -:: A recipe tells us how a type was constructed. -:: -:: - `%direct` is a simple type like `term`, or `xray`. -:: - `%synthetic` is a constructed type, like `(list @)`. -:: -+$ recipe - $% [%direct =term] - [%synthetic =term =(list xkey)] - == -:: -:: A `xpat` is high-level information about the shape of a type. This -:: is used for printing data. -:: -:: This is fairly heuristic. [%a %b %c ~] is recognized as a `path`, -:: `[3 ~[4 5 6]]` is recognized as a list, etc. -:: -:: Most of the xpats have names that make their purpose obvious: -:: for example, the %tape xpat means that data of type type can be -:: printed as if it had the `tape` type. However, `%gear` and `%gate` -:: might not be entirely obvious. -:: -:: - The %gear xpat is any core with a cell subject. -:: - The %gate xpat is a core that looks like a gate. -:: -+$ xpat - $@ ?(%hoon %manx %json %nock %path %plum %skin %spec %tape %tour %type %vase) - $% [%gate sample=xkey product=xkey] - [%gear sample=xkey context=xkey batt=xbat] - [%list item=xkey] - [%tree item=xkey] - [%unit item=xkey] - == -:: :: Left-fold over a list. :: :: This is `roll`, but with explicit type parameters.