10 KiB
+++ title = "Vases" description = "Learn about dynamically typed data" weight = 115 +++
Overview
A $vase
is a pair of
$type
and
$noun
, where the type describes the noun.
They're used all over Urbit to represent data whose type we can't know ahead of
time. This often comes up when being asked to compile and run other Hoon code.
It's also used to store data that could be any type, but where we want to know
the type, so we tag the value with its type to form a vase.
- The Arvo kernel uses vases to build itself and run vanes (kernel modules).
- The Gall vane used to use vases to run userspace agents, and probably will again in the future.
- The Ford build system (in the Clay vane) uses vases to build Hoon code and store typed files.
- The Dojo shell uses vases to compile and run shell expressions and to run generators.
- The Spider agent uses vases to run threads (scripts written in an IO monad).
Types and Molds
A Hoon $type
is a data structure that specifies a set of nouns. Remember,
everything in Urbit is a noun, so a $type
can be thought of as a way of
representing a boolean predicate that determines whether some noun is within the
set.
Types are not just used for this purpose, though. They're also used to represent the type of the "subject", which is the "scope" or "environment" that some Hoon code can access. This means that Hoon's equivalent of a symbol table lives in the type.
The programmer can name parts of a type, including the type of the subject. Once
part of a type has a name, Hoon code can refer to any named field within that
type. Since the subject of any Hoon expression always has a known type at
compile time, a reference (a wing, like
foo.+<.bar.|3.baz
) to a field within that subject is compiled to a Nock 0
operation (subtree lookups) at a known constant
axis (tree slot).
A Hoon $type
is defined by this (pronounced "buc type", also called "the type
of type"):
+$ 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
== ::
This is a union, meaning a type can be one of several different things. It's a discriminable union, meaning a piece of code can tell which kind of thing a type is by inspecting it.
If an instance of $type
is an atom, it's either the value %noun
, referring
to any noun (the set of all nouns), or %void
, referring to nothing (the empty
set, so no noun will ever be part of this set). %void
is mostly there for
mathematical completeness, so the compiler can represent the null set internally
-- any "inhabited" type will not be %void
.
Otherwise, an instance of $type
is a cell, in which case the head is a tag
(e.g. %atom
, %cell
, or %core
) that says what kind of type this is. The
values to the right of the tag contain the information used to specify the
variable lookup namespace for this type (i.e. the mapping from wing to axis, or
axis and core arm) and constraints that limit the set of nouns described by this
type.
An %atom
type describes a set of numbers. The p=term
in an atom type is its
aura, a name for a kind of value that can be stored
as an atom -- %da
for date, %ux
for hexadecimal number, %t
for text, etc.
The q=(unit @)
is either ~
, meaning any value, or [~ value]
, in which case
this type has only a single member. The type %foo
refers to the set whose only
instance is the atom %foo
.
The %cell
type refers to cells whose heads have type p
and tails have type
q
.
When working with types, %hold
types are particularly important to understand.
A %hold
is a lazily evaluated type. This is used for recursive types and
polymorphism (wetness). A hold contains a p=type
, referring to a subject type,
and a q=hoon
, a hoon expression intended to be run on a value of that 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
.
Consider the type (list @ud)
. This is a hold. Just as any instance of this
list type is either ~
or a non-null list [i=@ud t=(list @ud)]
, when you
evaluate the list's hold, you get a fork of [%atom %n [~ ~]]
and [%cell [%face %i [%atom %ud ~]] [%face %t [%hold ...]]]
, where the hold is the same as
the original hold.
Cores
All executable Hoon code is found in a core. This
core stores a map from arm name (like an OOP getter
function) to result type, along with some other information about the core. If
the core is a door (like an OOP object) or a
gate (like an anonymous function), then slot 6 (the
head of the tail) of the core is a "sample" slot, which is overwritten with
instance data or function argument, respectively. Whether this core expects a
sample, and if so, what the sample's type is, is represented in the $type
data
structure for cores of that type.
Core types are more complex than this simplified explanation, but this description is hopefully enough detail to be able to work with cores from vase mode.
"Slap'n'Slop" Vase Algebra
The vase operations form a relatively simple algebra. This algebra can be
thought of as a dynamically typed programming language. Each value in the
language is a vase (a dynamically typed datum), and the basic operations are
+slap
and
+slop
.
For example, the Hoon expression (slap (slop v1 (slop v2 (slap v3 h1)) v4) h2)
takes in four vases and two hoon expressions, and produces a vase. A pseudocode
version of this would be h2([v1 v2 h1(v3)])
Introduction Forms
The primary introduction form for a vase is the
!>
rune, which produces a vase of its
input. A vase can also be constructed manually as a cell whose head nests in
$type
, like [[%atom %ud ~] 3]
.
Elimination Forms
An elimination form for a vase is something that converts a vase to a statically typed value.
One unsafe elimination form is the !<
rune, which takes a mold and a value and (unsafely) converts the value to a
typed value. The more traditional elimination form has no syntactic support, but
involves pattern-matching on the type data structure, e.g. dispatching based on
whether the type is atom, cell, or something else, and coercing the value to a
specific type using a mold function.
The lack of a safe general-purpose elimination form stems from the fact that Hoon's structural type system cannot guarantee that the value in a vase's tail is an instance of the type in the vase's head, i.e. is an instance of that type. If not, the vase is said to be "evil".
Despite this limitation, it's relatively straightforward to convert vases to statically typed outputs safely, and plenty of Hoon code does it, in both kernelspace and userspace.
Fundamental Operations
The +slap
gate runs a hoon expression against a vase, producing a vase of the
result. The +slop
gate combines a pair of vases into a vase of a pair. These
operations can be composed arbitrarily, and higher-level operations can be built
out of them.
:: in /sys/hoon/hoon
::
++ slop :: cons two vases
|= [hed=vase tal=vase]
^- vase
[[%cell p.hed p.tal] [q.hed q.tal]]
::
++ slap
|= [vax=vase gen=hoon] ^- vase :: untyped vase .*
=+ gun=(~(mint ut p.vax) %noun gen)
[p.gun .*(q.vax q.gun)]
+slop
is the simplest vase operation. It converts a cell of vases into a vase
of a cell. It does this by making a pair [q.hed q.tal]
of the values of the
two input vases, and it constructs the type of the output vase as [%cell p.hed p.tal]
, i.e. a cell whose head has the type as the first vase and whose tail
has the same type as the second vase.
+slap
first compiles a parsed Hoon expression (gen
) using +mint:ut
, with
the type of the subject.
Examples
> (slop !>('foo') !>('bar'))
[#t/[@t @t] q=[7.303.014 7.496.034]]
> !< [@t @t] (slop !>('foo') !>('bar'))
['foo' 'bar']
> (slap !>(.) !,(*hoon (add 1 1)))
[#t/@ q=2]
Higher-Level Operations
There are a lot of higher-level operations on vases, mostly in /sys/hoon/hoon
and some in /sys/arvo/hoon
. Here's a sampling for instructional purposes.
+slam
Slam a gate with a sample
++ slam
|= [gat=vase sam=vase] ^- vase
=+ :- ^= typ ^- type
[%cell p.gat p.sam]
^= gen ^- hoon
[%cnsg [%$ ~] [%$ 2] [%$ 3] ~]
=+ gun=(~(mint ut typ) %noun gen)
[p.gun (slum q.gat q.sam)]
+slot
Got noun at axis (tree address)
++ slot
|= [axe=@ vax=vase] ^- vase
[(~(peek ut p.vax) %free axe) .*(q.vax [0 axe])]
Examples
> (slam !>(add) !>([1 1]))
[#t/@ q=2]
> (slot 6 !>([1 2 3 4]))
[#t/@ud q=2]
Further Reading
- Standard library section 5c: This contains most of the vase functions in the standard library.