Arvo • Language • docs.urbit.org

The arvo.hoon file primarily contains the basic event processing and routing machinery of Arvo, but it also defines a number of useful types and other functions. Some of these have been excluded as they're obscure types only used internally by Arvo, but the rest are documented below.

`+$arch`

Node identity

This represents a node in Clay, which may be a file or a directory.

Source

+$  arch  (axil @uvI)

Examples

> *arch
[fil=~ dir={}]

> .^(arch %cy %/sys)
[ fil=~
    dir
  { [p=~.hoon q=~]
    [p=~.lull q=~]
    [p=~.kelvin q=~]
    [p=~.vane q=~]
    [p=~.arvo q=~]
    [p=~.zuse q=~]
  }
]

> .^(arch %cy %/sys/arvo/hoon)
[   fil
  [ ~
    0v1s.31due.jlkt7.btvob.bhil7.fusae.55huv.7pghe.2ql6f.l495n.pi6ah
  ]
  dir={}
]

`++axal`

Fundamental node, recursive

This mold builder creates a representation of a node in Clay like an arch or axil, but the directory map contains more axals, so it contains the entire subtree rather than just one level.

Source

++  axal
  |$  [item]
  [fil=(unit item) dir=(map @ta $)]

Examples

> *(axal @uvI)
[fil=~ dir={}]

> =/  =path  /sys/vane
  |-
  =+  .^(=arch %cy (en-beam [our %base da+now] path))
  ^-  (axal @uvI)
  :-  fil.arch
  (~(urn by dir.arch) |=([name=@ta ~] ^$(path (snoc path name))))
[ fil=~
    dir
  { [p=~.iris q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v15.r0nos.81rq5.8t24j.vfnll.8ej0n.knuej.maetm.vr9ja.s3opn.5gtpd] dir={}]]}]]
    [p=~.clay q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v12.hdbo4.a9j11.amut0.76dvc.cd69g.djmv9.nl9gi.e8m2t.jjfjl.i6sj3] dir={}]]}]]
    [p=~.eyre q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v1a.l7oim.58p0r.j3qc6.jqce6.r1frb.2jc7u.oqs4f.cf14o.aucva.7vv43] dir={}]]}]]
    [p=~.dill q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0vq.r959f.eiqhv.0ujnq.4eb0r.3qtjq.lcsqt.ef8bu.lul18.abngb.1dbgl] dir={}]]}]]
    [p=~.ames q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0vb.va2dn.8ue5p.5bqal.tn08n.ce2k9.g2c55.dd4tc.5tv9d.7kru2.vvsh1] dir={}]]}]]
    [p=~.gall q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v13.ovi2q.3vcok.4pn5v.470rl.msg6p.oo5rn.neoai.allbh.8ora9.h26it] dir={}]]}]]
    [p=~.khan q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v1j.dnfbn.l5cts.4us65.cct40.2urng.hchvv.s2nvs.8pmnp.p7l3l.tqqer] dir={}]]}]]
    [p=~.behn q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0vu.4qadi.sar0t.rbp15.5n8o9.o6ifv.f52bj.nhof9.cl2nr.3osck.8d4ie] dir={}]]}]]
    [p=~.jael q=[fil=~ dir={[p=~.hoon q=[fil=[~ 0v5.4gubl.1bpjb.rnbrq.mir68.c25tq.euqfm.vqvg7.esv65.gp2in.r03op] dir={}]]}]]
  }
]

`++axil`

Fundamental node

This is the mold builder used to create a representation of a node in Clay. It's used by arch.

Source

++  axil
  |$  [item]
  [fil=(unit item) dir=(map @ta ~)]

Examples

> *(axil @uvI)
[fil=~ dir={}]

> .^((axil @uvI) %cy %/sys/vane)
[ fil=~
    dir
  { [p=~.iris q=~]
    [p=~.clay q=~]
    [p=~.eyre q=~]
    [p=~.dill q=~]
    [p=~.ames q=~]
    [p=~.gall q=~]
    [p=~.khan q=~]
    [p=~.behn q=~]
    [p=~.jael q=~]
  }
]

`+$beak`

Global context

