shrub/pkg/arvo/sur/xray.hoon

::
::  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]
  ==
--