git.iko.soy/urbit.org

on master help sign in

_index.mdnew file+7

@@ -0,0 +1,7 @@

1++++

2+title = "Docs"

3+template = "sections/docs.html"

4++++

5+Welcome to the documentation for the Urbit project, including the Azimuth identity layer, the Arvo operating system, and the Hoon programming language. This documentation is maintained by [Tlon](https://tlon.io) in a public [Github repository](https://github.com/urbit/docs). Issues and contributions are welcome.

6+

7+Please make your way to the [Introduction](docs/introduction) for an overview of the docs.

concepts.udondeleted−43

@@ -1,43 +0,0 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'3'

5− title/'Concepts'

6− ==

7−;>

8−

9−# Concepts

10−

11−The documents in this section are high-level introductions to the Urbit project and components thereof.

12−

13−## [Azimuth](/docs/concepts/azimuth)

14−

15−A quick explanation of Azimuth, the Urbit identity layer. This document also explains how Azimuth and Arvo are different, while being the two parallel systems that compose Urbit.

16−

17−### [Why Urbit Uses a Blockchain](/docs/concepts/azimuth/blockchain)

18−

19−Azimuth is built on the Ethereum blockchain. This document explains why.

20−

21−### [The Urbit HD Wallet](/docs/concepts/azimuth/blockchain)

22−

23−A detailed discussion of the unique wallet system used to own and manage Azimuth identities.

24−

25−## [Technical Overview](/docs/concepts/technical-overview)

26−

27−A more in-depth description of the entire Urbit stack.

28−

29−## [Contributing](/docs/concepts/contributing)

30−

31−A guide to getting involved with the Urbit project.

32−

33−## [Community Tutorials](/docs/concepts/community-tutorials)

34−

35−A collection of unofficial but useful Urbit learning resources.

36−

37−## [Source Code](/docs/concepts/source-code-overview)

38−

39−An explanation of Urbit's constituent GitHub repos.

40−

41−## [Galaxies, Stars, and Planets](/docs/concepts/galaxies-stars-and-planets)

42−

43−An explanation of the Urbit address-space hierarchy.

concepts/_index.mdnew file+7

@@ -0,0 +1,7 @@

1++++

2+title = "Concepts"

3+weight = 3

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

7+The documents in this section are high-level introductions to the Urbit project and components thereof.

concepts/arvo-vs-azimuth.mdnew file+15

@@ -0,0 +1,15 @@

1++++

2+title = "Arvo vs. Azimuth"

3+weight = 4

4+template = "doc.html"

5+description = "A quick explanation of the two parallel systems that compose Urbit."

6++++

7+Urbit is a project, not a single computer system. It has three components: Arvo, the operating system; Azimuth, the identity system; and Aegean, the pattern for creating software experiences for individual Urbit communities. This document compares the first two.

8+

9+[*Arvo*](https://github.com/urbit/arvo) is an operating system that provides the software for a personal server. These personal servers together constitute the peer-to-peer Arvo network. To make this network work on the social level, Arvo is built to work with a system of scarce and immutable identities.

10+

11+[*Azimuth*](https://github.com/urbit/azimuth) is the public-key infrastructure built to be such a system. A suite of smart-contracts on the Ethereum blockchain, Azimuth determines which Ethereum addresses own which Azimuth identities, called _points_. All point-related operations, such as transfers, are governed at this layer. But Azimuth isn't built strictly for Arvo -- it could be used as a generalized identity system for other projects.

12+

13+These otherwise-parallel systems meet when you want to connect to the Arvo network. Your Arvo personal server, called your _ship_, needs to be able to prove cryptographically that it is who it says it is. This proof comes in the form of a keyfile, derived from your point, that you use to start your ship.

14+

15+A metaphor might help illustrate the relationship between these two systems: the Arvo network is the neighborhood that you live in; Azimuth is the bank vault that stores the deed to your house.

concepts/azimuth.udon → concepts/azimuth/_index.mdrenamed+6−21

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− next/'false'

3− sort/'9'

4− title/'Azimuth'

5− ==

6−;>

7−

8−# Azimuth

9−

1++++

2+title = "Azimuth"

3+weight = 6

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a platform for Urbit identities that we call _points_. You need a point to use the Arvo network.

118

129The primary way to interact with Azimuth is through our [Bridge](https://github.com/urbit/bridge) application and the node libraries that it depends on, azimuth-js and keygen-js. Take a look at the source and play around or see [Getting Started](/docs/getting-started).

@@ -22,15 +19,3 @@ Urbit is a project, not a single computer system. It has three components: Arvo,

2219These otherwise-parallel systems meet when you want to connect to the Arvo network. Your Arvo personal server, called your _ship_, needs to be able to prove cryptographically that it is who it says it is. This proof comes in the form of a keyfile, derived from your point, that you use to start your ship.

2320

2421A metaphor might help illustrate the relationship between these two systems: the Arvo network is the neighborhood that you live in; Azimuth is the bank vault that stores the deed to your house.

25−

26−## Further Reading

27−

28−If you want to know more about Azimuth, check out the pages below.

29−

30−### [Why Urbit Uses a Blockchain](/docs/concepts/azimuth/blockchain)

31−

32−An explanation for why Ethereum makes sense for Azimuth.

33−

34−### [The Urbit HD Wallet](/docs/concepts/azimuth/wallet)

35−

36−A detailed discussion of the unique wallet system used to own and manage Azimuth identities.

concepts/azimuth/blockchain.udon → concepts/azimuth/blockchain.mdrenamed+8−10

@@ -1,10 +1,8 @@

1−:- :~ title/'Why Urbit Uses a Blockchain'

2− sort/'1'

3− ==

4−;>

5−

6−# Why Urbit Uses a Blockchain

7−

1++++

2+title = "Why Urbit Uses a Blockchain"

3+weight = 1

4+template = "doc.html"

5++++

86The Arvo network is composed of personal servers: instances of the Arvo operating system, called ships,

97that communicate as peers.

108

@@ -41,9 +39,9 @@ their property.

4139

4240Moving the Urbit land registry to Ethereum is an easy and obvious solution to

4341this problem. We chose Ethereum over Bitcoin because the former is built for

44−computation while the latter is not. We need a computational blockchain to

42+computation Landscape the latter is not. We need a computational blockchain to

4543enforce the specific rules of the Urbit identity registry.

4644

4745For more background on the decision to use the Ethereum blockchain, check out

48−[these](urbit.org/posts/essays/urbit-and-the-blockchain)

49−[two](urbit.org/posts/essays/bootstrapping-urbit-from-ethereum/) posts.

46+[these](https://urbit.org/posts/essays/urbit-and-the-blockchain/)

47+[two](https://urbit.org/posts/essays/bootstrapping-urbit-from-ethereum/) posts.

concepts/azimuth/wallet.udon → concepts/azimuth/wallet.mdrenamed+18−35

@@ -1,10 +1,8 @@

1−:- :~ title/'The Urbit HD Wallet'

2− sort/'2'

3− ==

4−;>

5−

6−# The Urbit HD Wallet

7−

1++++

2+title = "The Urbit HD Wallet"

3+weight = 2

4+template = "doc.html"

5++++

86Owners of Azimuth _points_ need safeguards that allow for the use of Urbit

97without jeopardizing cryptographic ownership of their assets. Toward this end,

108we created the *Urbit Hierarchical Deterministic (HD) Wallet* for the storage of

@@ -21,7 +19,7 @@ are also derived from the wallet.

2119Urbit HD wallets are composed of the following items, which are each assigned to

2220their own individual Ethereum key-pairs.

2321

24−## Master Ticket

22+#### Master Ticket

2523

2624Think of your master ticket like a very high-value password. The master ticket

2725is the secret code from which all of your other keys are derived. Technically,

@@ -29,49 +27,34 @@ your master ticket is seed entropy. You should never share it with anyone, and

2927store it very securely. This ticket can derive all of your other keys: your

3028ownership key and all of the related proxies.

3129

32−## Ownership Address

30+#### Ownership Address

3331

3432An ownership address has all rights over the assets deeded to it. These rights

3533are on-chain actions described and implemented in the Ecliptic, Azimuth's suite

3634of governing smart-contracts.

3735

38−## Proxies

36+#### Proxies

3937

4038Proxy addresses allow you to execute non-ownership related actions like spawning

4139child points, voting, and setting networking keys without jeopardizing the keys

4240you've designated with ownership rights. Setting proxy rights is optional, but

4341it is recommended for on-chain actions you will execute more frequently.

4442

45−### Management Proxy

46−

47−Can set Arvo networking keys and conduct sponsorship-related operations.

48−

49−#### Networking Keys

50−

51−Networking keys -- encryption and authentication key-pairs -- are used

52−for communicating on the Arvo network. They are contained in the keyfile

53−that you use to boot a ship.

54−

55−Unlike proxies, networking keys are not Ethereum wallets. They are just a public

56−key that is the point's state on the blockchain, combined with a private key

57−that is stored somewhere on your machine.

58−

59−The HD Wallet structure makes networking keys easy to change if the need arises.

60−If you want or need to rotate your keys, you only need to access your management proxy

61−to reset them. After you've done that, download a new keyfile and add it to your

62−ship.

43+- *Management Proxy*

6344

64−### Voting Proxy

45+ Can configure or set Arvo networking keys and conduct sponsorship related

46+ operations.

6547

66−Galaxies only. Galaxies are the part of the galactic senate, and this means

67−they can cast votes on new proposals including changes to the Ecliptic.

48+- *Voting Proxy*

6849

69−### Spawn Proxy

50+ Galaxies only. Galaxies are the part of the galactic senate, and this means

51+ they can cast votes on new proposals including changes to the Ecliptic.

7052

71−For stars and galaxies only. Can create new child points.

53+- *Spawn Proxy*

7254

55+ For stars and galaxies only. Can create new child points.

7356

74−;img@"https://media.urbit.org/fora/proposals/UP-8.jpg";

57+

7558

7659

7760Most Ethereum tokens use the ERC-20 standard for smart contracts. Azimuth points

@@ -88,5 +71,5 @@ Points, and all of their blockchain operations, are governed by the Ecliptic.

8871The Ecliptic is an Ethereum smart-contract that governs point state and the

8972ownership, spawn, management, and voting rights affiliated with your points.

9073

91−For the technical implementation details of Azimuth, take a look at the

74+For the technical implementation details Azimuth, take a look at the

9275[Github repo](https://github.com/urbit/azimuth).

concepts/community-tutorials.udon → concepts/community-tutorials.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− next/'false'

3− sort/'9'

4− title/'Community Tutorials'

5− ==

6−;>

7−

8−# Community Docs

9−

1++++

2+title = "Community Tutorials"

3+weight = 9

4+template = "doc.html"

5+description = "A collection of unofficial but useful Urbit learning resources."

6++++

107Here are some tutorials written by members of the Urbit community. Some are a little outdated, but they may still prove useful.

118

129- [Generators](https://github.com/joemfb/mardev/tree/master/docs/gen) by `~master-morzod`

concepts/contributing.udon → concepts/contributing.mdrenamed+7−10

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'3'

4− title/'Contributing'

5− ==

6−;>

7−

8−# Contributing

9−

1++++

2+title = "Contributing"

3+weight = 3

4+template = "doc.html"

5+description = "A guide to getting involved with the Urbit project."

6++++

107We accept submissions for improving our [code](https://github.com/urbit/urbit/) and [documentation](https://github.com/urbit/docs/) alike.

118

129If you're interested in contributing, but don't know where to start, feel free to [send us an email](mailto:support@urbit.org).

@@ -15,7 +12,7 @@ If you're interested in contributing, but don't know where to start, feel free t

1512

1613Our official guide to contributing can be found [here](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md), which is most useful for large and low-level changes.

1714

18−Before contributing code, you should familiarize yourself with the [Hoon style guide](/docs/learn/hoon/style). For a good example of preferred Hoon coding style, see [ford.hoon](https://github.com/urbit/arvo/blob/master/sys/vane/ford.hoon).

15+Before contributing code, you should familiarize yourself with the [Hoon style guide](/docs/learn/arvo/style). For a good example of preferred Hoon coding style, see [ford.hoon](https://github.com/urbit/arvo/blob/master/sys/vane/ford.hoon).

1916

2017## Community Guidelines

2118

concepts/galaxies-stars-and-planets.udon → concepts/galaxies-stars-and-planets.mdrenamed+7−7

@@ -1,9 +1,9 @@

1−:- :~ title/'Galaxies, Stars, and Planets'

2− ==

3−;>

4−

5−# Galaxies, Stars, and Planets

6−

1++++

2+title = "Galaxies, Stars, and Planets"

3+weight = 7

4+template = "doc.html"

5+description = "An explanation of the Urbit address-space hierarchy. "

6++++

77The current internet has no consistent system of identity. There are only quasi-identities such as IP addresses, Google accounts and email addresses, each able to be assumed and abandoned without much trouble. The result is a hostile social experience, since bad actors -- spammers, scammers, malware-spreaders, and harassers -- have an inexhaustible supply of places to hide.

88

99That's why we built a system for persistent identity called [Azimuth](../arvo-vs-azimuth). Azimuth identities are called _points_, and you need one to use the Arvo network. Points are secure, since they are owned and controlled with key-pair the Ethereum blockchain, which Azimuth is built on top of.

@@ -26,7 +26,7 @@ Planets are intended for everyday use by an adult human, and there is a maximum

2626

2727## Moons and Comets

2828

29−In addition to these three classes of Azimuth points, there two other kinds of Urbit identities, but they do _not_ use Azimuth.

29+In addition to these three classes of Azimuth points, there two other kinds of Urbit identities, but they do _not_ use Azimuth.

3030

3131*Moons* are 64 bits, are issued by planets, and have names like `~doznec-salfun-naptul-habrys`. Moons are meant for connected devices: phones, smart TVs, digital thermostats. Moons are not independent, but are subordinated to their parent planet.

3232

concepts/source-code-overview.udon → concepts/source-code-overview.mdrenamed+6−10

@@ -1,13 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'2'

5− title/'Source Code Overview'

6− ==

7−;>

8−

9−# Source Code Overview

10−

1++++

2+title = "Source Code Overview"

3+weight = 2

4+template = "doc.html"

5+description = "An explanation of Urbit's constituent GitHub repos."

6++++

117We host all our source code on GitHub at [github.com/urbit](https://github.com/urbit).

128

139Since there's quite a number of repos, we'll talk about a few of the most

concepts/technical-overview.udon → concepts/technical-overview.mdrenamed+7−11

@@ -1,13 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'1'

5− title/'Technical overview'

6− ==

7−;>

8−

9−# Technical overview

10−

1++++

2+title = "Technical overview"

3+weight = 1

4+template = "doc.html"

5+description = "A more in-depth description of the entire Urbit stack."

6++++

117Urbit is a clean-slate software stack designed to implement an encrypted P2P

128network of general-purpose personal servers. Each server on this network is a

139deterministic computer called an 'urbit' that runs on a Unix-based virtual

@@ -114,7 +110,7 @@ about 3000 lines of Hoon.

114110### Nock

115111

116112Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)

117−combinator language. It's so simple that its [specification](/docs/learn/nock/definition)

113+combinator language. It's so simple that its [specification](../../nock/definition)

118114fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions

119115are more narrow. Most Lisps are one-layer: a practical language is to be

120116created by extending a theoretically simple interpreter. The abstraction is

getting-started.udon → introduction/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'1'

4− title/'Getting Started'

5− ==

6−;>

7−

8−# Getting Started

9−

1++++

2+title = "Getting Started"

3+weight = 1

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107Pages in this section are guides to getting you started with Urbit.

118

129But first, the absolute basics. Arvo is the name of the Urbit operating system and the name of network. Azimuth is the name of the Urbit identity layer. Urbit is the project as the whole.

getting-started/booting-a-ship.udon → introduction/booting-a-ship.mdrenamed+6−8

@@ -1,10 +1,8 @@

1−:- :~ title/'Booting a Ship'

2− sort/'3'

3− ==

4−;>

5−

6−# Booting a Ship

7−

1++++

2+title = "Booting a Ship"

3+weight = 3

4+template = "doc.html"

5++++

86Now the rubber meets the road. You'll be booting your ship with the keyfile that you [downloaded from Bridge](../azimuth.udon).

97

108Note that this document is only for booting a ship that uses the live Arvo network. If you just want to create an unnetworked ship for development purposes, read [this guide](../creating-a-development-ship) instead.

@@ -13,7 +11,7 @@ Note that this document is only for booting a ship that uses the live Arvo netwo

1311

1412This will look something like `~lodleb-ritrul`. You can see the name of your point(s) when you log into your wallet using the Bridge client.

1513

16−;img@"http://media.urbit.org/site/bridge-0.png"(width "100%");

14+

1715

1816## Step 2: Find the path to your keyfile

1917

getting-started/creating-a-development-ship.udon → introduction/creating-a-development-ship.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Creating a Development Ship'

2− sort/'4'

3− ==

4−;>

5−

6−# Creating a Development Ship

7−

1++++

2+title = "Creating a Development Ship"

3+weight = 4

4+template = "doc.html"

5++++

86To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.

97

108Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](../installing-urbit).

getting-started/installing-urbit.udon → introduction/installing-urbit.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Installing Urbit'

2− sort/'2'

3− ==

4−;>

5−

6−# Installing Urbit

7−

1++++

2+title = "Installing Urbit"

3+weight = 2

4+template = "doc.html"

5++++

86Arvo runs nicely on a Unix-like operating system -- Ubuntu, Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need to get one of the aforementioned systems. Don't worry: most of them are free. Let's get it onto your machine.

97

108But first, some terminology:

getting-started/operating-a-star.udon → introduction/operating-a-star.mdrenamed+10−12

@@ -1,10 +1,8 @@

1−:- :~ title/'Operating a Star'

2− sort/'5'

3− ==

4−;>

5−

6−# Operating a Star

7−

1++++

2+title = "Operating a Star"

3+weight = 5

4+template = "doc.html"

5++++

86A _ship_ is an instance of the Arvo operating system that is used as a personal server on the Arvo network. Stars are a type of ship that act as infrastructure for the Arvo network. In the Arvo ship-hierarchy, stars are below galaxies and above planets.

97

108Parallel to the Arvo network is Azimuth, the Urbit identity system that uses the Ethereum blockchain. All ships must boot with a corresponding _point_ -- an Azimuth identity -- to use the Arvo network.

@@ -13,15 +11,15 @@ Important star operations happen on both the Arvo side and the Azimuth side. On

1311

1412## Powers of a Star

1513

16−Stars are above planets in the network hierarchy in the sense that each star sponsors some number of planets: stars assist their planets by facilitating peer discovery, routing packets, providing DNS routing, and pushing software updates. A star is the *sponsor* of the planets it provides those services to; those planets, in turn, are the *dependents* of that star.

14+Stars are above planets in the network hierarchy in the sense that each star sponsors some number of planets: stars discover peers for planets, route packets for planets, provide DNS routing for planets, and push software updates to planets. A star that fulfills this is called the *sponsor* of planets that receive such services from the star; those planets, in turn, are called *dependents* of that star.

1715

18−Stars are also the "parents" planets. A new planet comes into existence only when spawned by a parent star. A parent star is the sponsor of its child planets by default. This can change if a planet chooses to find a new sponsor (see the "Escaping a Sponsor" section below).

16+Stars are also the "parents" planets. A new planet comes into existence only when spawned by a parent star. A parent planet is the sponsor of its children planets by default. This can change if a planet chooses to find a new sponsor (see the "Escaping a Sponsor" section below).

1917

20−Planets must have a sponsor star to use most features of the Arvo network. A planet cannot fully boot without a sponsor, and cannot make new connections to peers as long as it is not connected to a sponsor. Sponsorless planets will still be able to message known peers, until they change their IP addresses.

18+Planets must have a sponsor star to use most features of the Arvo network. A planet cannot boot without a sponsor, and cannot make new connections to peers as long as it is not connected to a sponsor. Sponsorless planets will still be able to message discovered peers until any such peers change their IP addresses.

2119

2220## Responsibilities

2321

24−Like with real-life infrastructure, the operation of Arvo infrastructure comes with unique responsibilities. For reasons stated above, stars that are depended upon as sponsors should always be online on a reliable cloud service. These systems have layers of redundancies that make them much more resilient than local machines, so stars hosted in the cloud are unlikely to leave their dependents in the dark.

22+Like with real-life infrastructure, the operation of Arvo infrastructure comes with unique responsibilities. For reasons stated above, stars should be always be online on a reliable cloud service, such as Amazon Web Services or Google Cloud Platform. These systems have layers of redundancies that make them much more resilient than local machines, so stars hosted on the cloud are unlikely to leave their dependents in the dark.

2523

2624## Operations

2725

@@ -45,7 +43,7 @@ Occasionally, your star might lose network connectivity due to a known timer iss

4543

4644Planets are, of course, able to change sponsors. To do this, they must request that a different star takes them on as a dependent and that star must accept the request. Planets cannot emancipate themselves from a sponsor without having a new sponsor lined up.

4745

48−All of these actions happen on Azimuth. There will be [Bridge](../using-bridge) functionality to handle these actions in the future, but for now users will need to interact directly with the contracts with MetaMask, through services such as [Etherscan.io](https://etherscan.io/address/ecliptic.eth#writeContract). A sketch of the process is listed below; for now, only the Ethereum-savvy should act on these steps.

46+All of these actions happen on Azimuth. There will be Bridge functionality to handle these actions in the future, but for now users will need to interact directly with the contracts with MetaMask, through services such as [Etherscan.io](https://etherscan.io/address/ecliptic.eth#writeContract). A sketch of the process is listed below; for now, only the Ethereum-savvy should act on these steps.

4947

5048+ The planet calls the `escape` function in the Ecliptic contract and writes the resulting data to the blockchain.

5149+ If the chosen star wants to become the planet's sponsor, it calls the `adopt` function in the Ecliptic contract.

getting-started/using-bridge.udon → introduction/using-bridge.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Using Bridge'

2− sort/'1'

3− ==

4−;>

5−

6−# Using Bridge

7−

1++++

2+title = "Using Bridge"

3+weight = 1

4+template = "doc.html"

5++++

86[Bridge](https://github.com/urbit/bridge) is the client we built for interacting with [Azimuth](/docs/pki), the Urbit PKI, and managing your Azimuth identities, called _points_. Importantly, Bridge also allows you to generate a keyfile that you will need to boot your ship so that it can use the Arvo network.

97

108This guide assumes that you own an Azimuth point, or that you have found someone to send an Azimuth point to your Ethereum address and are looking to claim it.

learn.udon → learn/_index.mdrenamed+6−8

@@ -1,11 +1,9 @@

1−:- :~ navhome/'/docs/'

2− sort/'4'

3− title/'Learn'

4− ==

5−;>

6−

7−# Learn

8−

1++++

2+title = "Learn"

3+weight = 4

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

97Tutorials and explanations for all the components of Urbit.

108

119## Arvo(/docs/learn/arvo)

learn/arvo.udon → learn/arvo.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Arvo'

2− sort/'1'

3− ==

4−;>

5−

6−# Arvo

7−

1++++

2+title = "Arvo"

3+weight = 1

4+template = "doc.html"

5++++

86Arvo is Urbit's functional operating system, written in [Hoon](/docs/learn/hoon). It's composed of modules called _vanes_:

97

108## [Ames](ames)

learn/arvo/_index.mdnew file+112

@@ -0,0 +1,112 @@

1++++

2+title = "Arvo"

3+weight = 1

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

7+Arvo is Urbit's functional operating system, written in [Hoon](/docs/learn/hoon). It's composed of modules called _vanes_:

8+

9+## [Ames](ames)

10+

11+Ames is the name of our network and the vane that communicates over it. It's an encrypted P2P network composed of instances of the Arvo operating system.

12+

13+## [Behn](behn)

14+

15+Behn is our timer. It allows vanes and applications to set and timer events, which are managed in a simple priority queue.

16+

17+## [Clay](clay)

18+

19+Clay is our filesystem and revision-control system.

20+

21+## [Dill](dill)

22+

23+Dill is our terminal driver. Unix sends keyboard events to dill from the terminal, and dill produces terminal output.

24+

25+## [Eyre](eyre)

26+

27+Eyre is our HTTP server. Unix sends HTTP messages to `%eyre`, and `%eyre` produces HTTP messages in response.

28+

29+## [Ford](ford)

30+

31+Ford is our build system. It handles resources and publishing.

32+

33+## [Gall](gall)

34+

35+Gall is the vane for controlling userspace apps.

36+

37+### [Hall](hall)

38+

39+Hall isn't a vane, but an important Gall app that functions as the Urbit messaging protocol.

40+

41+## Principles

42+

43+At a high level `%arvo` takes a mess of Unix I/O events and turns them into something clean and structured for the programmer.

44+

45+`%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.

46+

47+### Ducts

48+

49+The `%arvo` causal stack is called a `++duct`. This is represented simply as a list of paths, where each path represents a step in the causal chain. The first element in the path is the first letter of whichever vane handled that step in the computation, or the empty span for Unix.

50+

51+Here's a duct that was recently observed in the wild:

52+

53+```

54+~[

55+ /g/a/~zod/4_shell_terminal/u/time

56+ /g/a/~zod/shell_terminal/u/child/4/main

57+ /g/a/~zod/terminal/u/txt

58+ /d/term-mess

59+ //term/1

60+]

61+```

62+

63+This is the duct the timer vane receives when "timer" sample app asks the timer vane to set a timer. This is also the duct over which the response is produced at the specified time. Unix sent a terminal keystroke event (enter), and Arvo routed it to `%dill` (our terminal), which passed it on to the `%gall` app terminal, which sent it to shell, its child, which created a new child (with process id 4), which on startup asked the timer vane to set a timer.

64+

65+The timer vane saves this duct, so that when the specified time arrives and Unix sends a wakeup event to the timer vane, it can produce the response on the same duct. This response is routed to the place we popped off the top of the duct, i.e. the time app. This app produces the text "ding", which falls down to the shell, which drops it through to the terminal. Terminal drops this down to dill, which converts it into an effect that Unix will recognize as a request to print "ding" to the screen. When dill produces this, the last path in the duct has an

66+initial element of the empty span, so this is routed to Unix, which applies the effects.

67+

68+This is a call stack, with a crucial feature: the stack is a first-class citizen. You can respond over a duct zero, one, or many times. You can save ducts for later use. There are definitely parallels to Scheme-style continuations, but simpler and with more structure.

69+

70+### Making Moves

71+

72+If ducts are a call stack, then how do we make calls and produce results? Arvo processes "moves" which are a combination of message data and metadata. There are two types of moves. A `%pass` move is analogous to a call:

73+

74+```

75+[duct %pass return-path=path vane-name=@tD data=card]

76+```

77+

78+Arvo pushes the return path (preceded by the first letter of the vane name) onto the duct and sends the given data, a card, to the vane we specified. Any response will come along the same duct with the path `return-path`.

79+

80+A `%give` move is analogous to a return:

81+

82+```

83+[duct %give data=card]

84+```

85+

86+Arvo pops the top path off the duct and sends the given card back to the caller.

87+

88+### Vanes

89+

90+As shown above, we use Arvo proper to route and control the flow of moves. However, Arvo proper is rarely directly responsible for processing the event data that directly causes the desired outcome of a move. This event data is contained within a card, which is simply a `(pair term noun)`. Instead, Arvo proper passes the card off to one of its vanes, which each present an interface to clients for a particular well-defined, stable, and general-purpose piece of functionality.

91+

92+As of this writing, we have seven vanes, which each provide the following services:

93+

94+- `%ames`: the name of both our network and the vane that communicates over it.

95+- `%behn`: a simple timer.

96+- `%clay`: our version-controlled, referentially- transparent, and global filesystem.

97+- `%dill`: a terminal driver. Unix sends keyboard events to `%dill` from either the console or telnet, and `%dill` produces terminal output.

98+- `%eyre`: an http server. Unix sends http messages to `%eyre`, and `%eyre` produces http messages in response.

99+- `%ford`: handles resources and publishing.

100+- `%gall`: manages our userspace applications. `%gall` keeps state and manages subscribers.

101+

102+### Cards

103+

104+Cards are the vane-specific portion of a move. Each vane defines a protocol for interacting with other vanes (via Arvo) by defining four types of cards: kisses, gifts, notes, and signs.

105+

106+When one vane is `%pass`ed a card in its `++kiss`, Arvo activates the `++call` gate with the card as its argument. To produce a result, the vane `%give`s one of the cards defined in its `++gift`. If the vane needs to request something of another vane, it `%pass`es it a `++note` card. When that other vane returns a result, Arvo activates the `++take` gate of the initial vane with one of the cards defined in its `++sign`.

107+

108+In other words, there are only four ways of seeing a move: (1) as a request seen by the caller, which is a ++note. (2) that same request as seen by the callee, a `++kiss`. (3) the response to that first request as seen by the callee, a `++gift`. (4) the response to the first request as seen by the caller, a `++sign`.

109+

110+When a `++kiss` card is passed to a vane, Arvo calls its `++call` gate, passing it both the card and its duct. This gate must be defined in every vane. It produces two things in the following order: a list of moves and a possibly modified copy of its context. The moves are used to interact with other vanes, while the new context allows the vane to save its state. The next time Arvo activates the vane it will have this context as its subject.

111+

112+This overview has detailed how to pass a card to a particular vane. To see the cards each vane can be `%pass`ed as a `++kiss` or return as a `++gift` (as well as the semantics tied to them), each vane's public interface is explained in detail in its respective overview.

learn/arvo/ames.udon → learn/arvo/ames.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'1'

5− title/'Ames'

6− ==

7−;>

8−

9−# Ames

10−

1++++

2+title = "Ames"

3+weight = 1

4+template = "doc.html"

5++++

116Our networking protocol.

127

138`%ames` is the name of both our network and the vane that communicates

learn/arvo/behn.udon → learn/arvo/behn.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'2'

5− title/'Behn'

6− ==

7−;>

8−

9−# Behn

10−

1++++

2+title = "Behn"

3+weight = 2

4+template = "doc.html"

5++++

116Our simple timer.

127

138It allows vanes and applications to set and timer events, which are

learn/arvo/clay.udon → learn/arvo/clay.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'3'

5− title/'Clay'

6− ==

7−;>

8−

9−# Clay

10−

1++++

2+title = "Clay"

3+weight = 3

4+template = "doc.html"

5++++

116Our filesystem.

127

138`%clay` is version-controlled, referentially-transparent, and global.

learn/arvo/dill.udon → learn/arvo/dill.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'4'

5− title/'Dill'

6− ==

7−;>

8−

9−# Dill

10−

1++++

2+title = "Dill"

3+weight = 4

4+template = "doc.html"

5++++

116Our terminal driver.

127

138Unix sends keyboard events to `%dill` from either the console or telnet,

learn/arvo/eyre.udon → learn/arvo/eyre.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'5'

5− title/'Eyre'

6− ==

7−;>

8−

9−# Eyre

10−

1++++

2+title = "Eyre"

3+weight = 5

4+template = "doc.html"

5++++

116Our HTTP server.

127

138Unix sends http messages to `%eyre`, and `%eyre` produces http messages

learn/arvo/ford.udon → learn/arvo/ford.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'6'

5− title/'Ford'

6− ==

7−;>

8−

9−# Ford

10−

1++++

2+title = "Ford"

3+weight = 6

4+template = "doc.html"

5++++

116Our typed and marked computation engine.

127

138A variety of different services are provided by `%ford`, but they mostly

learn/arvo/gall.udon → learn/arvo/gall.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'6'

4− title/'Gall Apps'

5− ==

6−;>

7−

8−# Gall Apps

9−

1++++

2+title = "Gall Apps"

3+weight = 6

4+template = "doc.html"

5++++

106This is documentation about how to write Gall apps. Some knowledge of Hoon is assumed.

117

128> Note: the last major revision of these lessons was in 2016. They need to be

learn/arvo/hall.udon → learn/arvo/hall.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'7'

5− title/'Hall'

6− ==

7−;>

8−

9−# Hall

10−

1++++

2+title = "Hall"

3+weight = 7

4+template = "doc.html"

5++++

116> Last major revision of this tutorial: 2017. Some of the information and Hoon syntax here may

127 be outdated.

138

learn/azimuth.udon → learn/azimuth.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Azimuth'

2− sort/'2'

3− ==

4−;>

5−

6−# Azimuth

7−

1++++

2+title = "Azimuth"

3+weight = 2

4+template = "doc.html"

5++++

86Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a decentralized ledger for Urbit identities that we call *points*. Having a point is necessary to use the Urbit network, which makes it important to have a neutral ledger to determine who owns what.

97

108Azimuth is not, however, part of the Arvo stack. Azimuth is a parallel system that be used as a generalized identity system for other projects. Azimuth "touches" the Urbit ecosystem when a point is used to boot a virtual computer on the Urbit network for the first time. When that happens, the point considered *linked* to Azimuth and the point’s full powers are available for use. Once a point is linked, it cannot be unlinked.

learn/hoon.udon → learn/hoon/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'2'

4− title/'Hoon'

5− ==

6−;>

7−

8−# Hoon

9−

1++++

2+title = "Hoon"

3+weight = 2

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics.

118

129Hoon is an unusual language in several respects, both in syntax and semantics. It uses runes (i.e., ASCII digraphs) in place of keywords, and the spacing rules are a bit strict. A great deal can be expressed in few lines, though excessively compressed code tends to be hard to read. Hoon has surprisingly simple semantics, but mastering it requires learning concepts that don't have close analogues in other languages.

learn/hoon/hoon-tutorial.udon → learn/hoon/hoon-tutorial/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'1'

4− title/'Hoon Tutorial'

5− ==

6−;>

7−

8−# Hoon Tutorial

9−

1++++

2+title = "Hoon Tutorial"

3+weight = 1

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107This series is designed to teach you Hoon without assuming you have an extensive programming background. In fact, you should be able to follow much of it even if you have no programming experience at all, though of course experience helps. We strongly encourage you to try out all the examples of each lesson. These lessons are meant for the beginner but they aren't meant to be skimmed.

118

129Chapter 1 introduces and explains the fundamental concepts you need in order to understand Hoon's semantics.

learn/hoon/hoon-tutorial/arms-and-cores.udon → learn/hoon/hoon-tutorial/arms-and-cores.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'14'

5− title/'Arms and Cores'

6− ==

7−;>

8−

9−# 1.4 Arms and Cores

10−

1++++

2+title = "Arms and Cores"

3+weight = 14

4+template = "doc.html"

5++++

116The Hoon subject is a noun. Each fragment of this noun is either an arm or a leg. In the previous lesson you learned what a leg is, and how to return legs of the subject by various means. In this lesson you'll learn what an arm is. Arms are a bit more complex than legs -- a full understanding of them requires a bit more background knowledge. Accordingly, in this lesson we must also introduce an important Hoon data structure: a 'core'.

127

138After arms are defined and explained we review wing expressions, this time focusing on wing resolution to arms.

learn/hoon/hoon-tutorial/atoms-auras-and-simple-cell-types.udon → learn/hoon/hoon-tutorial/atoms-auras-and-simple-cell-types.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'24'

5− title/'Atoms, Auras, and Simple Cell Types'

6− ==

7−;>

8−

9−# 2.4: Atoms, Auras, and Simple Cell Types

10−

1++++

2+title = "Atoms, Auras, and Simple Cell Types"

3+weight = 24

4+template = "doc.html"

5++++

116Like most modern high-level programming languages, Hoon has a type system. Because Hoon is a functional programming language, its type system differs somewhat from those of non-functional languages. In the next few lessons we'll go over Hoon's type system and point out some of its distinctive features. Certain advanced topics (e.g. type [polymorphism](https://en.wikipedia.org/wiki/Polymorphism_(computer_science%29)) won't be addressed until a later chapter.

127

138A type is ordinarily understood to be a set of values. Examples: the set of all atoms is a type, the set of all cells is a type, and so on.

learn/hoon/hoon-tutorial/cores-again.udon → learn/hoon/hoon-tutorial/cores-again.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'28'

5− title/'Cores Again'

6− ==

7−;>

8−

9−# 2.8 Cores Again

10−

1++++

2+title = "Cores Again"

3+weight = 28

4+template = "doc.html"

5++++

116In the last lesson you learned a bit about how to use cores as state machines. In this lesson you'll expand on that knowledge, in particular by learning how to use the `=^` rune. At the end of the lesson you'll learn how to write a generator that shuffles a 52 card deck and deals hands from it.

127

138## The `num` Core Again

learn/hoon/hoon-tutorial/cores.udon → learn/hoon/hoon-tutorial/cores.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'27'

5− title/'Cores'

6− ==

7−;>

8−

9−# 2.7 Cores

10−

1++++

2+title = "Cores"

3+weight = 27

4+template = "doc.html"

5++++

116You learned what a core is in previous lessons. After a brief review, let's talk about how to use cores effectively in Hoon programming.

127

138A core is a particularly useful kind of Hoon data: a cell whose head is a battery and whose tail is a payload:

learn/hoon/hoon-tutorial/examples.udon → learn/hoon/hoon-tutorial/examples.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'33'

5− title/'Examples'

6− ==

7−;>

8−

9−# Examples

10−

1++++

2+title = "Examples"

3+weight = 33

4+template = "doc.html"

5++++

116Let's look at two more examples of Hoon code: the Sieve of Eratosthenes (a naive prime sieve) and a tic-tac-toe engine.

127

138## Sieve of Eratosthenes

learn/hoon/hoon-tutorial/gates.udon → learn/hoon/hoon-tutorial/gates.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'15'

5− title/'Gates (Hoon Functions)'

6− ==

7−;>

8−

9−# 1.5 Gates (Hoon Functions)

10−

1++++

2+title = "Gates (Hoon Functions)"

3+weight = 15

4+template = "doc.html"

5++++

116In this lesson you're going to learn about Hoon functions.

127

138## What is a Function?

learn/hoon/hoon-tutorial/hoon-programs.udon → learn/hoon/hoon-tutorial/hoon-programs.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'21'

5− title/'Hoon Programs'

6− ==

7−;>

8−

9−# 2.1 Writing Hoon Programs

10−

1++++

2+title = "Hoon Programs"

3+weight = 21

4+template = "doc.html"

5++++

116So far you've only entered short snippets of Hoon code into the dojo. Let's look at some substantive programs.

127

138There many kinds of Hoon programs: generators, Gall apps, Sail documents, and more. In this chapter we'll work exclusively with a subset of the first kind: generators. This narrow focus will allow us to set aside complications that aren't necessary for learning the basics of Hoon. We won't even talk about the full range of generators supported in Urbit just yet. Other kinds of programs will be covered in other lessons.

learn/hoon/hoon-tutorial/hoon-syntax.udon → learn/hoon/hoon-tutorial/hoon-syntax.mdrenamed+6−11

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'22'

5− title/'Hoon Syntax'

6− ==

7−;>

8−

9−# 2.2 Hoon Syntax

10−

1++++

2+title = "Hoon Syntax"

3+weight = 22

4+template = "doc.html"

5++++

116The study of Hoon can be divided into two parts: syntax and semantics.

127

138The [syntax](https://en.wikipedia.org/wiki/Syntax_(programming_languages%29) of a programming language is the set of rules that determine what counts as admissible code in that language. It determines which characters may be used in the source, and also how these characters may be assembled to constitute a program. Attempting to run a program that doesn't follow these rules will result in a syntax error.

@@ -18,7 +13,7 @@ In this lesson we cover Hoon's syntax. A strict account of Hoon's syntax would

1813

1914## Hoon Characters

2015

21−Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters). Hoon does not accept any other characters in source files except for [UTF-8](https://en.wikipedia.org/wiki/UTF-8) in quoted strings. Hard tab characters are illegal; use two spaces instead.

16+Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters). Hoon does not accept any other characters in source files except for [UTF-8](https://en.wikipedia.org/wiki/UTF-8) in quoted strings. Hard tab characters are illegal.

2217

2318```

2419> "You can put ½ in quotes, but not elsewhere!"

learn/hoon/hoon-tutorial/lists.udon → learn/hoon/hoon-tutorial/lists.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'29'

5− title/'Standard Library: Lists'

6− ==

7−;>

8−

9−# 2.9 Standard Library: Lists

10−

1++++

2+title = "Standard Library: Lists"

3+weight = 29

4+template = "doc.html"

5++++

116In this lesson we'll review what a list is and then cover many of the list-related functions in the Hoon standard library.

127

138## List Review

learn/hoon/hoon-tutorial/multi-gate-cores-and-doors.udon → learn/hoon/hoon-tutorial/multi-gate-cores-and-doors.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'16'

5− title/'Multi-gate Cores and Doors'

6− ==

7−;>

8−

9−# 1.6 Multi-gate Cores and Doors

10−

1++++

2+title = "Multi-gate Cores and Doors"

3+weight = 16

4+template = "doc.html"

5++++

116It's useful to have cores whose arms evaluate to make gates. The use of such cores is common in Hoon; that's how the functions of the Hoon standard library are stored in the subject. Learning about such cores will also deepen the reader's understanding of Hoon semantics, and for that reason alone is worthwhile.

127

138In this lesson you'll also learn about a new kind of core, called a 'door'.

learn/hoon/hoon-tutorial/nouns.udon → learn/hoon/hoon-tutorial/nouns.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'12'

5− title/'Nouns'

6− ==

7−;>

8−

9−# 1.2 Nouns

10−

1++++

2+title = "Nouns"

3+weight = 12

4+template = "doc.html"

5++++

116In Urbit every piece of data is a noun. In order to understand Hoon one must first understand nouns.

127

138## Noun Definition

learn/hoon/hoon-tutorial/setup.udon → learn/hoon/hoon-tutorial/setup.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'11'

5− title/'Setup'

6− ==

7−;>

8−

9−# 1.1 Setup

10−

1++++

2+title = "Setup"

3+weight = 11

4+template = "doc.html"

5++++

116Before we begin working on Hoon you should first (1) have Urbit installed and (2) boot an 'urbit' that you can use for trying out Hoon examples. Interactive learning is far superior to passive reading.

127

138## Installing Urbit

learn/hoon/hoon-tutorial/simple-one-gate-programs.udon → learn/hoon/hoon-tutorial/simple-one-gate-programs.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'23'

5− title/'Simple One-Gate Programs'

6− ==

7−;>

8−

9−# 2.3 Simple One-Gate Programs

10−

1++++

2+title = "Simple One-Gate Programs"

3+weight = 23

4+template = "doc.html"

5++++

116In this lesson we'll try to cover enough basic Hoon so that you can write (and understand) your own simple programs. Each of the programs given in this lesson produces a gate. (Gates are one-armed cores of Hoon that can be used as functions -- this is covered in [lesson 1.5](../gates).)

127

138For each program we encourage you to: (1) write out the program yourself, (2) save it to the `/home/gen` directory of your urbit's pier, and (3) run it from the dojo. The best way to learn to program in Hoon is by getting your hands dirty.

learn/hoon/hoon-tutorial/structures-and-complex-types.udon → learn/hoon/hoon-tutorial/structures-and-complex-types.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'26'

5− title/'Structures and Complex Types'

6− ==

7−;>

8−

9−# 2.6 Structures and Complex Types

10−

1++++

2+title = "Structures and Complex Types"

3+weight = 26

4+template = "doc.html"

5++++

116In this lesson we'll talk a little about how type expressions become structures, and how these structures manifest in different ways in different parts of your Hoon code. We'll also talk about how to create your own custom-defined complex types from simpler ones.

127

138## Structures

learn/hoon/hoon-tutorial/the-subject-and-its-legs.udon → learn/hoon/hoon-tutorial/the-subject-and-its-legs.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'13'

5− title/'The Subject and Its Legs'

6− ==

7−;>

8−

9−# 1.3 The Subject and Its Legs

10−

1++++

2+title = "The Subject and Its Legs"

3+weight = 13

4+template = "doc.html"

5++++

116Hoon isn't an object-oriented programming language; it's a "subject-oriented" programming language. But what's this "subject"?

127

138## A Start

learn/hoon/hoon-tutorial/trees-sets-and-maps.udon → learn/hoon/hoon-tutorial/trees-sets-and-maps.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'30'

5− title/'Standard Library: Trees, Sets, and Maps'

6− ==

7−;>

8−

9−# 2.10 Hoon Standard Library: Trees, Sets, and Maps

10−

1++++

2+title = "Standard Library: Trees, Sets, and Maps"

3+weight = 30

4+template = "doc.html"

5++++

116Along with lists, the Hoon standard library also supports trees, sets, and maps as data structures. A Hoon `tree` is the data structure for a binary tree. A Hoon `set` is the data structure for a set of values. A Hoon `map` is the data structure for a set of `[key value]` pairs.

127

138In this lesson we'll cover each.

learn/hoon/hoon-tutorial/type-checking-and-type-inference.udon → learn/hoon/hoon-tutorial/type-checking-and-type-inference.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'25'

5− title/'Type Checking and Type Inference'

6− ==

7−;>

8−

9−# 2.5 Type Checking and Type Inference

10−

1++++

2+title = "Type Checking and Type Inference"

3+weight = 25

4+template = "doc.html"

5++++

116As the Hoon compiler compiles your Hoon code, it does a *type check* on certain expressions to make sure they are guaranteed to produce a value of the correct type. If it cannot be proved that the output value is correctly typed, the compile will fail with a `nest-fail` crash. In order to figure out what type of value is produced by a given expression, the compiler uses *type inference* on that code. In this lesson we'll cover various cases in which a type check is performed, and also how the compiler does type inference on an expression.

127

138## Type Checking

learn/hoon/hoon-tutorial/type-polymorphism.udon → learn/hoon/hoon-tutorial/type-polymorphism.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'31'

4− title/'Type Polymorphism'

5− ==

6−;>

7−

8−# 3.1 Polymorphism

9−

1++++

2+title = "Type Polymorphism"

3+weight = 31

4+template = "doc.html"

5++++

106There are many cases in which one may want to write a function that accepts as input various different types of data. Such a function is said to be [polymorphic](https://en.wikipedia.org/wiki/Polymorphism_(computer_science%29). ("Polymorphism" = "many forms"; so polymorphic functions accept many forms of data as input.)

117

128One relatively trivial form of polymorphism involves sub-typing. A gate whose sample is a raw `noun` can accept any Hoon data structure as input -- it's just that the sample will only be treated as a raw noun. For example, consider the `copy` gate below:

learn/hoon/style.udon → learn/hoon/style.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'3'

4− title/'Hoon Style Guide'

5− ==

6−;>

7−

8−# Hoon Style Guide

9−

1++++

2+title = "Hoon Style Guide"

3+weight = 3

4+template = "doc.html"

5++++

106Welcome to the Hoon style guide. It's important to familiarize yourself with our way of writing Hoon code.

117

128## Layout

learn/hoon/workbook.udon → learn/hoon/workbook/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'2'

4− title/'Hoon Workbook'

5− ==

6−;>

7−

8−# Hoon Workbook

9−

1++++

2+title = "Hoon Workbook"

3+weight = 2

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107The Workbook is the place to sharpen your Hoon skills. Each entry in the

118Workbook is a code walkthrough followed by exercises.

129

learn/hoon/workbook/bomb.udon → learn/hoon/workbook/bomb.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'7'

4− title/'Bomb Defusing'

5− ==

6−;>

7−

8−# Bomb Defusing

9−

1++++

2+title = "Bomb Defusing"

3+weight = 7

4+template = "doc.html"

5++++

106In this exercise, we will build a generator that takes a list of wires to be cut

117in order to defuse a bomb. The bomb is defused according to the following rules.

128

learn/hoon/workbook/caesar.udon → learn/hoon/workbook/caesar.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'2'

4− title/'Caesar Cipher'

5− ==

6−;>

7−

8−# Caesar Cipher

9−

1++++

2+title = "Caesar Cipher"

3+weight = 2

4+template = "doc.html"

5++++

106A Caesar cipher is a very simple way to obfuscate a message. The technique

117takes a string and swaps out each component letter with another letter that is

128a specified number of positions up or down in the alphabet. For example, with a

learn/hoon/workbook/digits.udon → learn/hoon/workbook/digits.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'4'

4− title/'Digits'

5− ==

6−;>

7−

8−# Digits

9−

1++++

2+title = "Digits"

3+weight = 4

4+template = "doc.html"

5++++

106Let's write a generator that takes a `@ud` (unsigned decimal) and returns a list

117of its digits.

128

learn/hoon/workbook/eightball.udon → learn/hoon/workbook/eightball.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'5'

4− title/'Magic 8-Ball'

5− ==

6−;>

7−

8−# Magic 8-Ball

9−

1++++

2+title = "Magic 8-Ball"

3+weight = 5

4+template = "doc.html"

5++++

106In this lesson we'll write a generator that mimics the functionality of a

117Magic 8-Ball, producing a randomized response with each run.

128

learn/hoon/workbook/list.udon → learn/hoon/workbook/list.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'1'

4− title/'List of Numbers'

5− ==

6−;>

7−

8−# List of Numbers

9−

1++++

2+title = "List of Numbers"

3+weight = 1

4+template = "doc.html"

5++++

106This code-example is intended to familiarize you with the basics of Hoon syntax. It's okay if you don't understand everything immediately; some concepts may beyond your grasp for now. What's important is that you become accustomed to the elements of the code and their look once combined into a valid program.

117

128Below is a simple Hoon program that takes a single number `n` from the user as input and produces a list of numbers from `1` up to (but not including) `n`. So, if the user gives the number `5`, the program will produce: `~[1 2 3 4]`.

learn/hoon/workbook/recursion.udon → learn/hoon/workbook/recursion.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'3'

4− title/'Recursion'

5− ==

6−;>

7−

8−# Recursion

9−

1++++

2+title = "Recursion"

3+weight = 3

4+template = "doc.html"

5++++

106Recursion is a common pattern for solving certain problems in most programming

117languages, and Hoon is no exception. One of the classically recursive problems

128is that of factorial. The factorial of _n_ is the product of all positive

learn/hoon/workbook/traffic-light.udon → learn/hoon/workbook/traffic-light.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'6'

4− title/'Traffic Light'

5− ==

6−;>

7−

8−# Traffic Light

9−

1++++

2+title = "Traffic Light"

3+weight = 6

4+template = "doc.html"

5++++

106Let's create a state machine in Hoon that models the functionality of a traffic

117light. Save the code below as `traffic.hoon` in your `/gen` directory.

128

learn/nock.udon → learn/nock/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'3'

4− title/'Nock'

5− ==

6−;>

7−

8−# Nock

9−

1++++

2+title = "Nock"

3+weight = 3

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107> Last major revision of this tutorial: 2016. Minor revisions were made in October 2018 to bring it in line with the new Nock 4K spec.

118

129Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.

learn/nock/definition.udon → learn/nock/definition.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'1'

5− title/'Nock Definition'

6− ==

7−;>

8−

9−# Nock Definition

10−

1++++

2+title = "Nock Definition"

3+weight = 1

4+template = "doc.html"

5++++

116Nock is a Turing-complete function that maps a cell

127`[subject formula]` to a noun `product`, where `subject` is the

138data, `formula` is the code, and `product` is the result.

learn/nock/example.udon → learn/nock/example.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'3'

5− title/'Example'

6− ==

7−;>

8−

9−# Nock by hand

10−

1++++

2+title = "Example"

3+weight = 3

4+template = "doc.html"

5++++

116Some people write assembly language by hand. Some of them have a

127good reason to do so. But there's no good reason to write Nock by

138hand, ever.

learn/nock/explanation.udon → learn/nock/explanation.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'2'

5− title/'Explanation'

6− ==

7−;>

8−

9−# An explanation of Nock

10−

1++++

2+title = "Explanation"

3+weight = 2

4+template = "doc.html"

5++++

116To make Nock make sense, let's work through the spec line by line.

127First the data model:

138

learn/nock/implementations.udon → learn/nock/implementations.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'4'

4− title/'Implementations'

5− ==

6−;>

7−

8−# Nock Implementations

9−

1++++

2+title = "Implementations"

3+weight = 4

4+template = "doc.html"

5++++

106We use a C implementation for our Nock interpreter. But building a Nock interpreter in another language is a fun exercise. Check out our community Nock implementations, shown below our official C implementation. (Note: the community implementations were written for a slightly older version of Nock, Nock 5K. The current version is Nock 4K.):

117

128## Table of Contents

learn/vere.udon → learn/vere/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'4'

4− title/'Vere'

5− ==

6−;>

7−

8−# Vere

9−

1++++

2+title = "Vere"

3+weight = 4

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107The Nock runtime system, written in C.

118

129Keep reading if you're planning to work on the Urbit interpreter, you're a

learn/vere/api.udon → learn/vere/api.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'4'

3− next/'true'

4− title/'API overview by prefix'

5− ==

6−;>

7−

8−## u3: API overview by prefix

9−

1++++

2+title = "API overview by prefix"

3+weight = 4

4+template = "doc.html"

5++++

106Let's run through the `u3` modules one by one. All public

117functions are commented, but the comments may be cryptic.

128

learn/vere/c.udon → learn/vere/c.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'2'

3− next/'true'

4− title/'C in Urbit'

5− ==

6−;>

7−

8−## c3: C in Urbit

9−

1++++

2+title = "C in Urbit"

3+weight = 4

4+template = "doc.html"

5++++

106Under `u3` is the simple `c3` layer, which is just how we write C

117in Urbit.

128

learn/vere/jetting.udon → learn/vere/jetting.mdrenamed+5−8

@@ -1,11 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'5'

3− title/'Writing Jets'

4− ==

5−;>

6−

7−# How to write a jet

8−

1++++

2+title = "Writing Jets"

3+weight = 5

4+template = "doc.html"

5++++

96A guide for new Urbit developers.

107

118Problem statement: coder A has written some Hoon and you, coder B, need to jet it.

learn/vere/nouns.udon → learn/vere/nouns.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'3'

3− next/'true'

4− title/'Land of Nouns'

5− ==

6−;>

7−

8−## u3: Land of nouns

9−

1++++

2+title = "Land of Nouns"

3+weight = 3

4+template = "doc.html"

5++++

106The division between `c3` and `u3` is that you could theoretically

117imagine using `c3` as just a generic C environment. Anything to do

128with nouns is in `u3`.

learn/vere/runtime.udon → learn/vere/runtime.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'1'

3− next/'true'

4− title/'C Runtime System'

5− ==

6−;>

7−

8−# C runtime system

9−

1++++

2+title = "C Runtime System"

3+weight = 1

4+template = "doc.html"

5++++

106The Urbit interpreter is built on a Nock runtime system written

117in C, `u3`. This section is a relatively complete description.

128

reference.udon → reference/_index.mdrenamed+6−8

@@ -1,11 +1,9 @@

1−:- :~ navhome/'/docs/'

2− sort/'5'

3− title/'Reference'

4− ==

5−;>

6−

7−# Reference

8−

1++++

2+title = "Reference"

3+weight = 5

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

97Various reference documents are stored here, particularly for Hoon, but also for other parts of the system.

108

119## [The Glossary](glossary)

reference/cheat-sheet.udon → reference/cheat-sheet.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Cheat sheet'

2− sort/'4'

3− ==

4−;>

5−

6−# Hoon cheat sheet

7−

1++++

2+title = "Cheat sheet"

3+weight = 4

4+template = "doc.html"

5++++

86##### `~rovnys-ricfer`

97

108_Original Fora post_ [here](https://urbit.org/fora/posts/~2017.9.18..22.31.06..24d5~).

reference/glossary.udon → reference/glossary.mdrenamed+5−8

@@ -1,11 +1,8 @@

1−:- :~ title/'Glossary'

2− sort/'3'

3− ==

4−

5−;>

6−

7−# Glossary

8−

1++++

2+title = "Glossary"

3+weight = 3

4+template = "doc.html"

5++++

96Urbit is renowned for its exotic terminology. Here's a simple overview

107from the strange words within.

118

reference/hoon-expressions.udon → reference/hoon-expressions/_index.mdrenamed+6−8

@@ -1,11 +1,9 @@

1−:- :~ title/'Hoon Expressions'

2− sort/'1'

3− ==

4−

5−;>

6−

7−# Hoon Expressions

8−

1++++

2+title = "Hoon Expressions"

3+weight = 1

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

97Documentation for Hoon expressions.

108

119## [Runes](runes)

reference/hoon-expressions/advanced.udon → reference/hoon-expressions/advanced.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'5'

4− title/'Advanced Types'

5− ==

6−;>

7−

8−# Advanced types

9−

1++++

2+title = "Advanced Types"

3+weight = 5

4+template = "doc.html"

5++++

106The definition of `type` in the 'Basic Types' section is only a simplified version. The Hoon type system is simple, but not *that* simple.

117

128The good news is that you can *skip this section*, at least when

reference/hoon-expressions/basic.udon → reference/hoon-expressions/basic.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'4'

4− title/'Basic Types'

5− ==

6−;>

7−

8−# Basic types

9−

1++++

2+title = "Basic Types"

3+weight = 4

4+template = "doc.html"

5++++

106A type is usually understood to be a set of values. Hoon values are all nouns,

117so a Hoon type is a set of nouns.

128

reference/hoon-expressions/irregular.udon → reference/hoon-expressions/irregular.mdrenamed+5−8

@@ -1,11 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'7'

3− title/'Irregular forms'

4− ==

5−;>

6−

7−## Irregular forms, a compilation

8−

1++++

2+title = "Irregular forms"

3+weight = 7

4+template = "doc.html"

5++++

96##### `~palfun-foslup`

107

118##### Reading guide

reference/hoon-expressions/limb.udon → reference/hoon-expressions/limb/_index.mdrenamed+6−9

@@ -1,12 +1,9 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'3'

4− title/'Limbs and Wings'

5− ==

6−;>

7−

8−# Limbs and wings

9−

1++++

2+title = "Limbs and wings"

3+weight = 3

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

107One feature Hoon lacks: a context that isn't a first-class value. Hoon has no

118concept of scope, environment, etc. An expression has exactly one data source,

129the *subject*, a noun like any other.

reference/hoon-expressions/limb/limb.udon → reference/hoon-expressions/limb/limb.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'1'

4− title/'Limbs'

5− ==

6−;>

7−

8−# Limb Expressions

9−

1++++

2+title = "Limbs"

3+weight = 1

4+template = "doc.html"

5++++

106A limb is an attribute of subject.

117

128### Produces

reference/hoon-expressions/limb/wing.udon → reference/hoon-expressions/limb/wing.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'2'

4− title/'Wings'

5− ==

6−;>

7−

8−# Wing Expressions

9−

1++++

2+title = "Wings"

3+weight = 2

4+template = "doc.html"

5++++

106`[%wing p=(list limb)]`

117

128A wing is a limb search path into the subject.

reference/hoon-expressions/rune.udon → reference/hoon-expressions/rune/_index.mdrenamed+6−8

@@ -1,11 +1,9 @@

1−:- :~ navhome/'/docs/'

2− sort/'2'

3− title/'Runes'

4− ==

5−;>

6−

7−# Runes

8−

1++++

2+title = "Runes"

3+weight = 2

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

97Runes are a way to form expressions in Hoon.

108

119## Non-Rune Expressions

reference/hoon-expressions/rune/bar.udon → reference/hoon-expressions/rune/bar.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'7'

4− title/'Cores | ("bar")'

5− ==

6−;>

7−

8−# Cores `|` "bar"

9−

1++++

2+title = "Cores"

3+weight = 7

4+template = "doc.html"

5++++

106Core expressions produce cores. A core is a cell of `[battery payload]`.

117The `battery` is code, a battery of Nock formulas. The `payload` is the data

128needed to run those formulas correctly.

reference/hoon-expressions/rune/buc.udon → reference/hoon-expressions/rune/buc.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'12'

4− title/'Structures $ ("buc")'

5− ==

6−;>

7−

8−# Structures $ ("buc")

9−

1++++

2+title = "Structures"

3+weight = 12

4+template = "doc.html"

5++++

106The `$` family of runes is used for defining custom types. Strictly speaking,

117these runes are used to produce 'structures'. A structure is a compile-time

128value that at runtime can be converted to either an example value (sometimes

reference/hoon-expressions/rune/cen.udon → reference/hoon-expressions/rune/cen.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'10'

4− title/'Calls % ("cen")'

5− ==

6−;>

7−

8−# Calls `%` ("cen")

9−

1++++

2+title = "Calls"

3+weight = 10

4+template = "doc.html"

5++++

106The `%` family of runes is used for making 'function calls' in Hoon. To be more precise, these runes evaluate the `$` arm in cores, usually after modifying the sample. (The default sample is replaced with the input values given in the call.)

117

128These runes reduce to the `%=` rune

reference/hoon-expressions/rune/col.udon → reference/hoon-expressions/rune/col.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'9'

4− title/'Cells : ("col")'

5− ==

6−;>

7−

8−# Cells `:` ("col")

9−

1++++

2+title = "Cells"

3+weight = 9

4+template = "doc.html"

5++++

106The `:` ("col") expressions are used to produce cells, which are pairs of values. E.g., `:-(p q)` produces the cell `[p q]`. All `:` runes reduce to `:-`.

117

128## Runes

reference/hoon-expressions/rune/constants.udon → reference/hoon-expressions/rune/constants.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'1'

4− title/'Atoms and strings'

5− ==

6−;>

7−

8−# Atoms and strings

9−

1++++

2+title = "Atoms and strings"

3+weight = 1

4+template = "doc.html"

5++++

106The simplest expressions in every language are constants:

117atoms, strings, paths. (Strings and paths aren't all constants per

128se, because they have interpolations.)

reference/hoon-expressions/rune/dot.udon → reference/hoon-expressions/rune/dot.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'3'

4− title/'Nock . ("dot")'

5− ==

6−;>

7−

8−# Nock `.` ("dot")

9−

1++++

2+title = "Nock"

3+weight = 3

4+template = "doc.html"

5++++

106Anything Nock can do, Hoon can do also. These runes are used for carrying out Nock operations in Hoon.

117

128## Runes

reference/hoon-expressions/rune/ket.udon → reference/hoon-expressions/rune/ket.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'11'

4− title/'Casts ^ ("ket")'

5− ==

6−;>

7−

8−# Casts `^` ("ket")

9−

1++++

2+title = "Casts"

3+weight = 11

4+template = "doc.html"

5++++

106[`^-` ("kethep")](#kethep), [`^+` ("ketlus")](#ketlus), and

117[`^=` ("kettis")](#kettis) let us adjust types without violating type

128constraints.

reference/hoon-expressions/rune/lus.udon → reference/hoon-expressions/rune/lus.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'8'

4− title/'Arms + ("lus")'

5− ==

6−;>

7−

8−# Arms `+` "lus"

9−

1++++

2+title = "Arms"

3+weight = 8

4+template = "doc.html"

5++++

106A core is a cell of `[battery payload]`. The battery is made of one or more arms, each of which is a computation on its parent core.

117

128Arm runes are used to define arms in a core, and thus can only be used from within an expression that produces a multi-arm core. That means arm runes cannot be used to mark the beginning of a first-class expression -- there is no such thing in Hoon as an arm without a core.

reference/hoon-expressions/rune/mic.udon → reference/hoon-expressions/rune/mic.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'13'

4− title/'Make ; ("mic")'

5− ==

6−;>

7−

8−# Make `;` ("mic")

9−

1++++

2+title = "Make"

3+weight = 13

4+template = "doc.html"

5++++

106Miscellaneous useful macros.

117

128## Runes

reference/hoon-expressions/rune/sig.udon → reference/hoon-expressions/rune/sig.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'14'

4− title/'Hints ~ ("sig")'

5− ==

6−;>

7−

8−# Hints `~` ("sig")

9−

1++++

2+title = "Hints"

3+weight = 14

4+template = "doc.html"

5++++

106Runes that use Nock `11` to pass non-semantic info to the interpreter.

117

128## Runes

reference/hoon-expressions/rune/terminators.udon → reference/hoon-expressions/rune/terminators.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− sort/'15'

4− title/'Terminators -- and =='

5− ==

6−;>

7−

8−# Terminators

9−

1++++

2+title = "Terminators"

3+weight = 15

4+template = "doc.html"

5++++

106The `--` and `==` are used as terminators: `--` for core expressions, and `==` for terminating a 'running' or 'jogging' series of Hoon expressions.

117

128## Runes

reference/hoon-expressions/rune/tis.udon → reference/hoon-expressions/rune/tis.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'5'

4− title/'Change Subject = ("tis")'

5− ==

6−;>

7−

8−# Change Subject `=` ("tis")

9−

1++++

2+title = "Change Subject"

3+weight = 5

4+template = "doc.html"

5++++

106These runes modify the subject. (Or more precisely, they

117evaluate at least one of their subexpressions with a modified subject.)

128

reference/hoon-expressions/rune/wut.udon → reference/hoon-expressions/rune/wut.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'6'

4− title/'Conditionals ? ("wut")'

5− ==

6−;>

7−

8−# Conditionals ? ("wut")

9−

1++++

2+title = "Conditionals"

3+weight = 6

4+template = "doc.html"

5++++

106Hoon has the usual program control branches. It also has the usual logical

117operators: AND `?&`, OR `?|`, and NOT `?!`. It also has a `?=` rune that tests

128whether a value matches a given type. In the course of type inference, Hoon

reference/hoon-expressions/rune/zap.udon → reference/hoon-expressions/rune/zap.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'4'

4− title/'Wild ! ("zap")'

5− ==

6−;>

7−

8−# Wild `!` ("zap")

9−

1++++

2+title = "Wild"

3+weight = 4

4+template = "doc.html"

5++++

106## Runes

117

128;=

reference/library/1a.udon → reference/library/1a.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'1'

3− title/'1a: Basic Arithmetic'

4− ==

5−

6−;>

7−

8−# 1a: basic arithmetic

9−

1++++

2+title = "1a: Basic Arithmetic"

3+weight = 1

4+template = "doc.html"

5++++

106### `++add`

117

128Add

reference/library/1b.udon → reference/library/1b.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'2'

3− title/'1b: Tree Addressing'

4− ==

5−

6−;>

7−

8−# 1b: tree addressing

9−

1++++

2+title = "1b: Tree Addressing"

3+weight = 2

4+template = "doc.html"

5++++

106Check out the Nock [explanation](/docs/nock/explanation/) for more

117information on the tree-addressing system.

128

reference/library/1c.udon → reference/library/1c.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'3'

3− title/'1c: Molds and Mold-Builders'

4− ==

5−

6−;>

7−

8−# 1c: molds and mold builders

9−

1++++

2+title = "1c: Molds and Mold-Builders"

3+weight = 3

4+template = "doc.html"

5++++

106### `++bloq`

117

128Blocksize

reference/library/2a.udon → reference/library/2a.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'4'

3− title/'2a: Unit Logic'

4− ==

5−

6−;>

7−

8−

9−# 2a: unit logic

10−

1++++

2+title = "2a: Unit Logic"

3+weight = 4

4+template = "doc.html"

5++++

116### `++biff`

127

138Unit as argument

reference/library/2b.udon → reference/library/2b.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'5'

3− title/'2b: List Logic'

4− ==

5−

6−;>

7−

8−# 2b: list logic

9−

1++++

2+title = "2b: List Logic"

3+weight = 5

4+template = "doc.html"

5++++

106### `++fand`

117

128All indices in `list`

reference/library/2c.udon → reference/library/2c.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'6'

3− title/'2c: Bit Arithmetic'

4− ==

5−

6−;>

7−

8−# 2c: bit arithmetic

9−

1++++

2+title = "2c: Bit Arithmetic"

3+weight = 6

4+template = "doc.html"

5++++

106### `++bex`

117

128Binary exponent

reference/library/2d.udon → reference/library/2d.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'7'

3− title/'2d: Bit Logic'

4− ==

5−

6−;>

7−

8−# 2d: bit logic

9−

1++++

2+title = "2d: Bit Logic"

3+weight = 7

4+template = "doc.html"

5++++

106### `++con`

117

128Binary OR

reference/library/2e.udon → reference/library/2e.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'8'

3− title/'2e: Insecure Hashing'

4− ==

5−

6−;>

7−

8−# 2e: insecure hashing

9−

1++++

2+title = "2e: Insecure Hashing"

3+weight = 8

4+template = "doc.html"

5++++

106### `++fnv`

117

128FNV scrambler

reference/library/2f.udon → reference/library/2f.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'9'

3− title/'2f: Noun Ordering'

4− ==

5−

6−;>

7−

8−

9−# 2f: noun ordering

10−

1++++

2+title = "2f: Noun Ordering"

3+weight = 9

4+template = "doc.html"

5++++

116### `++aor`

127

138Alphabetical order

reference/library/2g.udon → reference/library/2g.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'10'

3− title/'2g: Unsigned Powers'

4− ==

5−

6−;>

7−

8−# 2g: unsigned powers

9−

1++++

2+title = "2g: Unsigned Powers"

3+weight = 10

4+template = "doc.html"

5++++

106### `++pow`

117

128Computes `a` raised to the power of `b`, producing an atom.

reference/library/2h.udon → reference/library/2h.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'11'

3− title/'2h: Set Logic'

4− ==

5−

6−;>

7−

8−# 2h: set logic

9−

1++++

2+title = "2h: Set Logic"

3+weight = 11

4+template = "doc.html"

5++++

106### `++in`

117

128Set operations

reference/library/2i.udon → reference/library/2i.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'12'

3− title/'2i: Map Logic'

4− ==

5−

6−;>

7−

8−# 2i: map logic

9−

1++++

2+title = "2i: Map Logic"

3+weight = 12

4+template = "doc.html"

5++++

106### `++by`

117

128Map operations

reference/library/2j.udon → reference/library/2j.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'13'

3− title/'2j: Jar and Jug Logic'

4− ==

5−

6−;>

7−

8−# 2j: jar and jug logic

9−

1++++

2+title = "2j: Jar and Jug Logic"

3+weight = 13

4+template = "doc.html"

5++++

106### `++ja`

117

128Jar engine

reference/library/2k.udon → reference/library/2k.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'14'

3− title/'2k: Queue Logic'

4− ==

5−

6−;>

7−

8−

9−# 2k: queue logic

10−

1++++

2+title = "2k: Queue Logic"

3+weight = 14

4+template = "doc.html"

5++++

116### `++to`

127

138

reference/library/2l.udon → reference/library/2l.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'15'

3− title/'2l: Container from Container'

4− ==

5−

6−;>

7−

8−# 2l: container from container

9−

1++++

2+title = "2l: Container from Container"

3+weight = 15

4+template = "doc.html"

5++++

106### `++malt`

117

128Map from list

reference/library/2m.udon → reference/library/2m.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'16'

3− title/'2m: Container from Noun'

4− ==

5−

6−;>

7−

8−

9−# 2m: container from noun

10−

1++++

2+title = "2m: Container from Noun"

3+weight = 16

4+template = "doc.html"

5++++

116### `++ly`

127

138List from raw noun

reference/library/2n.udon → reference/library/2n.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'17'

3− title/'2n: Functional Hacks'

4− ==

5−

6−;>

7−

1++++

2+title = "2n: Functional Hacks"

3+weight = 17

4+template = "doc.html"

5++++

86# 2n: functional hacks

97

108### `++cork`

reference/library/2o.udon → reference/library/2o.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'18'

3− title/'2o: Normalizing Containers'

4− ==

5−

6−;>

7−

8−# 2o: normalizing containers

9−

1++++

2+title = "2o: Normalizing Containers"

3+weight = 18

4+template = "doc.html"

5++++

106### `++jar`

117

128Mold generator. A `jar` is a `map` of `list`.

reference/library/2p.udon → reference/library/2p.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'19'

3− title/'2p: Serialization'

4− ==

5−

6−;>

7−

8−

9−# 2p: serialization

10−

1++++

2+title = "2p: Serialization"

3+weight = 19

4+template = "doc.html"

5++++

116### `++cue`

127

138Unpack atom to noun

reference/library/2q.udon → reference/library/2q.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'20'

3− title/'2q: Molds and Mold-Builders'

4− ==

5−

6−;>

7−

8−

9−# 2q: molds and mold builders

10−

1++++

2+title = "2q: Molds and Mold-Builders"

3+weight = 20

4+template = "doc.html"

5++++

116### `++char`

127

138Character

reference/library/3a.udon → reference/library/3a.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'21'

3− title/'3a: Modular and Signed Ints'

4− ==

5−

6−;>

7−

1++++

2+title = "3a: Modular and Signed Ints"

3+weight = 21

4+template = "doc.html"

5++++

86# 3a: modular and signed ints

97

108### `++egcd`

reference/library/3b.udon → reference/library/3b.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'22'

3− title/'3b: Floating Point'

4− ==

5−

6−;>

7−

8−# 3b: floating point

9−

1++++

2+title = "3b: Floating Point"

3+weight = 22

4+template = "doc.html"

5++++

106### `++fn`

117

128Float

reference/library/3c.udon → reference/library/3c.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'23'

3− title/'3c: Urbit Time'

4− ==

5−

6−;>

7−

8−# 3c: urbit time

9−

1++++

2+title = "3c: Urbit Time"

3+weight = 23

4+template = "doc.html"

5++++

106### `++yall`

117

128Time since beginning of time

reference/library/3d.udon → reference/library/3d.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'24'

3− title/'3d: SHA Hash Family'

4− ==

5−

6−;>

7−

8−# 3d: SHA hash family

9−

1++++

2+title = "3d: SHA Hash Family"

3+weight = 24

4+template = "doc.html"

5++++

106### `++shad`

117

128Double SHA-256

reference/library/3e.mdnew file+8

@@ -0,0 +1,8 @@

1++++

2+title = "3e: AES encryption (Removed)"

3+weight = 25

4+template = "doc.html"

5++++

6+The standard-library functions in this section have been removed.

7+

8+---

reference/library/3e.udondeleted−12

@@ -1,12 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'25'

3− title/'3e: (Removed)'

4− ==

5−

6−;>

7−

8−# 3e: AES encryption

9−

10−The standard-library functions in this section have been removed.

11−

12−---

reference/library/3f.udon → reference/library/3f.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'26'

3− title/'3f: Scrambling'

4− ==

5−

6−;>

7−

8−# 3f: scrambling

9−

1++++

2+title = "3f: Scrambling"

3+weight = 26

4+template = "doc.html"

5++++

106### `++un`

117

128Reversible scrambling

reference/library/3g.udon → reference/library/3g.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'27'

3− title/'3g: Molds and Mold-Builders'

4− ==

5−

6−;>

7−

8−# 3g: molds and mold builders

9−

1++++

2+title = "3g: Molds and Mold-Builders"

3+weight = 27

4+template = "doc.html"

5++++

106### `++coin`

117

128

reference/library/4a.udon → reference/library/4a.mdrenamed+5−11

@@ -1,14 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'28'

3− title/'4a: Exotic Bases'

4− ==

5−

6−;>

7−

8−

9−

10−# 4a: exotic bases

11−

1++++

2+title = "4a: Exotic Bases"

3+weight = 28

4+template = "doc.html"

5++++

126### `++po`

137

148Phonetic base

reference/library/4b.udon → reference/library/4b.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'29'

3− title/'4b: Text Processing'

4− ==

5−

6−;>

7−

8−# 4b: text processing

9−

1++++

2+title = "4b: Text Processing"

3+weight = 29

4+template = "doc.html"

5++++

106### `++at`

117

128```

reference/library/4c.udon → reference/library/4c.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'30'

3− title/'4c: Tank Printer'

4− ==

5−

6−;>

7−

8−# 4c: tank printer

9−

1++++

2+title = "4c: Tank Printer"

3+weight = 30

4+template = "doc.html"

5++++

106### `++re`

117

128Pretty-printing engine

reference/library/4d.udon → reference/library/4d.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'31'

3− title/'4d: Parsing (Tracing)'

4− ==

5−

6−;>

7−

8−

9−# 4d: parsing (tracing)

10−

1++++

2+title = "4d: Parsing (Tracing)"

3+weight = 31

4+template = "doc.html"

5++++

116### `++last`

127

138Further trace

reference/library/4e.udon → reference/library/4e.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'32'

3− title/'4e: Parsing (Combinators)'

4− ==

5−

6−;>

7−

8−# 4e: parsing (combinators)

9−

1++++

2+title = "4e: Parsing (Combinators)"

3+weight = 32

4+template = "doc.html"

5++++

106### `++bend`

117

128Conditional composer

reference/library/4f.udon → reference/library/4f.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'33'

3− title/'4f: Parsing (Rule-Builders)'

4− ==

5−

6−;>

7−

8−

9−# 4f: parsing (rule builders)

10−

1++++

2+title = "4f: Parsing (Rule-Builders)"

3+weight = 33

4+template = "doc.html"

5++++

116### `++bass`

127

138Parser modifier: LSB

reference/library/4g.udon → reference/library/4g.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'34'

3− title/'4g: Parsing (Outside Caller)'

4− ==

5−

6−;>

7−

8−

9−# 4g: parsing (outside caller)

10−

1++++

2+title = "4g: Parsing (Outside Caller)"

3+weight = 34

4+template = "doc.html"

5++++

116### `++rash`

127

138Parse or crash

reference/library/4h.udon → reference/library/4h.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'35'

3− title/'4h: Parsing (ASCII Glyphs)'

4− ==

5−

6−;>

7−

8−

9−# 4h: parsing (ascii glyphs)

10−

1++++

2+title = "4h: Parsing (ASCII Glyphs)"

3+weight = 35

4+template = "doc.html"

5++++

116### `++ace`

127

138Parse space

reference/library/4i.udon → reference/library/4i.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'36'

3− title/'4i: Parsing (Useful Idioms)'

4− ==

5−

6−;>

7−

8−# 4i: parsing (useful idioms)

9−

1++++

2+title = "4i: Parsing (Useful Idioms)"

3+weight = 36

4+template = "doc.html"

5++++

106### `++alf`

117

128Alphabetic characters

reference/library/4j.udon → reference/library/4j.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'37'

3− title/'4j: Parsing (Bases and Base Digits)'

4− ==

5−

6−;>

7−

8−

9−# 4j: parsing (bases and base digits)

10−

1++++

2+title = "4j: Parsing (Bases and Base Digits)"

3+weight = 37

4+template = "doc.html"

5++++

116### `++ab`

127

138Primitive parser engine

reference/library/4k.udon → reference/library/4k.mdrenamed+5−9

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'38'

3− title/'4k: Atom Printing'

4− ==

5−

6−;>

7−

8−# 4k: atom printing

9−

1++++

2+title = "4k: Atom Printing"

3+weight = 38

4+template = "doc.html"

5++++

106### `++co`

117

128Literal rendering engine

reference/library/4l.udon → reference/library/4l.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'39'

3− title/'4l: Atom Parsing'

4− ==

5−

6−;>

7−

8−

9−# 4l: atom parsing

10−

1++++

2+title = "4l: Atom Parsing"

3+weight = 39

4+template = "doc.html"

5++++

116### `++so`

127

138Coin parser engine

reference/library/4m.udon → reference/library/4m.mdrenamed+6−10

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'40'

3− title/'4m: Formatting Functions'

4− ==

5−

6−;>

7−

8−# 4m: formatting functions

9−

1++++

2+title = "4m: Formatting Functions"

3+weight = 40

4+template = "doc.html"

5++++

106### `++scot`

117

128Render dime as cord

@@ -429,7 +425,7 @@ A `path`, or crash.

429425

430426 > (stab '/a/~pillyt/pals/1')

431427 /a/~pillyt/pals/1

432−

428+

433429 > `(pole ,@ta)`(stab '/a/~pillyt/pals/1')

434430 [~.a [~.~pillyt [~.pals [~.1 ~]]]]

435431```

reference/library/4n.udon → reference/library/4n.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'41'

3− title/'4n: Virtualization'

4− ==

5−

6−;>

7−

8−

9−# 4n: virtualization

10−

1++++

2+title = "4n: Virtualization"

3+weight = 41

4+template = "doc.html"

5++++

116### `++mack`

127

138Nock subject to unit

reference/library/4o.udon → reference/library/4o.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'42'

3− title/'4o: Molds'

4− ==

5−

6−;>

7−

8−

9−# 4o: molds and mold builders

10−

1++++

2+title = "4o: Molds"

3+weight = 42

4+template = "doc.html"

5++++

116### `++abel`

127

138Biblical names in hoon are primarily aliases for the compiler.

reference/library/5a.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5a: Compiler Utilities"

3+weight = 43

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5a.udondeleted−10

@@ -1,10 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'43'

3− title/'5a: Compiler Utilities'

4− ==

5−

6−;>

7−

8−# 5a: compiler utilities

9−

10−(To be documented)

reference/library/5b.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5b: Macro Expansion"

3+weight = 44

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5b.udondeleted−10

@@ -1,10 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'44'

3− title/'5b: Macro Expansion'

4− ==

5−

6−;>

7−

8−# 5b: macro expansion

9−

10−(To be documented)

reference/library/5c.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5c: Compiler Backend & Prettyprinter"

3+weight = 45

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5c.udondeleted−10

@@ -1,10 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'45'

3− title/'5c: Compiler Backend & Prettyprinter'

4− ==

5−

6−;>

7−

8−# 5c: compiler backend and prettyprinter

9−

10−(To be documented)

reference/library/5d.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5d: Parser"

3+weight = 46

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5d.udondeleted−11

@@ -1,11 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'46'

3− title/'5d: Parser'

4− ==

5−

6−;>

7−

8−

9−# 5d: parser

10−

11−(To be documented)

reference/library/5e.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5e: Caching Compiler"

3+weight = 47

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5e.udondeleted−11

@@ -1,11 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'47'

3− title/'5e: Caching Compiler'

4− ==

5−

6−;>

7−

8−

9−# 5e: caching compiler

10−

11−(To be documented)

reference/library/5f.udon → reference/library/5f.mdrenamed+5−10

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'48'

3− title/'5f: Molds and Mold-Builders'

4− ==

5−

6−;>

7−

8−

9−# 5f: molds and mold builders

10−

1++++

2+title = "5f: Molds and Mold-Builders"

3+weight = 48

4+template = "doc.html"

5++++

116### `++mane`

127

138XML name

reference/library/5g.mdnew file+6

@@ -0,0 +1,6 @@

1++++

2+title = "5g: profiling support"

3+weight = 49

4+template = "doc.html"

5++++

6+(To be documented)

reference/library/5g.udondeleted−11

@@ -1,11 +0,0 @@

1−:- :~ navhome/'/docs/'

2− sort/'49'

3− title/'5g: profiling support'

4− ==

5−

6−;>

7−

8−

9−# 5g: profiling support

10−

11−(To be documented)

reference/library.udon → reference/library/_index.mdrenamed+6−7

@@ -1,10 +1,9 @@

1−:- :~ title/'Standard library'

2− sort/'2'

3− ==

4−;>

5−

6−# Standard library

7−

1++++

2+title = "Standard library"

3+weight = 2

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

87#### [_alphabetical_](#alphabetical-) [_by section_](#by-section-)

98

109Documentation for the standard library.

reference/library/zuse.udon → reference/library/zuse.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'50'

3− title/'Zuse'

4− ==

5−

6−;>

7−

1++++

2+title = "Zuse"

3+weight = 50

4+template = "doc.html"

5++++

86_Zuse_ is a defined interface for vanes. It contains the part of the Hoon

97standard library that is specific to Arvo functionality.

108

reference/troubleshooting.udon → reference/troubleshooting.mdrenamed+5−7

@@ -1,10 +1,8 @@

1−:- :~ title/'Hoon Errors'

2− sort/'5'

3− ==

4−;>

5−

6−# Hoon Errors

7−

1++++

2+title = "Hoon Errors"

3+weight = 5

4+template = "doc.html"

5++++

86Ideally your Hoon works perfectly the first time. But...

97

108## Syntax errors

using.udon → using/_index.mdrenamed+6−8

@@ -1,11 +1,9 @@

1−:- :~ navhome/'/docs/'

2− sort/'2'

3− title/'Reference'

4− ==

5−;>

6−

7−# Using

8−

1++++

2+title = "Using"

3+weight = 2

4+sort_by = "weight"

5+template = "sections/docs/chapters.html"

6++++

97This section contains guides to using your urbit.

108

119- [Admin and Operation](admin) is a guide to the basic commands used to interact with your ship.

using/admin.udon → using/admin.mdrenamed+13−13

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'1'

5− title/'Admin and Operations'

6− ==

7−;>

8−

9−# Admin and operation

10−

1++++

2+title = "Admin and Operations"

3+weight = 1

4+template = "doc.html"

5++++

116Your urbit (also called your _ship_) is a persistent Unix process that you

127mainly control from the console. For some things, a browser will also work.

138

@@ -117,14 +112,17 @@ On startup Urbit tries to bind to `localhost:8080`. If you're already

117112running something on `8080` -- such as another urbit -- you'll find the urbit

118113that you just started on `8081`, and so on. For planets only, we also proxy web

119114domains through Urbit's own servers. Any planet `~your-urbit` is also at

120−`your-urbit.arvo.network`.

115+`your-urbit.urbit.org`.

121116

122117Your urbit serves a simple homepage from `http://localhost:8080` or

123−`https://your-urbit.arvo.network` that should be self-explanatory. Since

118+`https://your-urbit.urbit.org` that should be self-explanatory. Since

124119our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.

125120You can find that on `8443`. Or `8444` (and so on) if you're already

126121running something on `8443`.

127122

123+A complete walkthrough of the Urbit web interface is

124+[here](../web/).

125+

128126## Moons

129127

130128Urbit namespace is distributed by having parent nodes sign the keys for child

@@ -170,7 +168,9 @@ moon: ~faswep-navred-sampel-palnet

170168`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`

171169and does not need editing to be used with the `-k` option.

172170

173−The scheme for booting is:

171+You can use the resulting output in the same installation flow from

172+[install](../install) and [setup](../setup), following the same scheme as

173+for booting a planet. That scheme is:

174174

175175```

176176$ urbit -w <moonname> -G <key> -c <piername>

using/filesystem.udon → using/filesystem.mdrenamed+5−11

@@ -1,14 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'4'

5− title/'Introduction to the Filesystem'

6− ==

7−;>

8−

9−# Introduction to the Filesystem

10−

11−

1++++

2+title = "Introduction to the Filesystem"

3+weight = 4

4+template = "doc.html"

5++++

126Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,

137referentially transparent namespace. An easy way to think about it is like typed

148`git` with continuous sync.

using/generators.udon → using/generators.mdrenamed+7−15

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− next/'true'

3− sort/'9'

4− title/'Generators'

5− ==

6−;>

7−

8−# Generators

9−

1++++

2+title = "Generators"

3+weight = 9

4+template = "doc.html"

5++++

106Generators are the most straightforward way to write programs for Urbit. They

117are used for doing computations that do not require persistence: they take an

128input and produce an output, then disappear. Generators might make sense for

@@ -29,7 +25,7 @@ a

2925

3026This generator takes one argument of any noun and produces it without any

3127changes. If we put this into a file named `echo.hoon` in the `/gen` directory,

32−we can run it from the [Dojo](../shell):

28+we can run it from the [Dojo](/docs/learn/arvo/arvo-internals/shell):

3329

3430```

3531> +echo 42

@@ -483,11 +479,7 @@ u.my-json

483479

484480The above generator was written with the

485481[Studio Ghibli API](https://ghibliapi.herokuapp.com/). It uses this API to

486−print the title of a Studio Ghibli film. If you save it as `ghib.hoon` you could run this generator by providing an api endpoint like so.

487−

488−```

489−+ghib "https://ghibliapi.herokuapp.com/films/58611129-2dbc-4a81-a72f-77ddfc1b1b49"

490−```

482+print the title of a Studio Ghibli film.

491483

492484```

493485/- sole

using/layout.udon → using/layout.mdrenamed+9−14

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'5'

5− title/'Source layout'

6− ==

7−;>

8−

9−# Arvo source

10−

1++++

2+title = "Source layout"

3+weight = 5

4+template = "doc.html"

5++++

116When you boot an urbit, we transfer the current version of the Arvo

127operating environment to your urbit over our network. That is, the

138source for the system lives on your urbit. Here we'll take a brief tour

@@ -47,7 +42,7 @@ This is where the Arvo kernel lives. `sys/` contains:

4742

4843##### `sys/hoon.hoon`

4944

50−[Hoon](/docs/learn/hoon) is our programming language. Since Hoon

45+[Hoon](/docs/learn/arvo/hoon) is our programming language. Since Hoon

5146compiles itself, the language is actually specified in this source file.

5247

5348##### `sys/zuse.hoon`

@@ -104,9 +99,9 @@ That's it. That's the whole system.

10499

105100## app/

106101

107−This is where [Gall](/docs/learn/arvo/gall) apps live. Gall apps are stateful

102+This is where [Gall](../gall) apps live. Gall apps are stateful

108103servers, sort of like unix daemons. One familiar one is `app/hall.hoon` which is

109−the source code for [Hall](/docs/learn/arvo/hall), the Urbit messaging transport

104+the source code for [Hall](../hall), the Urbit messaging transport

110105layer. And there's also `app/dojo.hoon` — that's your shell.

111106

112107---

@@ -167,7 +162,7 @@ lib/test/*

167162## web/

168163

169164Here are files publicly accessible to the web, as made possible by

170−[Eyre](/docs/learn/arvo/eyre).

165+[Eyre](../eyre).

171166

172167---

173168

using/messaging.udon → using/messaging.mdrenamed+22−23

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'2'

5− title/'Messaging'

6− ==

7−;>

8−

9−# Messaging (Talk and Hall)

10−

1++++

2+title = "Messaging"

3+weight = 2

4+template = "doc.html"

5++++

116Talk is the built-in frontend for the Urbit messaging and notifications

127protocol, Hall. Today we use Hall to chat and coordinate, but it's really

138a general purpose piece of infrastructure.

@@ -27,7 +22,7 @@ be used for that we haven't even thought of.

2722

2823Here we'll be discussing how to operate the default CLI frontend, Talk,

2924to send and receive messages. For a more in-depth look at Hall's internals,

30−take a look at its [documentation](/docs/learn/arvo/hall).

25+take a look at its [documentation](../hall).

3126

3227## Quickstart

3328

@@ -47,19 +42,23 @@ circles, but we for now we'll be dealing with the _channel_: a publicly

4742accessible chatroom for general use. We'll discuss the other three

4843kinds in the [manual](#manual) section.

4944

50−Let's join the `/urbit-help` channel, which is hosting on the star `~dopzod`.

51−Use `ctrl-x` to switch from Dojo to Talk. Then:

45+Let's join the `/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.

46+Then, :

5247

5348```

54−~your-urbit:talk> ;join ~dopzod/urbit-help

49+~your-urbit:talk> ;join /urbit-help

5550```

5651

5752You'll see something like:

5853

5954```

60−--------------| ;join ~dopzod/urbit-help

61−--------------| :: onn =

62−--------------| has glyph = for ~dopzod/urbit-help

55+--------------| ;join /urbit-help

56+--------------| :: onn /urbit-help

57+--------------| bound '=' {[hos=~binzod nom=%urbit-help]}

58+--------------| new = /urbit-help

59+--------------| /urbit-help: cap: For Urbit-related discussion. Politically

60+ | correct and safe for work. Don't be rude.

61+--------------| /urbit-help: fit: caps:n unic:n

6362~your-urbit:talk=

6463```

6564

@@ -101,7 +100,7 @@ Now you and `~talsur-todres` can exchange messages directly.

101100To set your audience back to `/urbit-help`:

102101

103102```

104−~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help

103+~your-urbit:talk[~talsur-todres] ;/urbit-help

105104```

106105

107106You'll see your prompt change back:

@@ -122,7 +121,7 @@ You can also use the ASCII "glyph" assigned to your `/urbit-help` circle as a sh

122121Use `;leave` to unsubscribe from a channel:

123122

124123```

125−~your-urbit:talk= ;leave ~dopzod/urbit-help

124+~your-urbit:talk= ;leave /urbit-help

126125```

127126

128127The web UI ships as compiled JavaScript on your urbit, but has its own

@@ -379,7 +378,7 @@ messages sent to `~other/circle` to also appear in `%name`.

379378For example:

380379

381380```

382−~sampel-palnet:talk> ;source %coolbox ~dopzod/urbit-help

381+~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help

383382```

384383

385384###### Unsource

@@ -391,7 +390,7 @@ Removes `~other/circle` as a source for circle `%name`.

391390For example:

392391

393392```

394−~sampel-palnet:talk> ;unsource %coolbox ~dopzod/urbit-help

393+~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help

395394```

396395

397396### Circle Membership

@@ -440,7 +439,7 @@ specific circle to list members of just those: `;who ~some/circle`

440439For example:

441440

442441```

443−~sampel-palnet:talk> ;who ~dopzod/urbit-help

442+~sampel-palnet:talk> ;who ~marzod/urbit-help

444443```

445444

446445###### Attend

@@ -459,7 +458,7 @@ you.)

459458For example:

460459

461460```

462−~sampel-palnet:talk> ;attend ~dopzod/urbit-help idle

461+~sampel-palnet:talk> ;attend ~marzod/urbit-help idle

463462```

464463

465464###### Set Display Name

using/sail.udon → using/sail.mdrenamed+9−13

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'7'

3− next/'true'

4− title/'Sail'

5− ==

6−;>

7−

8−# Introduction to Sail

9−

1++++

2+title = "Sail"

3+weight = 7

4+template = "doc.html"

5++++

106Sail is Hoon markup that’s used to render a web page with XML. But what makes

117it special is that you can run arbitrary Hoon code within such a web page

128without using a separate markup language. In this tutorial, we will

@@ -15,10 +11,10 @@ be dealing with Sail as it renders to HTML, a subset of XML.

1511### Getting Started

1612

1713Before starting, make sure that your urbit is

18−[mounted to Unix](/docs/getting-started/creating-a-development-ship/)

14+[mounted to Unix](https://urbit.org/docs/using/setup/)

1915

2016To host that output, your ship also has a web-server, called

21−Eyre, that can be found at

17+[Eyre](https://urbit.org/docs/using/web/), that can be found at

2218`http://localhost:8080/` if it’s your first ship that’s running on the a

2319machine, `http://localhost:8081/` if it’s the second ship on that same machine,

2420and so on. In the startup messages, a ship will tell you which HTTP port it's

@@ -456,7 +452,7 @@ Hoon. They are part of Ford, our build system.

456452

457453`/$` is used to get data from the environment, and `/=` adds that data to

458454subject in the face `gas`. The

459−[Ford user manual](/docs/learn/arvo/ford/) has

455+[Ford user manual](https://urbit.org/docs/arvo/internals/ford/runes/) has

460456details on these and other Ford runes, but understanding these runes isn’t

461457necessary for the purposes of this tutorial.

462458

@@ -680,7 +676,7 @@ valid lists for the `;* ?: show-list` expression to resolve.

680676You should now have foundational knowledge for making web pages with Sail. There

681677is, of course, more to learn. If you’re curious, there’s more advanced

682678resources out there.

683−The [Ford manual](/docs/learn/arvo/ford/)

679+The [Ford manual](https://urbit.org/docs/arvo/internals/ford/runes/)

684680can show you how to access various ship resources for user in your pages. To

685681learn more about how the renderer works, take a look at the

686682`/home/ren/urb.hoon` file inside your urbit.

using/shell.udon → using/shell.mdrenamed+6−11

@@ -1,13 +1,8 @@

1−:- :~ navhome/'/docs/'

2− navuptwo/'true'

3− next/'true'

4− sort/'3'

5− title/'Shell (Dojo)'

6− ==

7−;>

8−

9−# Shell (Dojo)

10−

1++++

2+title = "Shell"

3+weight = 3

4+template = "doc.html"

5++++

116The Dojo is our shell; it processes system commands and returns output. It's a

127good place to quickly experiment with Urbit. On the surface the Dojo is just a

138Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

@@ -36,7 +31,7 @@ Tall-form Hoon may require multiple lines:

3631~your-urbit:dojo< 2

3732```

3833

39−Hoon uses something called [the subject](/docs/learn/hoon/hoon-tutorial/the-subject-and-its-legs).

34+Hoon uses something called [the subject](/docs/learn/arvo/hoon/the-subject-and-its-legs).

4035The Dojo has its own subject, and that's where Hoon's equivalent of variables,

4136called faces, are stored.

4237

using/udon.udon → using/udon.mdrenamed+12−16

@@ -1,12 +1,8 @@

1−:- :~ navhome/'/docs/'

2− sort/'8'

3− next/'true'

4− title/'Udon'

5− ==

6−;>

7−

8−# Udon

9−

1++++

2+title = "Udon"

3+weight = 8

4+template = "doc.html"

5++++

106## Table of Contents

117

128- #### [Udon: A Guide](#guide)

@@ -45,10 +41,10 @@ Udon files using our web interface.

4541### Getting Started

4642

4743Before starting, make sure that your urbit is

48−[mounted to Unix](/docs/getting-started/creating-a-development-ship/)

44+[mounted to Unix](https://urbit.org/docs/using/setup/)

4945

5046To host Udon and other kinds of files, your ship also has a

51−web-server, called Eyre, that can be found

47+web-server, called [Eyre](https://urbit.org/docs/using/web/), that can be found

5248at `http://localhost:8080/` if it’s your first ship that’s running on the

5349machine, `http://localhost:8081/` if it’s the second ship on that same machine,

5450and so on. If you can't find your ship on one of these for some reason, try the

@@ -323,12 +319,12 @@ destination.

323319*Example:*

324320

325321```

326−[I'm an inline-style link](https://www.urbit.org/docs/using/shell)

322+[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)

327323```

328324

329325###### Produces:

330326

331−[I'm an inline-style link](https://www.urbit.org/docs/using/shell)

327+[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)

332328

333329The second type is a reference-style link, which uses a relative path, based on

334330the current page's location. Instead of the full url, we use `..` to fill in

@@ -344,7 +340,7 @@ the all of the URL that the destination has in common with the origin page.

344340

345341[I'm a reference-style link](../shell)

346342

347−If this page is located at `https://www.urbit.org/docs/using/`, then these two

343+If this page is located at `https://www.urbit.org/docs/reference/`, then these two

348344examples should have the same destination.

349345

350346#### Anchor Link

@@ -791,7 +787,7 @@ Note: below we use Urbit's implementation of Markdown, [Udon](#udon).

791787This markup language allows you to use snippets of Hoon code but not HTML.

792788In particular, we use Sail, a subset of Hoon. This Sail is rendered as HTML

793789when the file is served to a client. To learn about Sail, head over to

794−the [Sail](/docs/using/sail) section of the docs.

790+the [Sail](/docs/learn/arvo/arvo-internals/sail) section of the docs.

795791

796792In `site/web/meet.udon` put:

797793

@@ -805,7 +801,7 @@ In `site/web/meet.udon` put:

805801

806802# Neo-Tokyo Urbit meetup

807803

808−;img@"https://ofheroesandcliches.files.wordpress.com/2014/06/neo-tokyo.png"(width "100%");

804+

809805

810806Hi there! We meet once a week at The Chat to work on Urbit projects

811807together.