This is the unencoded global path prefix for a node in Clay. It's a triple of a ship, desk and case. The case is a revision reference.

Source

+$  beak  (trel ship desk case)

Examples

> *beak
[p=~zod q=%$ r=[%ud p=0]]

> `beak`[our %base da+now]
[p=~zod q=%base r=[%da p=~2022.11.8..10.16.14..757a]]

> `beak`[our %base ud+1]
[p=~zod q=%base r=[%ud p=1]]

> `beak`[our %base tas+'foo']
[p=~zod q=%base r=[%tas p=%foo]]

`+$beam`

Global name

An unencoded global path to a node in Clay. The beak denotes the ship, desk and case (revision reference), and then s is the path to the node therein.

Source

+$  beam  [beak s=path]

Examples

> *beam
[[p=~zod q=%$ r=[%ud p=0]] s=/]

> `beam`[[our %base ud+1] /foo/bar]
[[p=~zod q=%base r=[%ud p=1]] s=/foo/bar]

`+$bone`

Opaque duct handle

This is used by Ames to identify a particular message flow over the network.

Source

+$  bone  @ud

Examples

> *bone
0

> .^([snd=(set bone) rcv=(set bone)] %ax /=//=/bones/~nes)
[snd={0} rcv={}]

`+$case`

Global version

A reference to a particular revision in Clay. It may be one of:

%da: a date.
%tas: a label (these are seldom used).
%ud: a revision number. The initial commit is 1, and then each subsequent commit increments it.

+$  case
  $%  [%da p=@da]
      [%tas p=@tas]
      [%ud p=@ud]
  ==

Examples

> *case
[%ud p=0]

> `case`ud+123
[%ud p=123]

> `case`tas+'foo'
[%tas p=%foo]

> `case`da+now
[%da p=~2022.11.8..10.57.44..0e31]

`+$cage`

Marked vase

A pair of a mark and a vase (type-value pair). These are extensively used for passing data around between vanes and agents.

Source

+$  cage  (cask vase)

Example

> *cage
[p=%$ q=[#t/* q=0]]

> `cage`[%noun !>('foo')]
[p=%noun q=[#t/@t q=7.303.014]]

`++cask`

Marked data builder

Like a cage except rather than a vase, the tail is whatever type was given to the mold builder. These are most frequently used for sending data over the network, as vases can only be used locally.

Source

++  cask  |$  [a]  (pair mark a)

Examples

> *(cask)
[p=%$ q=0]

> *(cask @t)
[p=%$ q='']

> `(cask @t)`[%noun 'foobar']
[p=%noun q='foobar']

> `(cask)`[%noun 'foobar']
[p=%noun q=125.762.588.864.358]

`+$desk`

Local workspace

The name of a desk in Clay.

Source

+$  desk  @tas

Examples

> *desk
%$

> `desk`%base
%base

`+$dock`

Message target

A pair of a ship and Gall agent name. This is most frequently used when composing cards to other agents in a Gall agent.

Source

+$  dock  (pair @p term)

Examples

> *dock
[p=~zod q=%$]

> `dock`[our %dojo]
[p=~zod q=%dojo]

`+$gang`

Infinite set of peers

This is used internally by the Scry interfaces in Arvo and its vanes.

Source

+$  gang  (unit (set ship))

Examples

> *gang
~

> `gang`[~ (silt ~zod ~nec ~)]
[~ {~nec ~zod}]

`+$mark`

Symbolic content type

The name of a mark file. It will typically correspond to a file in the /mar directory of a desk.

Source

+$  mark  @tas

Examples

> *mark
%$

> `mark`%json
%json

`+$mien`

Orientation

Some basic information given to Arvo: the local ship's name, the current time, and some entropy.

Source

+$  mien  [our=ship now=@da eny=@uvJ]

Examples

> *mien
[our=~zod now=~2000.1.1 eny=0v0]

`+$page`

Untyped cage

A pair of a mark and a raw, untyped noun. This is primarily used in Clay.

Source

+$  page  (cask)

Examples

> *page
[p=%$ q=0]

> `page`[%noun [123 'abc']]
[p=%noun q=[123 6.513.249]]

`++omen`

Namespace path and data

Source

++  omen  |$  [a]  (pair path (cask a))

Examples

> *(omen @t)
[p=/ q=[p=%$ q='']]

`+$ship`

Network identity

Another name for an @p.

Source

+$  ship  @p

Examples

> *ship
~zod

> `ship`~sampel
~sampel

`+$sink`

Subscription

A triple of a bone, ship and path.

Source

+$  sink  (trel bone ship path)

Examples

> *sink
[p=0 q=~zod r=/]

`++hypo`

Type-associated builder

A pair of a type and some value.

Source

++  hypo
  |$  [a]
  (pair type a)

Example

> *(hypo)
[#t/* q=0]

`+$meta`

Meta-vase

Source

+$  meta  (pair)

Examples

> *meta
[p=0 q=0]

`+$maze`

Vase, or meta-vase

Source

+$  maze  (each vase meta)

Examples

> *maze
[%.y p=[#t/* q=0]]

`+$ball`

Dynamic kernel action

This contains the action or response in a kernel move. One of:

[%hurl [%error-tag stack-trace] wite=pass-or-gift]: action failed; error.
[%pass wire=/vane-name/etc note=[vane=%vane-name task=[%.y p=vase]]]: advance; request.
[%slip note=[vane=%vane-name task=[%.y p=vase]]]: lateral; make a request as though you're a different vane.
[%give gift=[%.y vase]: retreat; response.

Source

+$  ball  (wite [vane=term task=maze] maze)

Examples

> *ball
[%give gift=[%.y p=[#t/* q=0]]]

`+$card`

Tagged, untyped event

Note this is not the same as a card:agent:gall used in Gall agents.

Source

+$  card  (cask)

Examples

> *card
[p=%$ q=0]

`+$duct`

Causal history

Arvo is designed to avoid the usual state of complex event networks: event spaghetti. We keep track of every event's cause so that we have a clear causal chain for every computation. At the bottom of every chain is a Unix I/O event, such as a network request, terminal input, file sync, or timer event. We push every step in the path the request takes onto the chain until we get to the terminal cause of the computation. Then we use this causal stack to route results back to the caller.

The Arvo causal stack is called a duct. This is represented simply as a list of wires (paths), where each path represents a step in the causal chain. The first element in the path is the vane handled that step in the computation, or an empty string for Unix.

Source

+$  duct  (list wire)

Examples

> `duct`-:~(tap in .^((set duct) %cx /=//=/tyre))
~[/gall/use/docket/0w3.kF2UY/~zod/tire /dill //term/1]

`++hobo`

%soft task builder

Source

++  hobo
  |$  [a]
  $?  $%  [%soft p=*]
      ==
      a
  ==

Examples

> *(hobo maze)
[%.y p=[#t/* q=0]]

`+$goof`

Crash label and trace

Source

+$  goof  [mote=term =tang]

Examples

> *goof
[mote=%$ tang=~]

`+$mass`

Memory usage

+whey produces a (list mass) for its memory report.

Source

+$  mass  $~  $+|+~
          (pair cord (each * (list mass)))

Examples

> *mass
[p='' q=[%.n p=~]]

`+$move`

Cause and action

Arvo makes calls and produces results by processing moves. The duct is a call stack, and the ball contains the action or response.

Source

+$  move  [=duct =ball]

Example

> *move
[duct=~ ball=[%give gift=[%.y p=[#t/* q=0]]]]

`+$ovum`

card with cause

Source

+$  ovum  [=wire =card]

Examples

> *ovum
[wire=/ card=[p=%$ q=0]]

`+$roof`

Namespace

Source

+$  roof  (room vase)                                   ::  namespace

`+$rook`

Meta-namespace (super advanced)

Source

+$  rook  (room meta)                                   ::  meta-namespace

`++room`

Generic namespace

This is used internally for scry handlers.

Source

++  room                                                ::  either namespace
  |$  [a]
  $~  =>(~ |~(* ~))
  $-  $:  lyc=gang                                      ::  leakset
          vis=view                                      ::  perspective
          bem=beam                                      ::  path
      ==                                                ::
  %-  unit                                              ::  ~: unknown
  %-  unit                                              ::  ~ ~: invalid
  (cask a)

`+$roon`

Partial namespace

Source

+$  roon                                                ::  partial namespace
  $~  =>(~ |~(* ~))
  $-  [lyc=gang car=term bem=beam]
  (unit (unit cage))

`+$root`

Raw namespace

Source

+$  root  $-(^ (unit (unit)))

`+$view`

Namespace perspective

Source

+$  view  $@(term [way=term car=term])

`++wind`

Kernel action builder

This is similar to wite but without the error case. It's most commonly used in the type of a card:agent:gall.

Source

::
++  wind
  |$  ::  a: forward
      ::  b: reverse
      ::
      [a b]
  $%  ::  %pass: advance
      ::  %slip: lateral
      ::  %give: retreat
      ::
      [%pass p=path q=a]
      [%slip p=a]
      [%give p=b]
  ==

Examples

> *(wind note:agent:gall gift:agent:gall)
[%give p=[%poke-ack p=~]]

`+$wire`

Event pretext

Type-wise, a wire is the same as a path; a list of knots with the syntax of /foo/bar/baz. While a path is typically used in requests to denote a scry or subscription endpoint, a wire is used for responses.

On the kernel-level, wires are used in ducts to represent a causal step in a call stack for routing purposes. In userspace, they're used the same way under the hood, but practically speaking, they can be thought of as "tags" for responses. That is, when you make a request to a vane of Gall agent, you provide a wire for any responses you get back, and you can use this to identity what the response is for.

Source

+$  wire  path

Examples

> *wire
/

> `wire`/foo/bar/baz
/foo/bar/baz

`++wite`

Kernel action/error builder

This is used by the kernel in moves. See the ball entry for further details.

Source

++  wite
  |$  ::  note: a routed $task
      ::  gift: a reverse action
      ::
      ::    NB:  task: a forward action
      ::         sign: a sourced $gift
      ::
      [note gift]
  $%  ::  %hurl: action failed
      ::  %pass: advance
      ::  %slip: lateral
      ::  %give: retreat
      ::
      [%hurl =goof wite=$;($>(?(%pass %give) $))]
      [%pass =wire =note]
      [%slip =note]
      [%give =gift]
  ==

Examples

> *(wite [vane=term task=maze] maze)
[%give gift=[%.y p=[#t/* q=0]]]

`++en-beam`

Encode a beam in a path

Accepts

A beam

Produces

A path

Source

++  en-beam
  |=(b=beam =*(s scot `path`[(s %p p.b) q.b (s r.b) s.b]))

Examples

> (en-beam [~zod %base da+now] /foo/bar)
/~zod/base/~2023.1.9..10.35.30..f55a/foo/bar

`++de-beam`

Decode a beam from a path

Accepts

A path

Produces

A beam in a unit, which is null if parsing failed.

Source

++  de-beam
  ~/  %de-beam
  |=  p=path
  ^-  (unit beam)
  ?.  ?=([@ @ @ *] p)  ~
  ?~  who=(slaw %p i.p)  ~
  ?~  des=?~(i.t.p (some %$) (slaw %tas i.t.p))  ~  :: XX +sym ;~(pose low (easy %$))
  ?~  ved=(de-case i.t.t.p)  ~
  `[[`ship`u.who `desk`u.des u.ved] t.t.t.p]

Examples

> (de-beam /~zod/base/~2023.1.9..10.35.30..f55a/foo/bar)
[~ [[p=~zod q=%base r=[%da p=~2023.1.9..10.35.30..f55a]] s=/foo/bar]]

`++de-case`

Parse a case

Accepts

A knot

Produces

A case in a unit, which is null if parsing failed.

Source

++  de-case
  ~/  %de-case
  |=  =knot
  ^-  (unit case)
  ?^  num=(slaw %ud knot)  `[%ud u.num]
  ?^  wen=(slaw %da knot)  `[%da u.wen]
  ?~  lab=(slaw %tas knot)  ~
  `[%tas u.lab]

Example

> (de-case '2')
[~ [%ud p=2]]

> (de-case '~2023.1.9..10.31.15..58ea')
[~ [%da p=~2023.1.9..10.31.15..58ea]]

> (de-case 'foo')
[~ [%tas p=%foo]]

> (de-case '!!!')
~