462e5c1 · urbit.org · git.iko.soy

getting-started.udon+13

compare with master

unifiedsplit

@@ -349,6 +349,19 @@ urbit -F zod

349If you want to get on the Arvo network with your point, then continue to the

350next section.

351

352+;=

353+ ;h3

354+ ;div(id "swap"): Set Up Swap

355+ ==

356+==

357+

358+If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, skip this section.

359+

360+Urbit wants to map 2GB of memory when it boots up. We won’t necessarily use all this memory, we just want to see it. On a normal modern PC or Mac, or on a large cloud virtual machine, this is not an issue. On some small cloud virtual machines (Amazon or Digital Ocean), the default memory configuration is smaller than this, and you need to manually configure a swapfile.

361+

362+Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04). For Amazon there’s a StackOverflow thread [here](https://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).

363+

364+Don’t spend a lot of time tweaking these settings; the simplest thing is fine.

352

365

353;=

366;=

354 ;h2

367 ;h2

introduction.udon+3−3

@@ -17,12 +17,12 @@ If you're looking for a high-level introduction to the Urbit project and its com

17- [Arvo vs. Azimuth](/docs/introduction/arvo-vs-azimuth), a quick explanation of the two parallel systems that compose Urbit.

18- [Technical Overview](/docs/introduction/technical-overview), a more in-depth description of the entire Urbit stack.

19- [Contributing](/docs/introduction/contributing), a guide to getting involved with the Urbit project.

20−- [Community Tutorials](/docs/introduction/community), a collection of unofficial but useful Urbit learning resources.

20+- [Community Tutorials](/docs/introduction/community-tutorials), a collection of unofficial but useful Urbit learning resources.

21−- [Source Code](/docs/introduction/source), an explanation of Urbit's constituent GitHub repos.

21+- [Source Code](/docs/introduction/source-code-overview), an explanation of Urbit's constituent GitHub repos.

22

23## [Getting Started](/docs/getting-started)

24

25−If you'd like to install Arvo, get an Azimuth point, and/or get on the Urbit network, you'll find guides here. Dive in, and don't be afraid to [ask for help](support@urbit.org)!

25+If you'd like to install Arvo, get an Azimuth point, and/or get on the Urbit network, you'll find guides here. Dive in, and don't be afraid to [ask for help](mailto:support@urbit.org)!

26

27- [The Installation Guide](/docs/getting-started), a step-by-step walkthrough for getting Urbit running.

28- [The Azimuth section](/docs/getting-started/azimuth), which contains information on managing your Azimuth identities.

introduction/community-tutorials.udon+2−4

@@ -5,16 +5,14 @@

5 ==

6;>

7

8−# Community Docs

8+# Community Docs

9

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

11

12If you want to add something to this list, [shoot us an email](mailto:support@urbit.org).

13

14- `~master-morzod`

15− - [Fora post](https://urbit.org/fora/posts/~2016.12.25..06.35.44..a1ec~/)

15+ - [Fora post](https://github.com/joemfb/mardev/tree/master/docs/gen)

16−- `~hidduc-posmeg`

17− - [Fora post](https://urbit.org/fora/posts/~2017.2.12..21.54.40..6fde~/)

18- `~palfun-foslup`

16- `~palfun-foslup`

19 - [Urbit by Doing](https://github.com/Fang-/Urbit-By-Doing)

17 - [Urbit by Doing](https://github.com/Fang-/Urbit-By-Doing)

20- `@knubie`

18- `@knubie`

learn/arvo/arvo-internals/admin.udon+2−2

@@ -143,7 +143,7 @@ To generate a random moon from your planet, run:

143```

144

145You can use the resulting output in the same installation flow from

146−[install](/../install) and [setup](/../setup), following the same scheme as

146+[install](../install) and [setup](../setup), following the same scheme as

147for booting a planet. That scheme is:

148

149```

@@ -162,7 +162,7 @@ $ urbit -w faswep-navred-sampel-palnet -t habref-mebsem-parsym-batlus -c mymoon

162

163Moons are automatically synced to their parent `%kids` desk, and can control

164applications on their parent planet using `|link`. You can read more about

165−those operations in the [filesystem](/../filesystem) and [console](/../shell)

165+those operations in the [filesystem](../filesystem) and [console](../shell)

166walkthroughs, respectively.

167

168

learn/arvo/arvo-internals/ford.udon+2−2

@@ -127,7 +127,7 @@ library in urbit.

127

128To run this example, put this code in your desk at `gen/faslus.hoon` and run

129`+faslus` in your dojo. This example is a generator. For more information on

130−generators, see the [generator docs](https://urbit.org/docs/arvo/generators).

130+generators, see the [generator docs](/docs/arvo/arvo-internals/generators).

131

132```

133/+ time-to-id

@@ -281,7 +281,7 @@ produces the text of the hoon file at "/path/to/hoon-file/hoon".

281passes the contents through unchanged. In general, rendering a file with a

282mark will potentially run the contents through a series of conversion

283operations. For details on marks, see the

284−[marks docs](https://urbit.org/docs/arvo/marks).

284+[Gall docs](../gall).

285

286Here's an example that includes a mark conversion:

287```

learn/arvo/arvo-internals/gall.udon+4−6

@@ -535,7 +535,7 @@ when you run a command like `+ls` or `|merge`, there are no marks in

535sight.

536

537We've used generators before, back in [Basic

538−Operation](/docs/using/admin). At that point, we just used the

538+Operation](/docs/learn/arvo/arvo-internals/admin). At that point, we just used the

539generators to produce values -- we didn't pipe their results into apps.

540In the dojo cast, the role of a generator is to take a list of arguments

541and produce a value, which is often, though not always, piped into an

@@ -576,10 +576,8 @@ pattern is so common, this can be abbreviated to

576generators for the `:hood` app, `:hood|generator <args>` can be

577shortened to `|generator <args>`.

578

579−Let's write a generator for a modified version of `:pong` from

580−the chapter on [Network Messages](/docs/arvo/system/network). Recall

581−that `:pong` takes an urbit address, which is of mark `urbit`,

579+Let's write a generator called `:pong` that takes an urbit address, which is of

582−and sends that urbit the message `'howdy'`. First--without a

580+mark `urbit`, and sends that urbit the message `'howdy'`. First--without a

583generator--let's make `:ping` that does the same, except that

581generator--let's make `:ping` that does the same, except that

584it lets the user optionally specify the message as well.

582it lets the user optionally specify the message as well.

585

583

@@ -785,7 +783,7 @@ purl:eyre)`. Thus, the result is null if and only if the url is malformed.

785When you send this request, you can expect a `%sigh` with the

783When you send this request, you can expect a `%sigh` with the

786response, which we handle later on in `++sigh-httr`.

784response, which we handle later on in `++sigh-httr`.

787

785

788−For `%wait`, you just pass a [`@da`]() (absolute date), and arvo will

786+For `%wait`, you just pass a `@da` (absolute date), and arvo will

789produce a `%wake` when the time comes.

787produce a `%wake` when the time comes.

790

788

791> A timer is guaranteed to not be triggered before the given time, but it's currently impossible to guarantee the timer will be triggered at exactly the requested time.

789> A timer is guaranteed to not be triggered before the given time, but it's currently impossible to guarantee the timer will be triggered at exactly the requested time.

learn/arvo/arvo-internals/generators.udon+1−1

@@ -29,7 +29,7 @@ a

29

30This generator takes one argument of any noun and produces it without any

31changes. If we put this into a file named `echo.hoon` in the `/gen` directory,

32−we can run it from the [Dojo](/docs/using/shell):

32+we can run it from the [Dojo](/docs/learn/arvo/arvo-internals/shell):

33

34```

35> +echo 42

learn/arvo/arvo-internals/layout.udon+4−4

@@ -47,7 +47,7 @@ This is where the Arvo kernel lives. `sys/` contains:

47

48##### `sys/hoon.hoon`

49

50−[Hoon](../../tutorials/hoon-ch1) is our programming language. Since Hoon

50+[Hoon](/docs/learn/arvo/hoon) is our programming language. Since Hoon

51compiles itself, the language is actually specified in this source file.

52

53##### `sys/zuse.hoon`

@@ -104,9 +104,9 @@ That's it. That's the whole system.

104

105## app/

106

107−This is where [Gall](../../tutorials/gall) apps live. Gall apps are stateful

107+This is where [Gall](../gall) apps live. Gall apps are stateful

108servers, sort of like unix daemons. One familiar one is `app/hall.hoon` which is

109−the source code for [Hall](../../tutorials/hall), the Urbit messaging transport

109+the source code for [Hall](../hall), the Urbit messaging transport

110layer. And there's also `app/dojo.hoon` — that's your shell.

111

112---

@@ -167,7 +167,7 @@ lib/test/*

167## web/

168

169Here are files publicly accessible to the web, as made possible by

170−[Eyre](../web).

170+[Eyre](../eyre).

171

172---

173

learn/arvo/arvo-internals/messaging.udon+1−1

@@ -27,7 +27,7 @@ be used for that we haven't even thought of.

27

28Here we'll be discussing how to operate the default CLI frontend, Talk,

29to send and receive messages. For a more in-depth look at Hall's internals,

30−take a look at its [documentation](../../tutorials/hall).

30+take a look at its [documentation](../hall).

31

32## Quickstart

33

learn/arvo/arvo-internals/publishing.udon+2−2

@@ -43,7 +43,7 @@ Your urbit's web server can be accessed remotely at

43way, one that is generated by running the `+code` command in the Dojo.

44

45_(Make sure you have a desk mounted to unix, as covered in the

46−[setup section](/../../using/setup))._

46+[setup section](../filesystem/))._

47

48##### Serving

49

@@ -95,7 +95,7 @@ Let's continue our with our `test.udon` example. Create `/sandbox/web/test/` and

95add two more Udon files in `/sandbox/web/test/daughter.udon`

96`/sandbox/web/test/son.udon`, respectively. Make sure that they contain valid

97Udon. Udon is our markup language, similar to Markdown; check out the guide

98−[here](../../tutorials/).

98+[here](../udon/).

99

100> NOTE: Due to a bug in Urbit, you may have to create the directory and the file

101 in it in rapid succession using something like `mkdir sandbox/web/test && touch

learn/arvo/arvo-internals/sail.udon+2−2

@@ -497,8 +497,8 @@ see what its value is.

497

498The first line, `=+ wid=(met 3 p.bem.gas)`, combines a new noun with the

499subject and gives it the face `wid`. This noun is produced by the the

500−standard-library function [`met`](../reference/library/2c), which measures the number of

500+standard-library function [`met`](/docs/reference/library/2c), which measures the number of

501−[blocks](../reference/library/1c/) of size `a` within `b`. Blocks are units that have a

501+[blocks](/docs/reference/library/1c/) of size `a` within `b`. Blocks are units that have a

502bitwidth of `2^a`. So, in this case, it measures how many bytes (blocks of size

5033 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship's address.

504

learn/arvo/arvo-internals/shell.udon+3−3

@@ -37,7 +37,7 @@ Tall-form Hoon may require multiple lines:

37~your-urbit:dojo< 2

38```

39

40−Hoon uses something called [the subject](../../tutorials/hoon-ch1/hoon-ch1-3).

40+Hoon uses something called [the subject](/docs/learn/arvo/hoon/the-subject-and-its-legs).

41The Dojo has its own subject, and that's where Hoon's equivalent of variables,

42called faces, are stored.

43

@@ -59,7 +59,7 @@ Use `=dir` to set the current working directory:

59```

60

61(`%` represents your current directory. For a complete explanation on urbit

62−paths, see the [filesystem section](/docs/using/filesystem))

62+paths, see the [filesystem section](../filesystem))

63

64Generators (files in `/gen`) are run with `+`:

65

@@ -264,7 +264,7 @@ Apps usually expect marked data, so `&` is often used here.

264

265##### `*` - Save in `%clay`

266

267−Save a new `.udon` ([Udon](/docs/tutorials/udon)) file in `web`:

267+Save a new `.udon` ([Udon](../udon)) file in `web`:

268

269```

270~your-urbit:dojo> *%/web/foo/udon '# hello'

learn/arvo/arvo-internals/udon.udon+5−5

@@ -323,12 +323,12 @@ destination.

323*Example:*

324

325```

326−[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)

326+[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)

327```

328

329###### Produces:

330

331−[I'm an inline-style link](https://www.urbit.org/docs/hoon/library)

331+[I'm an inline-style link](https://www.urbit.org/docs/reference/shell)

332

333The second type is a reference-style link, which uses a relative path, based on

334the current page's location. Instead of the full url, we use `..` to fill in

@@ -337,14 +337,14 @@ the all of the URL that the destination has in common with the origin page.

337*Example:*

338

339```

340−[I'm a reference-style link](../library)

340+[I'm a reference-style link](../shell)

341```

342

343###### Produces:

344

345−[I'm a reference-style link](../library)

345+[I'm a reference-style link](../shell)

346

347−If this page is located at `https://www.urbit.org/docs/hoon/`, then these two

347+If this page is located at `https://www.urbit.org/docs/reference/`, then these two

348examples should have the same destination.

349

350#### Anchor Link

learn/arvo/hoon.udon+4−3

@@ -23,12 +23,13 @@ The first three lessons take you through a simple Hoon program, explain Hoon's s

23

24## Lessons

25

26−;list;

26+-

27

28## Other Resources

29

30−Consult the [Reference](/docs/reference) to look up any unknown rune or standard library function you don't understand.

30+Consult the [Reference section](/docs/reference/) to look up any unknown rune or standard library function you don't understand.

31+

32+As you work your way through these lessons you may want to work on example problems from the [Hoon workbook](link) for practice. Once you finish the lessons here you may want to write more versatile Hoon programs which can make use of more of your urbit's environment, in which case you'll want to check out the [Generators](/docs/learn/arvo/arvo-internals/generators) documentation. Or maybe you'd like to learn how to write a [Gall app](/docs/learn/arvo/arvo-internals/gall). Learn about [Udon](/docs/learn/arvo/arvo-internals/udon), Urbit's stripped down version of Markdown. Or learn [Sail](/docs/learn/arvo/arvo-internals/sail), a subset of Hoon used for generating XML nodes.

31

33

32−As you work your way through these lessons you may want to work on example problems from the [Hoon workbook](link) for practice. Once you finish the lessons here you may want to write more versatile Hoon programs which can make use of more of your urbit's environment, in which case you'll want to check out the [Generators](/docs/learn/arvo/arvo-internals/generators) documentation. Or maybe you'd like to learn how to write a [Gall app](link). Learn about [Udon](/docs/learn/arvo/arvo-internals/udon), Urbit's stripped down version of Markdown. Or learn [Sail](/docs/learn/arvo/arvo-internals/sail), a subset of Hoon used for generating XML nodes.

33

34

34> Last major revision of this section: December 2018

35> Last major revision of this section: December 2018

learn/arvo/hoon/arms-and-cores.udon+1−1

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'24'

4+ sort/'14'

5 title/'Arms and Cores'

6 ==

7;>

learn/arvo/hoon/atoms-auras-and-simple-cell-types.udon+3−3

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'30'

4+ sort/'24'

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

6 ==

7;>

8

9−# Atoms, Auras, and Simple Cell Types

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

10

11Like 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.

12

@@ -22,7 +22,7 @@ In this lesson we'll cover (1)-(4) as they pertain to atoms and simple cell type

22

23## Atoms and Auras

24

25−In [lesson 1.2](../hoon-ch1-2) we defined what an atom is: any unsigned integer. In this lesson we'll expand on that discussion, going over how Hoon's type system implements auras.

25+In [lesson 1.2](../nouns) we defined what an atom is: any unsigned integer. In this lesson we'll expand on that discussion, going over how Hoon's type system implements auras.

26

27In the most straightforward sense, atoms simply are unsigned integers. But they can also be interpreted as representing signed integers, ASCII symbols, floating-point values, dates, binary numbers, hexadecimal numbers, and more. Every atom is, in and of itself, just an unsigned integer; but Hoon keeps track of type information about each atom, and this info tells Hoon how to interpret the atom in question.

28

learn/arvo/hoon/cores-again.udon+3−3

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'34'

4+ sort/'26'

5 title/'Cores Again'

6 ==

7;>

8

9−# Cores Again

9+# 2.6 Cores Again

10

11In 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.

12

@@ -153,7 +153,7 @@ Another way to cast for the type of the parent core of an arm is to use `_+>.$`.

153

154But what does it mean? First, the `_` indicates the irregular form of the `$_` rune. That is, `_+>.$` evaluates `+>.$` and produces a type from the resulting noun.

155

156−What is `+>.$`? This is a wing of two limbs, `+>` and `$`. As you saw in [section 1.4](../hoon-ch1-4), `+>` is the lark syntax for `+7`, i.e., address space `7`. And `$` is the name of the lone arm in a gate. Whenever an arm name is used in a wing expression and isn't the left-most limb in the series, it evaluates to its parent core. The parent core of `$` is the gate itself.

156+What is `+>.$`? This is a wing of two limbs, `+>` and `$`. As you saw in [section 1.4](../arms-and-cores), `+>` is the lark syntax for `+7`, i.e., address space `7`. And `$` is the name of the lone arm in a gate. Whenever an arm name is used in a wing expression and isn't the left-most limb in the series, it evaluates to its parent core. The parent core of `$` is the gate itself.

157

158Thus, `+>.$` evaluates to `+7` of the gate containing `$`. For our `plus` arm, the gate in question is the one defined by:

159

learn/arvo/hoon/cores.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'33'

4+ sort/'27'

5 title/'Cores'

6 ==

7;>

8

9−# Cores

9+2.7 Cores

10

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

12

learn/arvo/hoon/examples.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'37'

4+ sort/'30'

5 title/'Examples'

6 ==

7;>

8

9−# Examples

9+# 2.10 Examples

10

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

12

learn/arvo/hoon/gates.udon+1−1

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'25'

4+ sort/'15'

5 title/'Gates (Hoon Functions)'

6 ==

7;>

learn/arvo/hoon/getting-started.udon+3−3

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'21'

4+ sort/'11'

5 title/'Getting Started'

6 ==

7;>

@@ -12,7 +12,7 @@ Before we begin working on Hoon you should first (1) have Urbit installed and (2

12

13## Installing Urbit

14

15−You can [install Urbit](../../../using/install/) on any Mac or Unix machine. On Windows, make a virtual Linux machine using VirtualBox or a similar tool.

15+You can [install Urbit](/docs/getting-started) on any Mac or Unix machine; follow the steps for creating a development ship. On Windows, make a virtual Linux machine using VirtualBox or a similar tool.

16

17Once you're finished you can boot your very own urbit.

18

@@ -26,7 +26,7 @@ For this tutorial you'll boot and run what we call a 'comet'. *Comets* are urbi

26

27`~hillyn-pitwet-hasdur-paswer--miszod-rabpex-divrup-fogdur`

28

29−Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network. Thus, comets make the ideal urbit for playing around with Hoon, asking for help from other Urbit devs in [Talk](../../using/messaging/) if you need it, and showing off Urbit to your friends.

29+Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network. Thus, comets make the ideal urbit for playing around with Hoon, asking for help from other Urbit devs in [Talk](/docs/arvo/arvo-internals/using/messaging/) if you need it, and showing off Urbit to your friends.

30

31## Booting a Comet

32

learn/arvo/hoon/hoon-programs.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'27'

4+ sort/'21'

5 title/'Hoon Programs'

6 ==

7;>

8

9−# Writing Hoon Programs

9+# 2.1 Writing Hoon Programs

10

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

12

learn/arvo/hoon/hoon-syntax.udon+7−7

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'28'

4+ sort/'22'

5 title/'Hoon Syntax'

6 ==

7;>

8

9−# Hoon Syntax

9+# 2.2 Hoon Syntax

10

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

12

@@ -93,7 +93,7 @@ We start with atom literals. Each of these is a basic expression of Hoon that e

930b1101.1001

94```

95

96−Recall from [lesson 1.2](../hoon-ch1-2) that even though atoms are unsigned integers, they can be pretty-printed in different ways. The way an atom is to be represented depends on its aura. The literal syntax for each of the hard-coded auras will be explained further in [lesson 2.4](../hoon-ch2-4).

96+Recall from [lesson 1.2](../nouns) that even though atoms are unsigned integers, they can be pretty-printed in different ways. The way an atom is to be represented depends on its aura. The literal syntax for each of the hard-coded auras will be explained further in [lesson 2.4](../atoms-auras-and-simple-cell-types).

97

98Cell literals can be written in Hoon using `[ ]`. Cell literals are complex, because other expressions are put inside the square brackets. Examples:

99

@@ -160,7 +160,7 @@ Expressions with a rune at the beginning are rune expressions. Most runes are u

160

161Runes are classified by family (with the exceptions of `--` and `==`). The first of the two symbols indicates the family -- e.g., the `^-` rune is in the `^` family of runes, and the `|=` and `|%` runes are in the `|` family. The runes of particular family usually have related meanings. Two simple examples: the runes in the `|` family are all used to create cores, and the runes in the `:` family are all used to create cells.

162

163−Rune expressions are usually complex, which means they usually have one or more subexpressions. The appropriate syntax varies from rune to rune; after all, they're used for different purposes. To see the syntax rules for a particular rune, consult the [rune reference](../../../reference/rune). Nevertheless, there are some general principles that hold of all rune expressions.

163+Rune expressions are usually complex, which means they usually have one or more subexpressions. The appropriate syntax varies from rune to rune; after all, they're used for different purposes. To see the syntax rules for a particular rune, consult the [rune reference](/docs/reference/hoon-expressions/rune). Nevertheless, there are some general principles that hold of all rune expressions.

164

165#### Tall and Flat Forms

166

@@ -264,7 +264,7 @@ The irregular `( )` gate-calling syntax is versatile -- it is also a shortcut fo

264

265The `( )` gate-calling syntax can be used for gates of any other [arity](https://en.wikipedia.org/wiki/Arity) as well.

266

267−You've already seen two other irregular forms. In [lesson 1.5](../hoon-ch1-5), you made a gate that takes an atom `a` for its sample and returns `a + 1`: `|=(a=@ (add 1 a))`. This expression uses the `|=` rune in flat form.

267+You've already seen two other irregular forms. In [lesson 1.5](../gates), you made a gate that takes an atom `a` for its sample and returns `a + 1`: `|=(a=@ (add 1 a))`. This expression uses the `|=` rune in flat form.

268

269```

270> =inc |=(a=@ (add 1 a))

@@ -308,7 +308,7 @@ The `a=15` expression is the irregular form of `^=(a 15)`:

30835

309```

310

311−You can find other irregular forms in the irregular expression [reference document](../../../reference/irregular).

311+You can find other irregular forms in the irregular expression [reference document](/docs/reference/irregular).

312

313### Expressions That Are Only Irregular

314

@@ -349,7 +349,7 @@ b=[16 18]

349[16 18]

350```

351

352−To see other irregular expressions, check the irregular expression [reference document](../../../reference/irregular).

352+To see other irregular expressions, check the irregular expression [reference document](docs/reference/irregular).

353

354## Hoon Style

355

learn/arvo/hoon/lists.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'35'

4+ sort/'28'

5 title/'Standard Library: Lists'

6 ==

7;>

8

9−# Standard Library: Lists

9+# 2.8 Standard Library: Lists

10

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

12

learn/arvo/hoon/multi-gate-cores-and-doors.udon+1−1

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'26'

4+ sort/'16'

5 title/'Multi-gate Cores and Doors'

6 ==

7;>

learn/arvo/hoon/nouns.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'22'

4+ sort/'12'

5 title/'Nouns'

6 ==

7;>

@@ -290,7 +290,7 @@ You can force Hoon to interpret an atom differently by using the aura symbols in

290

291The atoms in the examples above are all exactly the same value. Only they're interpreted and printed differently, depending on the aura.

292

293−You'll learn more about atoms and auras in [lesson 2.4](../hoon-ch2-4).

293+You'll learn more about atoms and auras in [lesson 2.4](../atoms-auras-and-simple-cell-types.udon).

294

295## Cells

296

learn/arvo/hoon/simple-one-gate-programs.udon+6−6

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'29'

4+ sort/'23'

5 title/'Simple One-Gate Programs'

6 ==

7;>

8

9−# Simple One-Gate Programs

9+# 2.3 Simple One-Gate Programs

10

11−In 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](../hoon-ch1-5).)

11+In 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).)

12

13For 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.

14

@@ -20,7 +20,7 @@ Let's look at a really simple gate: `|=(a=@ 15)`. This gate takes any atom as i

20

21The `|=` rune takes two subexpressions. The first must indicate a type, and the second may evaluate to any value. The first defines the gate's sample type and possibly binds a face to it, and the second defines the output of the gate. In the example `|=(a=@ 15)` the `|=` subexpressions are `a=@` and `15`.

22

23−The following characters represent basic Hoon types: `@` for atoms, `^` for cells, `?` for flags, and `*` for nouns. You should already know what atoms, cells, and nouns are. (See [lesson 1.2](../hoon-ch1-2) if you need a reminder.) There are two values for the `?` type: `%.y` for yes, and `%.n` for no. In other words, `?` is for the [Boolean values](https://en.wikipedia.org/wiki/Boolean_data_type) of Hoon.

23+The following characters represent basic Hoon types: `@` for atoms, `^` for cells, `?` for flags, and `*` for nouns. You should already know what atoms, cells, and nouns are. (See [lesson 1.2](../nouns) if you need a reminder.) There are two values for the `?` type: `%.y` for yes, and `%.n` for no. In other words, `?` is for the [Boolean values](https://en.wikipedia.org/wiki/Boolean_data_type) of Hoon.

24

25You could have picked a different type for the first subexpression of `|=(a=@ 15)` and left off the face. To illustrate this let's call different versions of the gate with the `(gate arg)` function call syntax:

26

@@ -630,7 +630,7 @@ The `$( )` syntax is an irregular form of the the `%=` rune. We can rewrite tha

630

631This version is precisely equivalent to the old one. The first `%=` subexpression is for a wing. In the program above, this is just `$`. The other subexpressions of `%=` indicate the changes to be made upon resolution to the wing. You can make as many of these changes as desired when using `%=`, so the expression is ended with `==`.

632

633−Remember from lessons [1.4](../hoon-ch1-4) and [1.5](../hoon-ch1-5) that wing resolution works in two different ways. If the wing resolves to a leg, that fragment of the subject is returned. If the wing resolves to an arm, the arm is evaluated with its parent core as the subject. In [lesson 1.5](../hoon-ch1-5) you learned that `$` is the special name of the arm of a gate. (Remember, a gate is a one-armed core with a sample.) Because we wrote `add.hoon` with `|=` it produces a gate. The `%=` expression above thus evaluates the `$` arm of the gate, but only after having made changes to the parent core: `a` is incremented, and `b` is decremented.

633+Remember from lessons [1.4](../arms-and-cores) and [1.5](../gates) that wing resolution works in two different ways. If the wing resolves to a leg, that fragment of the subject is returned. If the wing resolves to an arm, the arm is evaluated with its parent core as the subject. In [lesson 1.5](../gates) you learned that `$` is the special name of the arm of a gate. (Remember, a gate is a one-armed core with a sample.) Because we wrote `add.hoon` with `|=` it produces a gate. The `%=` expression above thus evaluates the `$` arm of the gate, but only after having made changes to the parent core: `a` is incremented, and `b` is decremented.

634

635### Decrement

636

@@ -732,7 +732,7 @@ Write a program that takes a number `n` and returns `%.y` if it's prime, and `%.

732

733Let's write a Hoon implementation of [FizzBuzz](https://en.wikipedia.org/wiki/Fizz_buzz). Fizzbuzz takes some number `n` and then makes a list of numbers from `1` to `n`, except that numbers evenly divisible by `3` are replaced with 'Fizz', numbers evenly divisible by `5` are replaced with 'Buzz', and numbers evenly divisible by both are replaced with 'FizzBuzz'.

734

735−You already saw a program that produces a list of atoms from `1` to `n` in [lesson 2.1](../hoon-ch2-1), `listnum.hoon`:

735+You already saw a program that produces a list of atoms from `1` to `n` in [lesson 2.1](../hoon-programs), `listnum.hoon`:

736

737```

738|= end=@ :: 1

learn/arvo/hoon/structures-and-complex-types.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'32'

4+ sort/'25'

5 title/'Structures and Complex Types'

6 ==

7;>

8

9−# Structures and Complex Types

9+# 2.5 Structures and Complex Types

10

11In 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.

12

learn/arvo/hoon/the-subject-and-its-legs.udon+1−1

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'23'

4+ sort/'13'

5 title/'The Subject and Its Legs'

6 ==

7;>

learn/arvo/hoon/trees-sets-and-maps.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'36'

4+ sort/'29'

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

6 ==

7;>

8

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

9+# 2.9 Hoon Standard Library: Trees, Sets, and Maps

10

11Along 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.

12

learn/arvo/hoon/type-checking-and-type-inference.udon+2−2

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'31'

4+ sort/'24'

5 title/'Type Checking and Type Inference'

6 ==

7;>

8

9−# Type Checking and Type Inference

9+# 2.4 Type Checking and Type Inference

10

11As 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.

12

learn/arvo/hoon/type-polymorphism.udon+2−2

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

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

2 navuptwo/'true'

3− sort/'38'

3+ sort/'31'

4 title/'Type Polymorphism'

5 ==

6;>

7

8−# Polymorphism

8+# 3.1 Polymorphism

9

10There 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.)

11

learn/arvo/vere/jetting.udon+1−1

@@ -502,7 +502,7 @@ First, you may need to massage your inputs a bit to get them into types that you

502

503You have received a bunch of `u3_nouns` or `u3_atoms`, but you presumably want to do things in a native C / non-Hoon manner: computing w raw integers, etc.

504

505−A `u3_noun` will want to be further diassembled into atoms.

505+A `u3_noun` will want to be further disassembled into atoms.

506

507A `u3_atom` represents a simple number, but the implementation may or

508may not be simple. If the value held in the atom is 31 bits or less,

learn/azimuth/blockchain.udon+2−2

@@ -45,5 +45,5 @@ computation Landscape the latter is not. We need a computational blockchain to

45enforce the specific rules of the Urbit identity registry.

46

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

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

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

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

49+[two](urbit.org/posts/updates/2017.9.20-bootstrapping-urbit-from-ethereum) posts.

reference.udon+9

@@ -7,3 +7,12 @@

7# Reference

8

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

10+

11+## [The Glossary](/docs/reference/glossary)

12+

13+Urbit is known for introducing a great deal of new terminology. The glossary will

14+help demystify our jargon.

15+

16+## [The Cheat Sheet](/docs/reference/cheat-sheet)

17+

18+The cheat sheet compact document for looking up Hoon expressions.

reference/cheat-sheet.udon+1−1

@@ -20,7 +20,7 @@ hand. So above is a download link to a Hoon cheatsheet .pdf. It's missing a

20few of the literal syntaxes, but it covers the most common ones.

21

22This doesn't list any of the Ford runes, although there is now at least

23−some documentation for those [here](../../tutorials/internals/ford/runes).

23+some documentation for those [here](/docs/learn/arvo/arvo-internals/ford#runes).

24

25The following runes also exist, but are currently undocumented and not listed in

26the cheat sheet:

reference/glossary.udon+2−3

@@ -712,8 +712,7 @@ number of bits in their address:

712Any ship can be called an _urbit_. The lowercase "u" distinguishes it from Urbit

713the software stack and Urbit the network.

714

715−_You can find a longer-form summary here:

715+_You can find a longer-form summary [here.](https://urbit.org/posts/essays/the-urbit-address-space/)._

716−[`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/)._

717

716

718An Urbit identity is a string like `~firbyr-napbes`. It means nothing,

717An Urbit identity is a string like `~firbyr-napbes`. It means nothing,

719but it's easy to remember and say out loud. `~firbyr-napbes` is actually

718but it's easy to remember and say out loud. `~firbyr-napbes` is actually

@@ -880,7 +879,7 @@ of the simpler built-in types.

880 error. This is one of the most commons errors in Hoon programming.

879 error. This is one of the most commons errors in Hoon programming.

881

880

882 _See [advanced types](/docs/reference/hoon-expressions/advanced/)_.

881 _See [advanced types](/docs/reference/hoon-expressions/advanced/)_.

883− _See [troubleshooting](/docs/reference/hoon-expressions/troubleshooting)_.

882+ _See [troubleshooting](/docs/reference/troubleshooting)_.

884

883

885

884

886### Unit

885### Unit

reference/hoon-expressions/advanced.udon+5

@@ -119,6 +119,11 @@ A lead core `a` has an opaque payload. There is no constraint on

119the payload of a core `b` which nests within it. Hence,

120*bivariant*.

121

122+(_Opaque_ here means that the faces and arms are not exported into

123+the namespace, and that the values of faces and arms can't be written to.

124+The object in question can be replaced by something else without breaking type

125+safety.)

126+

122An iron core `a` has a write-only sample (payload head, `+6.a`)

127An iron core `a` has a write-only sample (payload head, `+6.a`)

123and an opaque context (payload tail, `+7.a`). A core `b` which

128and an opaque context (payload tail, `+7.a`). A core `b` which

124nests within it must be a gold or iron core, such that `+6.a`

129nests within it must be a gold or iron core, such that `+6.a`

reference/hoon-expressions/irregular.udon−2

@@ -8,8 +8,6 @@

8

9##### `~palfun-foslup`

10

11−*Original Fora post* [here](https://urbit.org/fora/posts/~2016.12.29..19.37.08..89d5~/).

12−

13##### Reading guide

11##### Reading guide

14

12

15Headings contain runes, phonetics and tokens. Description contains a link to the docs and a short description of the rune. Both regular (R) and irregular (I) forms are given.

13Headings contain runes, phonetics and tokens. Description contains a link to the docs and a short description of the rune. Both regular (R) and irregular (I) forms are given.

reference/library/2e.udon+1−1

@@ -12,7 +12,7 @@

12FNV scrambler

13

14Hashes an atom with the 32-bit FNV non-cryptographic hash algorithm. Multiplies

15−`a` by the prime number 16,777,619 and then takes the [block](../2c.md) of size

15+`a` by the prime number 16,777,619 and then takes the [block](../2c) of size

165 off the product's end, producing an atom.

17

18#### Accepts

reference/library/2o.udon+1−1

@@ -81,7 +81,7 @@ Mold generator. A `jug` is a `map` of `set`.

81

82#### Discussion

83

84−See also: [`ja`](../2j), [`by`](../2i), [`map`](../2i), [`set`](..2h)

84+See also: [`ja`](../2j), [`by`](../2i), [`set`](../2h)

85

86---

87### `++map`

reference/library/3g.udon+4−4

@@ -55,9 +55,9 @@ and printed using `++so` and `++co` cores.

55

56Aura-atom pair

57

58−Used in `++coin`. Convenience methods [`++scot`](../4m.md) and

58+Used in `++coin`. Convenience methods [`++scot`](../4m) and

59−[`++scow`](../4m.md) print dimes as `++cord` and `++tape`, respectively.

59+[`++scow`](../4m) print dimes as `++cord` and `++tape`, respectively.

60−[`++slat`](../4m.md), [`++slav`](../4m.md), and [`++slaw`](../4m.md) are used

60+[`++slat`](../4m), [`++slav`](../4m), and [`++slaw`](../4m) are used

61to parse atoms of specific auras.

62

63#### Source

@@ -98,7 +98,7 @@ Optional result `p` and parsing continuation `q`.

98

99#### Discussion

100

101−See also: [Section 2e](../2e.md), `++rule`

101+See also: [Section 2e](../2e), `++rule`

102

103

104---

reference/troubleshooting.udon+6−6

@@ -22,7 +22,7 @@ a correct Hoon file. These values are always correct.

22Usually, the line and column tell you everything you need to

23know. But the worst-case scenario for a syntax error is that,

24somewhere above, you've confused Hoon's tall form by using the

25−wrong fanout for a rune. For example, `%+` ([*cenlus*](../rune/cen/lus),

25+wrong fanout for a rune. For example, `%+` ([*cenlus*](/docs/reference/hoon-expressions/rune/cen#cenlus),

26a function call whose sample is a cell) has three subhoons:

27

28```

@@ -102,7 +102,7 @@ means you tried to pound a square peg into a round hole.

102What was the peg and what was the hole? Hoon doesn't tell you by

103default, because moral fiber, and also because in too many cases

104trivial errors lead to large intimidating dumps. However, you

105−can use the `~!` rune ([*sigzap*](../rune/sig/zap)) to print the type of

105+can use the `~!` rune ([*sigzap*](/docs/reference/hoon-expressions/rune/sig#sigzap)) to print the type of

106any hoon in your stack trace.

107

108For instance, you wrote `(foo bar)` and got a `nest-fail`. Change

@@ -132,7 +132,7 @@ function.

132

133These are errors caused by type inference in pattern matching.

134`mint-vain` means this hoon is never executed. `mint-lost` means

135−there's a case in a `?-` ([*wuthep*](../rune/wut/hep)) that isn't handled.

135+there's a case in a `?-` ([*wuthep*](/docs/reference/hoon-expressions/rune/wut#wuthep)) that isn't handled.

136

137## Runtime crashes

138

@@ -146,7 +146,7 @@ infinite loop will time out either too slowly or too fast). The

146stack trace will show what your code was doing when interrupted.

147

148The counterpart of `~!` for runtime crashes is `~|`

149−([*sigbar*](../rune/sig/bar)):

149+([*sigbar*](/docs/reference/hoon-expressions/rune/sig#sigbar)):

150

151```

152~| foo

@@ -162,7 +162,7 @@ The worst possibility, of course, is that your code runs but does

162the wrong thing. This is relatively unusual in a typed

163functional language, but it still happens.

164

165−`~&` ([*sigpad*](../rune/sig/pad)) is Hoon's debugging printf.

165+`~&` ([*sigpad*](/docs/reference/hoon-expressions/rune/sig#sigpad)) is Hoon's debugging printf.

166This pretty-prints its argument:

167

168```

@@ -171,7 +171,7 @@ This pretty-prints its argument:

171```

172

173will always print `foo` every time it executes. A variant is

174−`~?` ([*sigwut*](../rune/sig/wut)), which prints only if a condition is

174+`~?` ([*sigwut*](/docs/reference/hoon-expressions/rune/sig#sigwut)), which prints only if a condition is

175true:

176

177```